Using Agents and Tools Inside Mastra Workflows

Learn how to convert existing agents and tools directly into workflow steps and connect them using data transformation steps.

In the previous lesson, you built custom steps with standard JavaScript logic and registered a basic workflow. Now, you will combine standalone agents and tools into the same deterministic execution pipeline.

Previous lesson: Building Mastra Workflows | Next lesson: Mastra RAG: Answering From Your Own Docs

Converting Tools Directly into Workflow Steps

In earlier lessons, you created tools for your agent to call whenever the model chose to do so. In a workflow, you often know ahead of time that a tool must execute at an exact point in the pipeline.

Mastra allows you to pass a tool directly to createStep. When you do this, Mastra automatically creates a workflow step that inherits the tool schema.

ts
Copy

The resulting step requires the exact input defined in the tool inputSchema. For orderStatusTool, that means the step requires { orderId: string }. It outputs { orderId: string, status: string, eta: string }.

Pro Tip: Using createStep(tool) avoids writing duplicate validation logic. Any change made to the tool input schema immediately updates the workflow step schema.

Converting Agents Directly into Steps

You can also convert an entire agent into a workflow step by passing the agent instance into createStep.

ts
Copy

An agent converted to a step always expects an object containing a prompt string:

ts
Copy

The step executes the agent using that prompt and returns the generated text. This provides a direct way to invoke a language model inside an automated sequence without writing manual invocation code.

Common Mistake: Passing arbitrary fields to an agent step will cause a validation failure. An agent step created with createStep(agent) strictly expects an object with the shape { prompt: string }.

Reshaping Data with .map

Workflows enforce strict contract matching. The output of one step must match the input schema of the next step.

When you chain createStep(orderStatusTool) directly into createStep(supportAgent), a mismatch occurs. The tool outputs { orderId, status, eta }, but the agent step demands { prompt }.

To resolve this difference, use the .map method. Think of .map like a physical plug adapter that reshapes the prongs of a cable so two different devices can connect.

ts
Copy

The .map callback accepts inputData from the previous step and returns a new object matching the input expected by agentStep.

Accessing Agents Dynamically Inside Steps

Converting an agent directly with createStep(agent) is quick, but you might need more control. You may want to customize memory options, configure tool call limits, or inspect the text before returning.

In those situations, define a custom step with createStep and retrieve your agent from the mastra execution context.

ts
Copy

Inside the execute function, mastra.getAgent('supportAgent') uses the registration key defined on your Mastra instance. This gives you full access to all standard agent methods like generate and stream.

Building the Complete Order Update Workflow

Now you can build a complete file showing both techniques in action. This workflow takes an incoming ticket, checks the order status with a tool step, reshapes the payload, and sends the prompt to the support agent.

Create the file src/mastra/workflows/order-update-workflow.ts:

ts
Copy

Register this workflow on your main Mastra configuration in src/mastra/index.ts:

ts
Copy

Save this test script as run-order-update.ts in your project root:

ts
Copy

Run it with tsx:

bash
Copy

When this runs, orderStatusTool resolves the order details deterministically. Next, .map constructs the prompt format required by the agent. Finally, supportAgent generates the final text.

Try This: Run npm run dev to start Mastra Studio at http://localhost:4111. Open the Workflows tab, locate order-update-workflow, enter {"orderId": "ORD-1001"}, and trigger a run to see each step output in the trace visualizer.

Quick Challenge: Add a second .map step after the agent output to format the final result into an object containing both a timestamp string and the text response.

In the next lesson, Mastra RAG: Answering From Your Own Docs, you will learn how to store support documents in a vector database so your agent can answer customer questions directly from knowledge base articles.