francostan/ai-sdk-6-skill
Overview
This skill is an expert guide for using Vercel AI SDK 6 with ToolLoopAgent, safety patterns, MCP integration, RAG reranking, and DevTools. It condenses core patterns, code snippets, and migration tips so engineers can build reliable multi-step agents and safe tool integrations. The guide is focused on practical workflows, observability, and production-ready considerations.
How this skill works
The skill explains how to create multi-step agents using ToolLoopAgent that iterate: call model → run tools → append results. It covers safety workflows with needsApproval, connecting external MCP tool servers, two-stage RAG using rerank, and structured JSON outputs via Output.object(). It also details debugging and telemetry using DevTools and token analytics.
When to use it
- Building multi-step, agentic workflows that orchestrate tools and sub-agents
- Adding human-in-the-loop safety for destructive or sensitive operations
- Connecting external tool providers via MCP or provider-native tools
- Implementing RAG with a broad candidate search followed by reranking
- Debugging model behavior, tool calls, and token usage with DevTools and token analytics
Best practices
- Define agents in dedicated modules and export InferAgentUIMessage types for UI integration
- Use callOptionsSchema and prepareCall to inject runtime context (userId, tier) and keep prompts small
- Require explicit approval for destructive tools using needsApproval and implement a two-call approval flow in the UI
- Prefer Output.object() for typed structured outputs and minimize what the model sees by using toModelOutput for compact summaries
- Use rerank to reduce hallucinations: retrieve many candidates then rerank top-N for final context
- Wrap providers with devToolsMiddleware in dev and add reconnect logic for MCP in production
Example use cases
- Orchestrator-worker pattern: orchestrator delegates research and analysis to specialized ToolLoopAgents
- Human approval flow: agent pauses on deleteUser call and UI resumes workflow after explicit user approval
- RAG pipeline: vector search returns 50 candidates, rerank returns top 5 for grounded responses
- Parallel agents: run weather, news, and finance agents concurrently and summarize results
- Migration: codemod v6 then fix custom middleware and replace generateObject/streamObject with generateText+Output.object
FAQ
When needsApproval triggers, the agent returns a tool-approval-request. Present an approval UI, then re-call the agent with a tool-approval-response message including the toolCallId and approved flag.
When should I use rerank vs top-k search?
Use rerank when initial retrieval returns noisy results. Fetch a broad candidate set (e.g., 50), then rerank to obtain a smaller, highly relevant top-N to reduce hallucinations.
How do I limit agent steps?
Configure stopWhen with helpers like stepCountIs(N) or adjust toolChoice and activeTools per prepareStep to control loop length.
