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

# Agent 및 Tool

Workflow 단계에서는 Agent를 호출하여 LLM 추론을 사용하거나 유형 안전 논리를 위한 Tool을 호출할 수 있습니다. 단계 내에서 호출할 수 있습니다.`execute()`함수를 사용하거나 다음을 사용하여 단계로 직접 구성합니다.`createStep()`.

## Workflow에서 Agent 사용

추론, 언어 생성 또는 기타 LLM 기반 작업이 필요하면 Workflow 단계에서 Agent를 사용하세요. Agent 호출을 더 세밀하게 제어해야 하는 경우(예: 메시지 기록 추적 또는 구조화된 출력 반환) 단계의 `execute()` 함수에서 Agent를 호출합니다. Agent의 호출 방식을 변경할 필요가 없으면 Agent를 단계로 구성하세요.

### Agent 호출

단계의 `execute()` 함수 내에서 `.generate()` 또는 `.stream()`을 사용하여 Agent를 호출합니다. 이를 통해 다음 단계로 전달하기 전에 Agent 호출을 수정하고 응답을 처리할 수 있습니다.

```typescript
const step1 = createStep({
  execute: async ({ inputData, mastra }) => {
    const { message } = inputData

    const testAgent = mastra.getAgent('testAgent')
    const response = await testAgent.generate(
      `Convert this message into bullet points: ${message}`,
      {
        memory: {
          thread: 'user-123',
          resource: 'test-123',
        },
      },
    )

    return {
      list: response.text,
    }
  },
})
```

### 단계로서의 Agent

Agent 호출을 수정할 필요가 없으면 `createStep()`을 사용하여 Agent를 단계로 구성합니다. `.map()`을 사용하여 이전 단계의 출력을 Agent가 사용할 수 있는 `prompt`로 변환하세요. ![단계로 사용하는 Agent](/ko/assets/images/workflows-agent-tools-agent-step-b2f5be22552ce514f7f8cd785ffc5604.jpg)

```typescript
import { testAgent } from '../agents/test-agent'
const step1 = createStep(testAgent)

export const testWorkflow = createWorkflow({})
  .map(async ({ inputData }) => {
    const { message } = inputData
    return {
      prompt: `Convert this message into bullet points: ${message}`,
    }
  })
  .then(step1)
  .then(step2)
  .commit()
```

자세한 내용은 [입력 데이터 매핑](https://mastra.zisheng.pro/ko/docs/workflows/control-flow)을 참조하세요. `structuredOutput` 옵션을 제공하지 않으면 Mastra Agent는 입력으로 `prompt` 문자열을 받고 출력으로 `text` 문자열을 반환하는 기본 스키마를 사용합니다.

```typescript
{
  inputSchema: {
    prompt: string
  },
  outputSchema: {
    text: string
  }
}
```

### 구조화된 출력이 있는 Agent

Agent가 일반 텍스트 대신 구조화된 데이터를 반환해야 하면 `createStep()`에 `structuredOutput` 옵션을 전달합니다. 단계의 출력 스키마가 제공한 스키마와 일치하므로 이후 단계를 타입 안전하게 연결할 수 있습니다.

```typescript
const articleSchema = z.object({
  title: z.string(),
  summary: z.string(),
  tags: z.array(z.string()),
})

const agentStep = createStep(testAgent, {
  structuredOutput: { schema: articleSchema },
})

// Next step receives typed structured data
const processStep = createStep({
  id: 'process',
  inputSchema: articleSchema, // Matches agent's outputSchema
  outputSchema: z.object({ tagCount: z.number() }),
  execute: async ({ inputData }) => ({
    tagCount: inputData.tags.length, // Fully typed
  }),
})

export const testWorkflow = createWorkflow({})
  .map(async ({ inputData }) => ({
    prompt: `Generate an article about: ${inputData.topic}`,
  }))
  .then(agentStep)
  .then(processStep)
  .commit()
```

`structuredOutput.schema` 옵션은 모든 Standard JSON Schema를 허용합니다. Agent는 이 스키마를 준수하는 출력을 생성하며, 단계의 `outputSchema`는 이에 맞게 자동으로 설정됩니다. 오류 처리 전략과 구조화된 출력 스트리밍 같은 추가 옵션은 [구조화된 출력](https://mastra.zisheng.pro/ko/docs/agents/structured-output)을 참조하세요.

### 그만큼`.agent()` shorthand

Agent를 `createStep()`으로 래핑하는 대신 `.agent()`를 사용하여 직접 추가하세요. 이 메서드는 `createStep(agent, options)`과 동일한 옵션을 받으며, 인스턴스 대신 Agent ID 문자열을 전달할 수도 있습니다.

```typescript
import { testAgent } from '../agents/test-agent'

export const testWorkflow = createWorkflow({})
  .map(async ({ inputData }) => ({
    prompt: `Generate an article about: ${inputData.topic}`,
  }))
  .agent(testAgent, { structuredOutput: { schema: articleSchema } })
  .commit()
```

`.agent()`는 불투명한 단계가 아니라 Workflow 그래프에 선언적 항목을 기록하므로, 이 방식으로 구축한 Workflow는 [동적 Workflow](https://mastra.zisheng.pro/ko/docs/workflows/dynamic-workflows)처럼 영구 저장할 수 있습니다. 모든 매개변수는 [Workflow.agent()](https://mastra.zisheng.pro/ko/reference/workflows/workflow-methods/agent)을 참조하세요.

## Workflow에서 Tool 사용

Workflow 단계에서 Tool을 사용해 기존 Tool 로직을 활용합니다. 컨텍스트를 준비하거나 응답을 처리해야 할 때는 단계 내에서 `.execute()` 함수를 호출하세요. Tool의 사용 방식을 수정할 필요가 없다면 Tool을 단계로 구성하세요.

### 호출 Tool

단계 내에서 Tool의 `.execute()` 함수를 호출하세요. Tool의 입력 컨텍스트를 더 세밀하게 제어하거나, 응답을 처리한 후 다음 단계로 전달할 수 있습니다.

```typescript
import { testTool } from '../tools/test-tool'

const step2 = createStep({
  execute: async ({ inputData, requestContext }) => {
    const { text } = inputData

    const response = await testTool.execute({ text }, { requestContext })

    return {
      emphasized: response.emphasized,
    }
  },
})
```

### 단계로서의 Tool

이전 단계의 출력이 Tool의 입력 컨텍스트와 일치하면 `createStep()`을 사용해 Tool을 단계로 구성하세요. 일치하지 않으면 `.map()`을 사용해 이전 단계의 출력을 변환할 수 있습니다. ![단계로 사용하는 Tool](/ko/assets/images/workflows-agent-tools-tool-step-cfd56227ce83c2d03a8c8d0496faeeef.jpg)

```typescript
import { testTool } from '../tools/test-tool'

const step2 = createStep(testTool)

export const testWorkflow = createWorkflow({})
  .then(step1)
  .map(async ({ inputData }) => {
    const { formatted } = inputData
    return {
      text: formatted,
    }
  })
  .then(step2)
  .commit()
```

자세한 내용은 [입력 데이터 매핑](https://mastra.zisheng.pro/ko/docs/workflows/control-flow)을 참조하세요.

### 그만큼`.tool()` shorthand

Tool을 `createStep()`으로 래핑하는 대신 `.tool()`을 사용해 직접 추가하세요. Tool 인스턴스 또는 등록된 Tool ID 문자열과 단계 수준의 `retries` 및 `metadata`를 받습니다.

```typescript
import { testTool } from '../tools/test-tool'

export const testWorkflow = createWorkflow({}).then(step1).tool(testTool).commit()
```

`.agent()`와 마찬가지로 `.tool()`은 선언적 항목을 기록하므로 Workflow를 [동적 Workflow](https://mastra.zisheng.pro/ko/docs/workflows/dynamic-workflows)로 영속화할 수 있습니다. 모든 매개변수는 [Workflow.tool()](https://mastra.zisheng.pro/ko/reference/workflows/workflow-methods/tool)을 참조하세요.

## 관련된

- [Agent 사용](https://mastra.zisheng.pro/ko/docs/agents/overview)
- [MCP 개요](https://mastra.zisheng.pro/ko/docs/mcp/overview)