> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# Agent 클래스

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

## 변경됨

### `getAgents`에게`listAgents`

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

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

:::tip\[코드모드]

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

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

:::

### `RuntimeContext`에게`RequestContext`

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

```diff
- 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를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

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

:::

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

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

```diff
- 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를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

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

:::

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

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

```diff
- 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를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

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

:::

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

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

```diff
- 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*`를 사용하는 규칙과 일치합니다. 마이그레이션하려면 프로세서 메서드 이름을 업데이트하세요.

```diff
- 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를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

```bash
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 버전 호환성을 위해 마이그레이션이 필요하지 않습니다. 기존 스키마 가져오기를 유지합니다.

```ts
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 버전에 따라 메서드 이름을 업데이트하세요.

```diff
// 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`에서 최상위 수준으로 이동하세요.

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

:::tip\[코드모드]

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

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

:::

### `output`에게`structuredOutput.schema`

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

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

### Agent의 `id` 필드가 이제 필수

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

```diff
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 인스턴스 내에서 고유해야 합니다.

```typescript
// 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.body`LLM 요청 페이로드 포함(시스템 Prompt, Tool 스키마)
- `metadata.request`단계 결과
- `output.steps[].request`중첩된 단계 데이터에서

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

## 제거됨

### `generateVNext`그리고`streamVNext` methods

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

```diff
- 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를 사용하여 코드를 자동으로 업데이트할 수 있습니다.

```bash
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()` 함수를 사용하세요.

```diff
- 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는 변환을 자동으로 처리합니다.

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

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

### `TMetrics`Agent의 일반 매개변수

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

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

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

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

```diff
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
+ }
```

스트리밍 응답의 경우:

```diff
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
    }
  }
```

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

```diff
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()`:

```diff
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` 옵션 안으로 이동하세요.

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

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

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