Loading pattern preview
BlocksAgent Patterns
Multi-Step Tool Pattern
Multi-Step Tool Pattern
Execute multi-step workflows with typed tools. Includes streaming, tool chaining, and decision-making for automated tasks.
Use this when a chat agent must call several typed tools in a row, feeding each result into the next step, with a step limit to stop runaway loops.
Loading pattern preview
Problems solved
Technical challenges this implementation handles out of the box.
- Coordinate multi-step tool calling inside an Experimental_Agent loop
- Chain dependent tool results across several agent steps
- Stream progressive tool activity to the chat UI
- Stop runaway loops with step-count controls
Use cases
Products and workflows this pattern is designed to support.
- Research agents that gather then synthesize
- Ops assistants that complete multi-step checklists
- Data enrichment chats with sequential tools
- Teaching multi-step tool patterns with AI SDK agents
Compare with
Similar patterns, and when each one is the better fit.
Sequential Workflow PatternFreeUse this when each stage's output feeds the next and you need a pass/fail gate before moving on, such as drafting then polishing copy.
Orchestrator-Worker Workflow PatternFreeUse this when a durable workflow must plan a multi-file change set, then hand create, modify, and delete work to parallel specialized workers.
Tool ApprovalUse this when a destructive action, such as deleting a file, needs an in-chat confirm or deny step built only on the AI SDK's own approval flow.
Dynamic ToolUse this when you need to build tools with dynamicTool whose Zod schemas change per request, like a converter whose inputs differ by conversion type.
Setup
Requirements, wiring steps, and what this pattern adds to your project.
Getting started
Pick how you want to pull this pattern in. Then wire env vars and routes the same way.
- 1
Download → Next.js app
Use Download → Next.js app in the preview toolbar. You get a zip scaffold (Pro downloads rewrite preview `/view/.../api/*` paths to `/api/*` automatically).
- 2
Extract the zip and install dependencies
Unzip the archive, then run `pnpm install` (or npm / yarn) in the project folder.
- 3
Fill .env.local
The download includes .env.local placeholders when needed. Add real values for: OPENAI_API_KEY, PERPLEXITY_API_KEY.
- 4
Customize the agent and tool files
Adapt prompts, tools, and stop conditions in the generated project for your product.
- 5
Run the app and open the pattern route
Run `pnpm dev`, open the setup/checklist page if present, then navigate to the generated pattern route and verify responses.
Environment variables
Capabilities
AI SDK APIs
AgenttoolstepCountIsgenerateObjectExperimental_AgentgatewayhasToolCallProviders
OpenAIPerplexity
External services
Hacker News
Files added
18 files
app/page.tsxapp/layout.tsxapp/api/multi-step-tool-agent/route.tslib/multi-step-agent.tslib/multi-step-tool-types.tslib/ai-agent-multi-step-tools/web-search.tslib/ai-agent-multi-step-tools/news-search.tslib/ai-agent-multi-step-tools/analyze.tslib/ai-agent-multi-step-tools/decide.tslib/ai-agent-multi-step-tools/provide-answer.tslib/ai-agent-multi-step-tools/schema.tscomponents/multi-step-tool-chat-demo.tsxcomponents/tool-views/web-search-view.tsxcomponents/tool-views/news-search-view.tsxcomponents/tool-views/analyze-view.tsxcomponents/tool-views/decide-view.tsxcomponents/tool-views/provide-answer-view.tsxREADME.md
Dependencies
7 total
npm packages
6AISDKlucide-reactNext.jsReactsonnerZod
Registry components
empty
Critical files
8 files
multi-step-tool-agent/route.tsAPI route wiring the agent to HTTP: uses createAgentUIStreamResponse and validateUIMessages to connect the multi-step agent to a streaming endpoint.
lib/multi-step-agent.tsCore agent definition: creates an Experimental_Agent with comprehensive system instructions, 5 registered tools, and stop conditions (hasToolCall or stepCountIs(8)).
ai-agent-multi-step-tools/web-search.tsWeb search tool using Perplexity Sonar: uses generateObject with perplexity/sonar model. Implements generator-based execute with loading/ready states.
ai-agent-multi-step-tools/news-search.tsNews search tool using HN Algolia API. Generator-based tool with loading/ready states and graceful error fallback.
ai-agent-multi-step-tools/analyze.tsAnalysis tool: breaks down complex problems into components using systematic/creative/technical approaches. Generator-based with Zod schema validation.
ai-agent-multi-step-tools/decide.tsDecision tool with scoring logic: evaluates options against criteria using keyword matching and heuristic scoring. Shows a tool with non-trivial local computation.
ai-agent-multi-step-tools/provide-answer.tsTerminal answer tool that synthesizes all previous tool results into a final structured answer with inline citations and confidence score. Triggers agent termination via stopWhen condition.
ai-agent-multi-step-tools/schema.tsShared Zod schemas for web search tools: WebSearchItemSchema and WebSearchSchema for Perplexity Sonar responses.
Requirements
- Complexity
- Intermediate
- Setup time
- ~10 minutes
- Node
- 24+
- Memory
- 1GB
