Agent 클래스

Agent 클래스는 재구성된 음성 방법, 업데이트된 속성 액세스 패턴 및 간소화된 스트리밍 API로 업데이트되었습니다.

변경됨

getAgents에게listAgents

mastra.getAgents() 메서드의 이름이 mastra.listAgents()로 변경되었습니다. 이 변경은 여러 항목을 가져오는 getter 메서드에 list 접두사를 사용하는 API 전반의 명명 규칙과 일치합니다. 마이그레이션하려면 모든 mastra.getAgents() 호출을 mastra.listAgents()로 바꾸세요.

- const agents = mastra.getAgents();
+ const agents = mastra.listAgents();

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npm

npx @mastra/codemod@latest v1/mastra-plural-apis .

pnpm

pnpm dlx @mastra/codemod@latest v1/mastra-plural-apis .

Yarn

yarn dlx @mastra/codemod@latest v1/mastra-plural-apis .

Bun

bun x @mastra/codemod@latest v1/mastra-plural-apis .

:::

RuntimeContext에게RequestContext

코드베이스 전반에서 RuntimeContext 클래스의 이름이 RequestContext로 변경되었습니다. 새 이름은 이 클래스가 요청별 데이터를 나타낸다는 점을 명확히 하고 웹 프레임워크의 규칙과도 일치합니다. 마이그레이션하려면 모든 RuntimeContext/runtimeContext 가져오기와 매개변수 이름을 RequestContext/requestContext로 업데이트하세요.

- import { RuntimeContext } from '@mastra/core/runtime-context';
+ import { RequestContext } from '@mastra/core/request-context';

- const runtimeContext = new RuntimeContext();
- runtimeContext.set('userTier', 'enterprise');
+ const requestContext = new RequestContext();
+ requestContext.set('userTier', 'enterprise');

- await agent.generate(messages, { runtimeContext });
+ await agent.generate(messages, { requestContext });

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/runtime-context .

:::

getter 메서드에 대한 직접 속성 액세스

agent.llm, agent.tools, agent.instructions 속성에 직접 접근하는 방식은 더 이상 사용되지 않습니다. 이 변경으로 캡슐화가 개선되고 더 광범위한 API 설계와의 일관성이 높아집니다. 마이그레이션하려면 속성 액세스를 해당 getter 메서드로 바꾸세요.

- const llm = agent.llm;
- const tools = agent.tools;
- const instructions = agent.instructions;
+ const llm = agent.getLLM();
+ const tools = agent.getTools();
+ const instructions = agent.getInstructions();

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/agent-property-access .

:::

음성 방식이 다음으로 이동되었습니다.agent.voice namespace

음성 관련 메서드가 Agent 클래스에서 agent.voice 네임스페이스로 이동하여 음성 API가 한곳에 모였습니다. 마이그레이션하려면 음성 방법 호출을 업데이트하여agent.voice namespace.

- await agent.speak('Hello');
- await agent.listen();
- const speakers = agent.getSpeakers();
+ await agent.voice.speak('Hello');
+ await agent.voice.listen();
+ const speakers = agent.voice.getSpeakers();

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/agent-voice .

:::

agent.fetchMemory()에게(await agent.getMemory()).recall()

fetchMemory() 메서드는 비동기 Memory 접근을 명시적으로 나타내는 API로 대체되었습니다. 마이그레이션하려면 fetchMemory() 호출을 새 API로 바꾸세요.

- const messages = await agent.fetchMemory({ threadId: 'thread-123' });
+ const memory = await agent.getMemory();
+ const result = await memory.recall({ threadId: 'thread-123' });
+ const messages = result.messages;

프로세서 메서드 이름을 get*에서 list*로 변경

더 광범위한 API와의 일관성을 위해 Agent 프로세서 메서드의 명명 패턴이 get*에서 list*로 변경되었습니다. 이 변경은 컬렉션을 반환하는 메서드에 list*를 사용하는 규칙과 일치합니다. 마이그레이션하려면 프로세서 메서드 이름을 업데이트하세요.

- const inputProcessors = await agent.getInputProcessors(runtimeContext);
- const outputProcessors = await agent.getOutputProcessors(runtimeContext);
+ const inputProcessors = await agent.listInputProcessors(requestContext);
+ const outputProcessors = await agent.listOutputProcessors(requestContext);

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/agent-processor-methods .

:::

Zod v3 및 v4 구조화된 출력 스키마는 계속 지원됩니다.

Mastra v1은 구조화된 출력 스키마를 사용하는 공개 Agent API에서 Zod v3 및 Zod v4 스키마를 모두 계속 지원합니다. 여기에는 agent.generateLegacy(), agent.streamLegacy() 메서드와 관련 옵션 타입이 포함됩니다. 이미 Zod 스키마를 Agent API에 전달한 경우 Zod 버전 호환성을 위해 마이그레이션이 필요하지 않습니다. 기존 스키마 가져오기를 유지합니다.

import { z as z3 } from 'zod/v3'
import { z as z4 } from 'zod/v4'

await agent.generateLegacy({
  prompt: 'Summarize this ticket',
  output: z3.object({ summary: z3.string() }),
})

await agent.streamLegacy({
  prompt: 'Extract contact info',
  output: z4.object({ email: z4.string().email() }),
})

애플리케이션 전체에서 하나의 Zod 버전으로 표준화하려는 경우에만 가져오기를 업데이트하세요.

AI SDK 버전의 기본 옵션 메서드 이름 변경

레거시(AI SDK v4) API와 AI SDK v5+ API를 구별하기 위해 기본 옵션 메서드의 이름이 변경되었습니다. 이제 메서드 이름은 대상으로 하는 AI SDK 버전을 나타냅니다.

마이그레이션하려면 사용 중인 AI SDK 버전에 따라 메서드 이름을 업데이트하세요.

  // For legacy AI SDK v4
- const options = await agent.getDefaultGenerateOptions();
- const streamOptions = await agent.getDefaultStreamOptions();
+ const options = await agent.getDefaultGenerateOptionsLegacy();
+ const streamOptions = await agent.getDefaultStreamOptionsLegacy();

  // For new AI SDK v5+ (default)
  const streamOptions = await agent.getDefaultStreamOptions();

modelSettings.abortSignal최상위 수준으로abortSignal

abortSignal 옵션이 modelSettings에서 스트림 및 생성 옵션의 최상위 수준으로 이동했습니다. 이제 실행 제어는 Model별 설정 외부에 위치합니다. 마이그레이션하려면 abortSignal을 modelSettings에서 최상위 수준으로 이동하세요.

  agent.stream('Hello', {
-   modelSettings: {
-     abortSignal: abortController.signal,
-   },
+   abortSignal: abortController.signal,
  });

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/agent-abort-signal .

:::

output에게structuredOutput.schema

더 이상 사용되지 않는 output 및 experimental_output 옵션이 제거되었습니다. 이 변경으로 구조화된 출력에 하나의 안정적인 API만 사용하게 됩니다. 마이그레이션하려면 output 또는 experimental_output을 structuredOutput.schema으로 업데이트하세요.

  agent.stream('Hello', {
-   output: z.object({ result: z.string() }),
+   structuredOutput: {
+     schema: z.object({ result: z.string() }),
+   },
  });

Agent의 id 필드가 이제 필수

이제 Agent를 생성할 때 id 필드가 필요합니다. 이전에는 명시적인 ID 없이 Agent를 생성할 수 있었지만 더 이상 지원되지 않습니다. 마이그레이션하려면 모든 Agent 구성에 id 필드를 추가하세요.

  const agent = new Agent({
+   id: 'my-agent',
    name: 'My Agent',
    instructions: 'You are a helpful assistant',
    model: 'openai/gpt-5.6-sol',
  });

id는 name과 같아도 되고 다른 식별자를 사용해도 됩니다. ID는 mastra.getAgentById()를 호출할 때 사용되며 Mastra 인스턴스 내에서 고유해야 합니다.

// Register agent with Mastra
const mastra = new Mastra({
  agents: {
    myAgent: agent, // key can differ from id
  },
})

// Retrieve by ID
const agent = mastra.getAgentById('my-agent')

Stream API 응답은 이제 민감한 데이터를 수정합니다.

이제 Mastra 서버는 Agent 스트림 응답에서 민감한 정보를 자동으로 삭제합니다. 이를 통해 시스템 Prompt, Tool 정의 및 API 키가 step-start, step-finish, finish 스트림 청크에서 실수로 노출되는 것을 방지합니다. 수정된 내용:

• request.bodyLLM 요청 페이로드 포함(시스템 Prompt, Tool 스키마)
• metadata.request단계 결과
• output.steps[].request중첩된 단계 데이터에서

이 동작은 기본적으로 활성화되어 있습니다. 전체 요청 데이터에 접근해야 하는 경우(예: 디버깅 또는 내부 서비스) @mastra/hono 또는 @mastra/express와 같은 서버 어댑터를 직접 사용할 때 정보 삭제를 비활성화할 수 있습니다.

제거됨

generateVNext그리고streamVNext methods

더 이상 사용되지 않는 generateVNext() 및 streamVNext() 메서드가 제거되었습니다. 이전에는 AI SDK v5+ 호환성을 위해 사용되었지만, 이제 해당 구현이 표준입니다. 마이그레이션하려면 표준 generate() 및 stream() 메서드를 사용하세요.

- const result = await agent.generateVNext('Hello');
- const stream = await agent.streamVNext('Hello');
+ const result = await agent.generate('Hello');
+ const stream = await agent.stream('Hello');

:::tip[코드모드]

Mastra의 codemod CLI를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

npx @mastra/codemod@latest v1/agent-generate-stream-v-next .

:::

stream() 및 generate()의 format 매개변수

agent.stream() 및 agent.generate() 메서드에서 format 매개변수가 제거되었습니다. 이제 AI SDK 스트림 변환은 @mastra/ai-sdk 패키지에서 처리합니다. 이 변경은 AI SDK 전용 코드를 별도 패키지로 이동하여 트리 셰이킹을 개선합니다. 마이그레이션하려면 AI SDK 형식 변환에 @mastra/ai-sdk의 toAISdkStream() 함수를 사용하세요.

- const stream = await agent.stream(messages, {
-   format: 'aisdk',
- });

+ import { toAISdkStream } from '@mastra/ai-sdk';
+ 
+ const stream = await agent.stream(messages);
+ const aiSdkStream = toAISdkStream(stream, { from: 'agent' });

agent.toStep()방법

Agent 클래스에서 toStep() 메서드가 제거되었습니다. 이제 명시적으로 변환하지 않고도 Agent를 Workflow 단계에 직접 추가할 수 있습니다. 마이그레이션하려면 Workflow 단계에 Agent를 직접 추가하세요. Workflow는 변환을 자동으로 처리합니다.

- const step = agent.toStep();
- const workflow = new Workflow({
-   steps: [step],
- });

+ const workflow = new Workflow({
+   steps: [agent],
+ });

TMetricsAgent의 일반 매개변수

AgentConfig와 Agent 생성자에서 TMetrics 제네릭 매개변수가 제거되었습니다. 이제 메트릭과 채점기는 Agent 타입 시스템의 일부가 아니라 채점기 API를 사용해 구성합니다. 마이그레이션하려면 TMetrics 제네릭 매개변수를 제거하고 새 API를 사용해 채점기를 구성하세요.

- const agent = new Agent<AgentId, Tools, Metrics>({
+ const agent = new Agent<AgentId, Tools>({
    // ...
  });

Tripwire 응답 형식이 변경되었습니다.

트립와이어 응답 형식이 별도의 tripwire 및 tripwireReason 필드에서 모든 관련 데이터를 포함하는 단일 tripwire 객체로 변경되었습니다. 마이그레이션하려면 새 개체 구조에서 인계철선 데이터에 액세스하도록 코드를 업데이트하세요.

  const result = await agent.generate('Hello');

- if (result.tripwire) {
-   console.log(result.tripwireReason);
- }
+ if (result.tripwire) {
+   console.log(result.tripwire.reason);
+   // New fields available:
+   // result.tripwire.retry - whether this step should be retried
+   // result.tripwire.metadata - additional metadata from the processor
+   // result.tripwire.processorId - which processor triggered the tripwire
+ }

스트리밍 응답의 경우:

  for await (const chunk of stream.fullStream) {
    if (chunk.type === 'tripwire') {
-     console.log(chunk.payload.tripwireReason);
+     console.log(chunk.payload.reason);
+     // New fields available:
+     // chunk.payload.retry
+     // chunk.payload.metadata
+     // chunk.payload.processorId
    }
  }

이제 단계 결과에는 트립와이어 정보도 포함됩니다.

  const result = await agent.generate('Hello');

  for (const step of result.steps) {
-   // No tripwire info on steps
+   if (step.tripwire) {
+     console.log('Step was blocked:', step.tripwire.reason);
+   }
  }

prepareStep메시지 형식

이제 prepareStep 콜백은 AI SDK v5+ Model 메시지 형식 대신 MastraDBMessage 형식의 메시지를 받습니다. 이 변경으로 prepareStep은 에이전틱 루프의 각 단계에서 실행되는 새 processInputStep 프로세서 메서드와 통일됩니다. 이전 AI SDK v5+ 형식이 필요한 경우 다음을 사용하세요.messageList.get.all.aiV5.model():

  agent.generate('Hello', {
    prepareStep: async ({ messages, messageList }) => {
-     // messages was AI SDK v5+ ModelMessage format
-     console.log(messages[0].content);
+     // messages is now MastraDBMessage format
+     // Use messageList to get AI SDK v5+ format if needed:
+     const aiSdkMessages = messageList.get.all.aiV5.model();

      return { toolChoice: 'auto' };
    },
  });

threadId 및 resourceId를 memory 옵션으로 이동

agent.stream() 및 agent.generate()에서 threadId와 resourceId 옵션이 제거되었습니다. 대신 Memory 구성을 위한 더 깔끔한 API를 제공하는 memory 옵션을 사용하세요. 마이그레이션하려면 threadId와 resourceId를 memory 옵션 안으로 이동하세요.

  await agent.stream('Hello', {
-   threadId: 'thread-123',
-   resourceId: 'user-456',
+   memory: {
+     thread: 'thread-123',
+     resource: 'user-456',
+   },
  });

새 스레드를 생성할 때 memory 옵션으로 스레드 메타데이터를 전달할 수도 있습니다.

await agent.stream('Hello', {
  memory: {
    thread: {
      id: 'thread-123',
      title: 'Support conversation',
      metadata: { category: 'billing' },
    },
    resource: 'user-456',
  },
})