代理和工具

🌐 Agents and Tools

工作流步骤可以调用代理来利用大型语言模型的推断能力，或调用工具以实现类型安全的逻辑。你可以在步骤的 execute 函数中调用它们，也可以使用 createStep() 将它们直接组合为步骤。

🌐 Workflow steps can call agents to leverage LLM reasoning or call tools for type-safe logic. You can either invoke them from within a step's execute function or compose them directly as steps using createStep().

在工作流中使用代理

🌐 Using agents in workflows

在工作流步骤中使用代理，当你需要推断、语言生成或其他基于大语言模型的任务时使用。通过步骤的 execute 函数调用，以便对代理调用有更多控制（例如，跟踪消息历史或返回结构化输出）。当你不需要修改代理调用方式时，将代理组合为步骤使用。

🌐 Use agents in workflow steps when you need reasoning, language generation, or other LLM-based tasks. Call from a step's execute function for more control over the agent call (e.g., track message history or return structured output). Compose agents as steps when you don't need to modify how the agent is invoked.

调用代理

🌐 Calling agents

在步骤的 execute 函数中使用 .generate() 或 .stream() 调用代理。这让你可以在将响应传递给下一步之前修改代理调用并处理响应。

🌐 Call agents inside a step's execute function using .generate() or .stream(). This lets you modify the agent call and handle the response before passing it to the next step.

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 as steps

当你不需要修改代理调用时，使用 createStep() 将代理作为一个步骤来编写。使用 .map() 将上一步的输出转换为代理可以使用的 prompt。

🌐 Compose an agent as a step using createStep() when you don't need to modify the agent call. Use .map() to transform the previous step's output into a prompt the agent can use.

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

info

请访问 输入数据映射 了解更多信息。

🌐 Visit Input Data Mapping for more information.

当未提供 structuredOutput 选项时，Mastra 代理会使用默认模式，该模式期望输入为 prompt 字符串，并返回 text 字符串作为输出：

🌐 When no structuredOutput option is provided, Mastra agents use a default schema that expects a prompt string as input and returns a text string as output:

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

具有结构化输出的代理

🌐 Agents with structured output

当你需要代理返回结构化数据而不是纯文本时，将 structuredOutput 选项传递给 createStep()。该步骤的输出模式将与你提供的模式匹配，从而实现与后续步骤的类型安全链式连接。

🌐 When you need the agent to return structured data instead of plain text, pass the structuredOutput option to createStep(). The step's output schema will match your provided schema, enabling type-safe chaining to subsequent steps.

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 选项接受任何 Zod 模式。代理将生成符合该模式的输出，并且此步骤的 outputSchema 将自动设置为匹配。

🌐 The structuredOutput.schema option accepts any Zod schema. The agent will generate output conforming to this schema, and the step's outputSchema will be automatically set to match.

info

访问 Structured Output 以获取更多选项，例如错误处理策略和使用结构化输出的流式传输。

🌐 Visit Structured Output for more options like error handling strategies and streaming with structured output.

在工作流中使用工具

🌐 Using tools in workflows

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

🌐 Use tools in workflow steps to leverage existing tool logic. Call from a step's execute function when you need to prepare context or process responses. Compose tools as steps when you don't need to modify how the tool is used.

调用工具

🌐 Calling tools

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

🌐 Call tools inside a step's execute function using .execute(). This gives you more control over the tool's input context, or process its response before passing it to the next step.

src/mastra/workflows/test-workflow.ts

import { testTool } from "../tools/test-tool";

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

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

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

info

访问 Calling Tools 获取更多示例。

🌐 Visit Calling Tools for more examples.

工具作为步骤

🌐 Tools as steps

当上一步的输出与工具的输入上下文匹配时，使用 createStep() 将工具作为一个步骤进行组合。如果不匹配，可以使用 .map() 转换上一步的输出。

🌐 Compose a tool as a step using createStep() when the previous step's output matches the tool's input context. You can use .map() to transform the previous step's output if they don't.

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

info

请访问 输入数据映射 了解更多信息。

🌐 Visit Input Data Mapping for more information.

相关

🌐 Related

• 使用代理
• MCP 概述