Agent 與 Tool

Workflow 步驟可以呼叫 Agent 來使用 LLM 推理，也可以呼叫 Tool 來執行型別安全的邏輯。你可以從步驟的 execute() 函式內叫用它們，或使用 createStep() 直接將它們組合為步驟。

在 Workflow 中使用 Agent

需要推理、語言生成或其他以 LLM 為基礎的任務時，請在 Workflow 步驟中使用 Agent。若要進一步控制 Agent 呼叫（例如追蹤訊息歷程或傳回結構化輸出），請從步驟的 execute() 函式呼叫。若不需要修改 Agent 的叫用方式，則可將 Agent 組合為步驟。

呼叫 Agent

使用 .generate() 或 .stream()，在步驟的 execute() 函式內呼叫 Agent。這可讓你先修改 Agent 呼叫並處理回應，再將結果傳給下一個步驟。

src/mastra/workflows/test-workflow.ts

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。

src/mastra/workflows/test-workflow.ts

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()

如需更多資訊，請參閱輸入資料對應。

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

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

使用結構化輸出的 Agent

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

src/mastra/workflows/test-workflow.ts

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 會自動設定為相符的 schema。如需錯誤處理策略及串流結構化輸出等更多選項，請參閱結構化輸出。

.agent() 簡寫

使用 .agent() 直接新增 Agent，不必將其包裝在 createStep() 中。它接受與 createStep(agent, options) 相同的選項，也能以 Agent ID 字串取代執行個體：

src/mastra/workflows/test-workflow.ts

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。如需所有參數，請參閱 Workflow.agent()。

在 Workflow 中使用 Tool

在 Workflow 步驟中使用 Tool，即可運用現有的 Tool 邏輯。需要準備內容或處理回應時，請從步驟的 .execute() 函式呼叫。若不需要修改 Tool 的使用方式，則可將 Tool 組合為步驟。

呼叫 Tool

在步驟的 .execute() 函式內呼叫 Tool。這可讓你更進一步控制 Tool 的輸入內容，或先處理其回應，再將結果傳給下一個步驟。

src/mastra/workflows/test-workflow.ts

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() 轉換前一個步驟的輸出。

src/mastra/workflows/test-workflow.ts

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()

如需更多資訊，請參閱輸入資料對應。

.tool() 簡寫

使用 .tool() 直接新增 Tool，不必將其包裝在 createStep() 中。它接受 Tool 執行個體或已註冊的 Tool ID 字串，以及步驟層級的 retries 和 metadata：

src/mastra/workflows/test-workflow.ts

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

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

與 .agent() 相同，.tool() 會記錄宣告式項目，因此 Workflow 可以持久保存為動態 Workflow。如需所有參數，請參閱 Workflow.tool()。

相關資源

• 使用 Agent
• MCP 概觀