|
| 1 | +# Build a Multi-Agent App |
| 2 | + |
| 3 | +[Your First Agent](/guide/first-agent) ended with a single agent answering one prompt. Real work rarely fits one prompt: a research question fans out into several lines of inquiry that each want their own tools, a shared house style, and someone to plan the work and stitch the findings back together. |
| 4 | + |
| 5 | +This tutorial builds that app, a small research assistant, by composing three GemStack packages: |
| 6 | + |
| 7 | +- [`@gemstack/ai-sdk`](/packages/ai-sdk/agents) for tools and the agent loop, |
| 8 | +- [`@gemstack/ai-skills`](/packages/ai-skills) to load a portable `SKILL.md` skill onto a worker, |
| 9 | +- [`@gemstack/ai-autopilot`](/packages/ai-autopilot) to plan a task into subtasks, dispatch them to workers, and synthesize the result. |
| 10 | + |
| 11 | +By the end you will have a `Supervisor` that breaks a research question into subtasks, runs each on a skill-equipped worker agent, and combines the answers. We finish with a short note on exposing the whole thing over MCP. |
| 12 | + |
| 13 | +If you have not registered a provider yet, do that first (see [Installation](/guide/installation)). |
| 14 | + |
| 15 | +## Register a provider |
| 16 | + |
| 17 | +Every example assumes a default provider registered once at startup: |
| 18 | + |
| 19 | +```ts |
| 20 | +import { AiRegistry, AnthropicProvider } from '@gemstack/ai-sdk' |
| 21 | + |
| 22 | +AiRegistry.register(new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! })) |
| 23 | +AiRegistry.setDefault('anthropic/claude-sonnet-4-6') |
| 24 | +``` |
| 25 | + |
| 26 | +With a default model set, agents do not need to declare one. |
| 27 | + |
| 28 | +## Step 1: two tools the worker can call |
| 29 | + |
| 30 | +A research worker needs to reach the web. We give it two tools with `toolDefinition(...)`: one to search, one to fetch a page. Each declares its input with Zod and attaches a `.server()` handler that the agent calls (see [Tools](/packages/ai-sdk/tools)). Swap the stubbed bodies for a real search API and HTTP client. |
| 31 | + |
| 32 | +```ts |
| 33 | +import { toolDefinition } from '@gemstack/ai-sdk' |
| 34 | +import { z } from 'zod' |
| 35 | + |
| 36 | +export const searchWeb = toolDefinition({ |
| 37 | + name: 'search_web', |
| 38 | + description: 'Search the web and return the top matching result snippets', |
| 39 | + inputSchema: z.object({ |
| 40 | + query: z.string().describe('The search query'), |
| 41 | + limit: z.number().int().min(1).max(10).default(5), |
| 42 | + }), |
| 43 | +}).server(async ({ query, limit }) => { |
| 44 | + // Call your real search provider here. |
| 45 | + return await search(query, limit) // -> [{ title, url, snippet }, ...] |
| 46 | +}) |
| 47 | + |
| 48 | +export const fetchPage = toolDefinition({ |
| 49 | + name: 'fetch_page', |
| 50 | + description: 'Fetch a URL and return its readable text content', |
| 51 | + inputSchema: z.object({ url: z.string().url() }), |
| 52 | +}).server(async ({ url }) => { |
| 53 | + const res = await fetch(url) |
| 54 | + return await res.text() |
| 55 | +}) |
| 56 | +``` |
| 57 | + |
| 58 | +The agent decides when to call each tool, validates the arguments against `inputSchema` before your handler runs, and feeds the result back to the model on the next step. |
| 59 | + |
| 60 | +## Step 2: a skill for house style |
| 61 | + |
| 62 | +Every worker should cite its sources the same way, and that convention should travel with the agent rather than being copy-pasted into each system prompt. That is exactly what a skill is: a portable folder of instructions (and optionally tools and resources) you compose onto an agent on demand. |
| 63 | + |
| 64 | +Create `skills/citations/SKILL.md`. The YAML frontmatter is the manifest; the markdown body becomes extra system-prompt text: |
| 65 | + |
| 66 | +```markdown |
| 67 | +--- |
| 68 | +name: citations |
| 69 | +description: Cite every claim with a source URL and never invent sources |
| 70 | +trigger: answering a research question that draws on web sources |
| 71 | +--- |
| 72 | + |
| 73 | +# Citations |
| 74 | + |
| 75 | +When you state a fact drawn from a source, cite it inline with the page URL in |
| 76 | +parentheses, like (https://example.com/article). Only cite pages you actually |
| 77 | +fetched with `fetch_page`. If you could not verify a claim, say so plainly |
| 78 | +instead of guessing. End your answer with a "Sources" list of the URLs you used. |
| 79 | +``` |
| 80 | + |
| 81 | +This skill is instructions-only, so there is no build step to worry about. (A skill that ships tools co-locates them in a `tools.ts` that the loader imports from its compiled output; see the [compiled-output caveat](/packages/ai-skills) when you go that far.) |
| 82 | + |
| 83 | +Load it once at module init, since loading is async and the agent hooks are synchronous: |
| 84 | + |
| 85 | +```ts |
| 86 | +import { loadSkill } from '@gemstack/ai-skills' |
| 87 | + |
| 88 | +const citations = await loadSkill('./skills/citations') |
| 89 | +``` |
| 90 | + |
| 91 | +## Step 3: the worker agent |
| 92 | + |
| 93 | +The worker is a `SkillfulAgent`. You declare your own identity in `baseInstructions()` and your own tools in `baseTools()`; the skills listed in `skills()` are merged in, with your own declarations winning on any name collision. Because research is multi-step (search, fetch, read, repeat), we give it a stop condition with `stepCountIs(...)`. |
| 94 | + |
| 95 | +```ts |
| 96 | +import { SkillfulAgent } from '@gemstack/ai-skills' |
| 97 | +import { stepCountIs } from '@gemstack/ai-sdk' |
| 98 | + |
| 99 | +class ResearchWorker extends SkillfulAgent { |
| 100 | + baseInstructions() { |
| 101 | + return 'You research a focused question using the web tools, then answer concisely.' |
| 102 | + } |
| 103 | + skills() { return [citations] } // adds the citation house style |
| 104 | + baseTools() { return [searchWeb, fetchPage] } |
| 105 | + stopWhen() { return stepCountIs(6) } // up to 6 tool-calling rounds |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | +Override the `base*` hooks, not `instructions()` / `tools()`: those are sealed on `SkillfulAgent` and do the merge for you. Overriding them directly would drop the skill composition. |
| 110 | + |
| 111 | +You can run this worker on its own to sanity-check it before wiring up the supervisor: |
| 112 | + |
| 113 | +```ts |
| 114 | +const probe = await new ResearchWorker().prompt( |
| 115 | + 'What problem did the original Transformer paper set out to solve?', |
| 116 | +) |
| 117 | +console.log(probe.text) // answer, with a Sources list, thanks to the skill |
| 118 | +``` |
| 119 | + |
| 120 | +## Step 4: plan, dispatch, synthesize |
| 121 | + |
| 122 | +Now the orchestration. A `Supervisor` takes three stages: a `plan` that decomposes the task into subtasks, the `workers` that run them, and a `synthesize` that combines the results. The planner and synthesizer are themselves ai-sdk agents, adapted with `agentPlanner(...)` and `agentSynthesizer(...)`. |
| 123 | + |
| 124 | +```ts |
| 125 | +import { Supervisor, agentPlanner, agentSynthesizer } from '@gemstack/ai-autopilot' |
| 126 | +import { agent } from '@gemstack/ai-sdk' |
| 127 | + |
| 128 | +const planner = agent( |
| 129 | + 'You break a research question into a few independent sub-questions that can be researched in parallel.', |
| 130 | +) |
| 131 | + |
| 132 | +const editor = agent( |
| 133 | + 'You combine several researched answers into one coherent, well-cited brief. Preserve every source URL.', |
| 134 | +) |
| 135 | + |
| 136 | +const supervisor = new Supervisor({ |
| 137 | + plan: agentPlanner(planner), // LLM decomposition into subtasks |
| 138 | + workers: new ResearchWorker(), // every subtask runs on this worker |
| 139 | + synthesize: agentSynthesizer(editor), // LLM synthesis of the results |
| 140 | + concurrency: 3, // up to 3 workers in flight at once |
| 141 | + maxSubtasks: 5, // hard cap; a longer plan is trimmed |
| 142 | + budget: { maxTotalTokens: 200_000 }, // stop dispatching past this spend |
| 143 | + onEvent: (e) => console.log(e.type), // 'plan', 'dispatch-start', ... |
| 144 | +}) |
| 145 | +``` |
| 146 | + |
| 147 | +`workers` here is a single agent, so each subtask runs on a fresh `ResearchWorker` prompt. When you want different subtasks handled by different specialists, pass a `Record<string, Agent>` instead and let the planner set each `subtask.worker` to route between them. |
| 148 | + |
| 149 | +## Step 5: run it |
| 150 | + |
| 151 | +```ts |
| 152 | +const run = await supervisor.run( |
| 153 | + 'How did the Transformer architecture change machine translation, and what came after it?', |
| 154 | +) |
| 155 | + |
| 156 | +console.log(run.text) // the synthesized, cited brief |
| 157 | +console.log(run.plan) // the subtasks that were executed |
| 158 | +console.log(run.results) // one result per subtask: { text, ok, error?, usage } |
| 159 | +console.log(run.usage) // aggregate token usage across dispatched subtasks |
| 160 | +console.log(run.stoppedEarly) // true if a guardrail trimmed or halted the work |
| 161 | +``` |
| 162 | + |
| 163 | +`run()` resolves to a `SupervisorRun`. A few properties worth leaning on: |
| 164 | + |
| 165 | +- **`run.results`** is one entry per dispatched subtask, in plan order. A worker that throws becomes an `ok: false` result; its siblings still run, so one failed line of inquiry does not sink the whole report. |
| 166 | +- **`run.usage`** aggregates token usage across the dispatched workers. (Planning and synthesis spend are not counted: those contracts return data, not usage.) |
| 167 | +- **`run.stoppedEarly`** tells you a guardrail (the `maxSubtasks` cap or the token `budget`) cut the work short, so you can flag a partial answer. |
| 168 | + |
| 169 | +That is the whole app: tools give a worker hands, a skill gives it a house style, and the supervisor plans the work, fans it out, and reassembles it. |
| 170 | + |
| 171 | +## Optional: expose it over MCP |
| 172 | + |
| 173 | +Once the supervisor works, you can publish it as a Model Context Protocol server so other agents and MCP-aware clients can call it as a tool. Wrap the run in a server tool and serve it with [`@gemstack/ai-mcp`](/packages/ai-mcp); the worker's own tools stay internal, and callers see one `research` capability. See [/packages/ai-mcp](/packages/ai-mcp) for the server surface and transport options. |
| 174 | + |
| 175 | +## See also |
| 176 | + |
| 177 | +- [Tools](/packages/ai-sdk/tools) - `toolDefinition(...).server(...)`, streaming, approval, and scoped tools. |
| 178 | +- [Running agents](/packages/ai-sdk/agents) - the agent loop, stop conditions, sub-agents, and suspend/resume. |
| 179 | +- [`@gemstack/ai-skills`](/packages/ai-skills) - authoring, loading, and composing `SKILL.md` skills. |
| 180 | +- [`@gemstack/ai-autopilot`](/packages/ai-autopilot) - the `Supervisor` topology and its guardrails. |
| 181 | +- [`@gemstack/ai-mcp`](/packages/ai-mcp) - expose agents and tools over the Model Context Protocol. |
0 commit comments