Agents and tools

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Mastra workflow documentation covering how to invoke agents and tools from within workflow steps, targeting developers building LLM-powered workflows that leverage LLM reasoning and type-safe logic.

Insight

Mastra workflows support two approaches for integrating agents and tools: calling them from within a step’s execute() function for fine-grained control, or composing them directly as steps using createStep(). For agents, use .generate() or .stream() methods inside execute() to handle responses before passing to subsequent steps. The .generate() method accepts memory options with thread and resource identifiers for conversation tracking. When composing agents as steps, use .map() to transform previous step output into a prompt string. Agents without structuredOutput use a default schema with prompt:string input and text:string output. The structuredOutput option accepts any Standard JSON Schema, automatically matching the step’s outputSchema to the provided schema for type-safe step chaining. For tools, call .execute() inside execute() with the tool context and requestContext, or compose tools as steps when the previous step’s output matches the tool’s input. Tools as steps can use .map() to transform mismatched outputs. Both agents and tools support being directly passed to createStep() without modification.

Hành động

1. To call agents from execute(): Use mastra.getAgent() to retrieve the agent, then call .generate() with prompt and memory options (thread, resource). Return transformed data to subsequent steps. 2. To compose agents as steps: Create a .map() that transforms input to {prompt: string}, then pass the agent to createStep() as the first argument. 3. For structured output: Pass {structuredOutput: {schema: z.object({…})}} to createStep() with your JSON schema. Subsequent steps receive typed data matching the schema. 4. To call tools from execute(): Import the tool, call tool.execute({input}, {requestContext}), return transformed response. 5. To compose tools as steps: Use .map() to match previous output to tool’s expected input context, then pass tool to createStep().

Kết quả

Agents invoked via .generate() return a response object with .text property. Agents composed as steps return text output (or structured data with structuredOutput). Tools invoked via .execute() return their defined response object. Tools composed as steps return their output matching the previous step’s mapped input.

Điều kiện áp dụng

This documentation applies to Mastra workflows using the createStep() and createWorkflow() APIs. Agents require an agent registered in mastra. Tools require imported tool modules.

---

Nội dung gốc (Original)

Agents and tools

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

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

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.

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

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.

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.

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

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.

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

The structuredOutput.schema option accepts any Standard JSON Schema. The agent will generate output conforming to this schema, and the step’s outputSchema will be automatically set to match.

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

Using tools in workflows

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

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

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

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.

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

• Using Agents
• MCP Overview

Liên kết

• Nền tảng: Dev Framework · Mastra
• Nguồn: https://mastra.ai/docs/workflows/agents-and-tools

Xem thêm:

• Tools
• Workflows overview
• Agent networks
• Agents overview
• Processors in Mastra Agents