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

# Workflow\.Agent()

그만큼`.agent()`메서드는 선언적 단계로 Agent를 추가합니다. 단계는 수락합니다`{ prompt: string }`입력 및 반환으로`{ text: string }`기본적으로. 사용`.map()`Workflow 데이터에서 Prompt를 작성하기 위해 Agent보다 먼저.

Agent를 `createStep()`으로 감싸는 방식과 달리 `.agent()`는 Workflow 그래프에 선언적 항목을 기록합니다. 따라서 Workflow를 이식할 수 있습니다. 동일한 그래프를 직렬화하고 [동적 Workflow](https://mastra.zisheng.pro/ko/docs/workflows/dynamic-workflows)로 영구 저장할 수 있습니다.

## 사용예

```typescript
workflow
  .map({ prompt: mapVariable({ initData: workflow, path: "topic" }) })
  .agent(testAgent)
  .commit();
```

## 매개변수

**agentOrId** (`Agent | string`): Agent 인스턴스 또는 Mastra 인스턴스에 등록된 Agent의 ID입니다. ID를 전달하면 실행 시 레지스트리에서 Agent를 확인합니다.

**options** (`AgentStepOptions & { structuredOutput?: { schema }, retries?: number, scorers?: DynamicArgument<MastraScorers>, metadata?: StepMetadata }`): maxSteps, modelSettings, memory, providerOptions와 같은 Agent 호출 옵션과 단계 수준의 retries, scorers, metadata입니다. requestContext, resourceId, threadId, onStepFinish와 같은 요청별 필드는 Workflow 엔진에서 관리하므로 제외됩니다.

**stepOptions** (`{ id?: string }`): Workflow 내 단계의 호출 지점 ID입니다. 기본값은 Agent의 ID입니다. 하나의 Workflow에 동일한 Agent가 두 번 이상 나타날 때 설정하세요.

## 보고

**workflow** (`Workflow`): 메서드 체이닝을 위한 Workflow 인스턴스입니다

## 구조화된 출력

기본적으로 단계의 출력은 `{ text: string }`입니다. 단계가 대신 지정된 형태를 반환하도록 하려면 `structuredOutput.schema`를 전달하세요. 이 스키마가 단계의 출력 스키마가 되므로 이후 단계를 완전한 타입 안전성을 유지하며 연결할 수 있습니다.

```typescript
workflow
  .agent(testAgent, {
    structuredOutput: {
      schema: z.object({
        subtopics: z.array(z.string()),
      }),
    },
  })
  .commit();
```

## ID로 상담사 참조

등록된 Agent를 가져오지 않고 참조하려면 문자열을 전달하세요. Workflow가 실행될 때 Agent는 Mastra 인스턴스에 등록되어야 합니다.

```typescript
workflow.agent("test-agent", { maxSteps: 3 }).commit();
```

## 지속 Agent 단계

`.agent()`로 구축한 Workflow는 [동적 Workflow](https://mastra.zisheng.pro/ko/docs/workflows/dynamic-workflows)에서 사용하는 것과 동일한 선언적 항목으로 직렬화됩니다. 저장소를 통해 왕복 보존되는 옵션은 `retries`와 `metadata`뿐입니다. `onFinish`나 함수 값을 갖는 `toolChoice`처럼 함수를 포함하는 옵션은 Workflow를 저장할 때 오류를 발생시킵니다.

## 관련된

- [Agent 및 Tool](https://mastra.zisheng.pro/ko/docs/workflows/agents-and-tools)
- [동적 Workflow](https://mastra.zisheng.pro/ko/docs/workflows/dynamic-workflows)
- [Workflow.tool()](https://mastra.zisheng.pro/ko/reference/workflows/workflow-methods/tool)