Skip to main content

Workflow.agent()

The .agent() method adds an agent as a declarative step. The step accepts { prompt: string } as input and returns { text: string } by default. Use .map() before the agent to build the prompt from workflow data.

Unlike wrapping an agent with createStep(), .agent() records a declarative entry in the workflow graph. This makes the workflow portable: the same graph can be serialized and persisted as a dynamic workflow.

Usage example
Direct link to Usage example

workflow
  .map({ prompt: mapVariable({ initData: workflow, path: 'topic' }) })
  .agent(testAgent)
  .commit()

Parameters
Direct link to Parameters

agentOrId:

Agent | string
An agent instance, or the ID of an agent registered on the Mastra instance. When passing an ID, the agent is resolved from the registry at execution time.

options?:

AgentStepOptions & { structuredOutput?: { schema }, retries?: number, scorers?: DynamicArgument<MastraScorers>, metadata?: StepMetadata }
Agent call options such as maxSteps, modelSettings, memory, and providerOptions, plus step-level retries, scorers, and metadata. Per-request fields such as requestContext, resourceId, threadId, and onStepFinish are managed by the workflow engine and excluded.

stepOptions?:

{ id?: string }
The step's call-site ID within the workflow. Defaults to the agent's ID. Set this when the same agent appears more than once in one workflow.

Returns
Direct link to Returns

workflow:

Workflow
The workflow instance for method chaining

Structured output
Direct link to Structured output

By default the step's output is { text: string }. Pass structuredOutput.schema to make the step return that shape instead. The schema becomes the step's output schema, so later steps chain against it with full type safety:

workflow
  .agent(testAgent, {
    structuredOutput: {
      schema: z.object({
        subtopics: z.array(z.string()),
      }),
    },
  })
  .commit()

Referencing an agent by ID
Direct link to Referencing an agent by ID

Pass a string to reference a registered agent without importing it. The agent must be registered on the Mastra instance when the workflow runs:

workflow.agent('test-agent', { maxSteps: 3 }).commit()

Persisting agent steps
Direct link to Persisting agent steps

Workflows built with .agent() serialize to the same declarative entries that dynamic workflows use. Only structuredOutput.schema (stored as JSON Schema), retries, and metadata round-trip through storage. Options that hold functions, such as onFinish or a function-valued toolChoice, throw an error when the workflow is stored.

On this page