Agents 和 tools

Workflow 步骤可以调用 agents 来使用 LLM 推理，或调用工具来实现类型安全的逻辑。你既可以在步骤的 execute() 函数中调用它们，也可以使用 createStep() 将它们直接组合为步骤。

在 workflows 中使用 agents

当你需要推理、语言生成或其他基于 LLM 的任务时，请在 workflow 步骤中使用 agents。通过步骤的 execute() 函数调用可以获得对 agent 调用的更多控制（例如跟踪消息历史或返回结构化输出）。当你不需要修改 agent 的调用方式时，可以将 agents 组合为步骤。

调用 agents

在步骤的 execute() 函数中使用 .generate() 或 .stream() 调用 agents。这样你可以修改 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,
    }
  },
})

将 agents 用作步骤

当你不需要修改 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 agents 使用默认 schema，它期望输入 prompt 字符串并返回 text 字符串作为输出：

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

带结构化输出的 agents

当你需要 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 将自动设置为匹配。有关错误处理策略和使用结构化输出进行流式传输等更多选项，请访问结构化输出。

.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 图中记录一个声明式条目，而不是不透明的步骤，因此以这种方式构建的 workflows 可以持久化为动态 workflows。所有参数请访问 Workflow.agent()。

在 workflows 中使用 tools

在 workflow 步骤中使用工具可以复用现有的工具逻辑。当你需要准备上下文或处理响应时，请从步骤的 .execute() 函数调用。当你不需要修改工具的使用方式时，可以将工具组合为步骤。

调用 tools

在步骤的 .execute() 函数中调用工具。这样你可以更好地控制工具的输入上下文，或在将响应传递给下一步骤之前进行处理。

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,
    }
  },
})

将 tools 用作步骤

当前一步骤的输出与工具的输入上下文匹配时，使用 createStep() 将工具组合为步骤。如果不匹配，可以使用 .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() 直接添加工具，而不是将其包装在 createStep() 中。它接受工具实例或已注册的工具 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()。

相关内容

• 使用 Agents
• MCP 概览