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

# Agent 与 Tool

Workflow 步骤可以调用 Agent 使用 LLM 推理，也可以调用 Tool 执行类型安全的逻辑。你可以在步骤的 `execute()` 函数中调用它们，也可以使用 `createStep()` 将其直接组合为步骤。

## 在 Workflow 中使用 Agent

当需要推理、语言生成或其他基于 LLM 的任务时，请在 Workflow 步骤中使用 Agent。如果需要更细致地控制 Agent 调用（例如跟踪消息历史或返回结构化输出），请从步骤的 `execute()` 函数调用；如果无需修改 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 用作步骤](/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/docs/workflows/control-flow)。

未提供 `structuredOutput` 选项时，Mastra Agent 会使用默认 Schema：输入为 `prompt` 字符串，输出为 `text` 字符串：

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

### 使用结构化输出的 Agent

需要 Agent 返回结构化数据而非纯文本时，请将 `structuredOutput` 选项传给 `createStep()`。步骤的输出 Schema 会与你提供的 Schema 匹配，从而以类型安全的方式链接后续步骤。

```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 会生成符合该 Schema 的输出，并自动将步骤的 `outputSchema` 设为匹配值。错误处理策略、结构化输出 Stream 等更多选项请参阅 [Structured Output](https://mastra.zisheng.pro/docs/agents/structured-output)。

### `.agent()` 简写

可以使用 `.agent()` 直接添加 Agent，无需用 `createStep()` 包裹。它接受与 `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 可以作为 [Dynamic Workflow](https://mastra.zisheng.pro/docs/workflows/dynamic-workflows) 持久化。全部参数请参阅 [Workflow.agent()](https://mastra.zisheng.pro/reference/workflows/workflow-methods/agent)。

## 在 Workflow 中使用 Tool

在 Workflow 步骤中使用 Tool，可以复用现有 Tool 逻辑。当需要准备上下文或处理响应时，请从步骤的 `.execute()` 函数调用；如果无需修改 Tool 的使用方式，则将 Tool 组合为步骤。

### 调用 Tool

在步骤的 `.execute()` 函数中调用 Tool。这样可以更细致地控制 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 用作步骤](/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/docs/workflows/control-flow)。

### `.tool()` 简写

可以使用 `.tool()` 直接添加 Tool，无需用 `createStep()` 包裹。它接受 Tool 实例或已注册的 Tool ID 字符串，以及步骤级 `retries` 和 `metadata`：

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

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

与 `.agent()` 类似，`.tool()` 会记录声明式条目，因此 Workflow 可以作为 [Dynamic Workflow](https://mastra.zisheng.pro/docs/workflows/dynamic-workflows) 持久化。全部参数请参阅 [Workflow.tool()](https://mastra.zisheng.pro/reference/workflows/workflow-methods/tool)。

## 相关内容

- [使用 Agent](https://mastra.zisheng.pro/docs/agents/overview)
- [MCP 概览](https://mastra.zisheng.pro/docs/mcp/overview)