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

# Agent 與 Tool

Workflow step 可以呼叫 Agent 來運用 LLM 推理，亦可呼叫 Tool 來執行型別安全的邏輯。你可以在 step 的 `execute()` 函數內呼叫它們，或使用 `createStep()` 直接將它們組合成 step。

## 在 Workflow 中使用 Agent

當你需要推理、語言生成或其他以 LLM 為基礎的工作時，可在 Workflow step 中使用 Agent。如需更精細地控制 Agent 呼叫（例如追蹤訊息歷史記錄或傳回結構化輸出），請從 step 的 `execute()` 函數呼叫 Agent。如果不需要修改 Agent 的呼叫方式，則可將 Agent 組合成 step。

### 呼叫 Agent

在 step 的 `execute()` 函數內使用 `.generate()` 或 `.stream()` 呼叫 Agent。這樣便可在將回應傳遞至下一個 step 前，修改 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 用作 step

如果不需要修改 Agent 呼叫，請使用 `createStep()` 將 Agent 組合成 step。使用 `.map()` 將上一個 step 的輸出轉換成 Agent 可使用的 `prompt`。

![將 Agent 用作 step](/zh-HK/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/zh-HK/docs/workflows/control-flow)。

如果未提供 `structuredOutput` 選項，Mastra Agent 會使用預設 schema，要求輸入為 `prompt` 字串，並以 `text` 字串作為輸出：

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

### 使用結構化輸出的 Agent

當你需要 Agent 傳回結構化資料而非純文字時，請將 `structuredOutput` 選項傳遞至 `createStep()`。step 的輸出 schema 會與你提供的 schema 相符，讓你能以型別安全的方式串連後續 step。

```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 的輸出，而 step 的 `outputSchema` 會自動設定為與其相符。如需錯誤處理策略及串流結構化輸出等更多選項，請參閱[結構化輸出](https://mastra.zisheng.pro/zh-HK/docs/agents/structured-output)。

### `.agent()` 簡寫方式

你可以使用 `.agent()` 直接加入 Agent，無需以 `createStep()` 包裝。它接受與 `createStep(agent, options)` 相同的選項，亦可使用 Agent ID 字串代替 Agent 實例：

```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 graph 中記錄聲明式項目，而非不透明的 step，因此以此方式建立的 Workflow 可保存為[動態 Workflow](https://mastra.zisheng.pro/zh-HK/docs/workflows/dynamic-workflows)。如需所有參數的詳情，請參閱 [Workflow.agent()](https://mastra.zisheng.pro/zh-HK/reference/workflows/workflow-methods/agent)。

## 在 Workflow 中使用 Tool

在 Workflow step 中使用 Tool，以運用現有的 Tool 邏輯。當你需要準備 context 或處理回應時，請從 step 的 `.execute()` 函數呼叫 Tool。如果不需要修改 Tool 的使用方式，則可將 Tool 組合成 step。

### 呼叫 Tool

在 step 的 `.execute()` 函數內呼叫 Tool。這樣可更精細地控制 Tool 的輸入 context，或在將其回應傳遞至下一個 step 前加以處理。

```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 用作 step

當上一個 step 的輸出與 Tool 的輸入 context 相符時，可使用 `createStep()` 將 Tool 組合成 step。如果兩者不相符，你可以使用 `.map()` 轉換上一個 step 的輸出。

![將 Tool 用作 step](/zh-HK/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/zh-HK/docs/workflows/control-flow)。

### `.tool()` 簡寫方式

你可以使用 `.tool()` 直接加入 Tool，無需以 `createStep()` 包裝。它接受 Tool 實例或已註冊的 Tool ID 字串，以及 step 層級的 `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/zh-HK/docs/workflows/dynamic-workflows)。如需所有參數的詳情，請參閱 [Workflow.tool()](https://mastra.zisheng.pro/zh-HK/reference/workflows/workflow-methods/tool)。

## 相關內容

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