docs(advanced): add agent-orchestration page#497
Conversation
Covers the four multi-agent patterns (router, handoff, orchestrator + parallel workers + synthesizer, evaluator loop) with code, mermaid diagrams, and tradeoffs; five invariants that keep multi-agent systems reliable (prompt isolation, explicit convergence, structured seams, cost + latency budgeting, fail loud); a worked example combining three patterns; and a cheat sheet. Adds a nav entry under Advanced.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughAdds a new documentation page that describes four multi-agent orchestration patterns, operational invariants, a worked Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
🚀 Changeset Version Preview11 package(s) bumped directly, 22 bumped as dependents. 🟥 Major bumps
🟨 Minor bumps
🟩 Patch bumps
|
|
View your CI Pipeline Execution ↗ for commit 0b7363c
☁️ Nx Cloud last updated this comment at |
@tanstack/ai
@tanstack/ai-anthropic
@tanstack/ai-client
@tanstack/ai-code-mode
@tanstack/ai-code-mode-skills
@tanstack/ai-devtools-core
@tanstack/ai-elevenlabs
@tanstack/ai-event-client
@tanstack/ai-fal
@tanstack/ai-gemini
@tanstack/ai-grok
@tanstack/ai-groq
@tanstack/ai-isolate-cloudflare
@tanstack/ai-isolate-node
@tanstack/ai-isolate-quickjs
@tanstack/ai-ollama
@tanstack/ai-openai
@tanstack/ai-openrouter
@tanstack/ai-preact
@tanstack/ai-react
@tanstack/ai-react-ui
@tanstack/ai-solid
@tanstack/ai-solid-ui
@tanstack/ai-svelte
@tanstack/ai-vue
@tanstack/ai-vue-ui
@tanstack/preact-ai-devtools
@tanstack/react-ai-devtools
@tanstack/solid-ai-devtools
commit: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/advanced/agent-orchestration.md (1)
218-221:⚠️ Potential issue | 🟡 MinorUse
.describe()instead of.meta()for schema descriptions.Same issue as in the Router pattern. The Verdict schema should use
.describe()for the feedback field description:🔧 Proposed fix
const Verdict = z.object({ accepted: z.boolean(), - feedback: z.string().meta({ description: "Required if accepted is false" }), + feedback: z.string().describe("Required if accepted is false"), });🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/advanced/agent-orchestration.md` around lines 218 - 221, The Verdict Zod schema uses .meta() for the feedback field description; update the schema so the feedback property uses .describe("Required if accepted is false") instead of .meta(...). Locate the Verdict constant and replace the feedback field's z.string().meta({ description: "Required if accepted is false" }) with z.string().describe("Required if accepted is false") so the schema description follows the Router pattern and Zod conventions.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/advanced/agent-orchestration.md`:
- Around line 54-57: Replace the use of Zod's .meta({ description: ... }) on the
Route schema with .describe(...) so the schema description is attached in the
standard Zod way; specifically update the Route constant (const Route =
z.object({...})) to call .describe("One sentence justifying the choice") on the
reason field (and any other fields using .meta({ description: ... })) so
descriptions appear correctly in JSON Schema output and LLM consumption.
---
Duplicate comments:
In `@docs/advanced/agent-orchestration.md`:
- Around line 218-221: The Verdict Zod schema uses .meta() for the feedback
field description; update the schema so the feedback property uses
.describe("Required if accepted is false") instead of .meta(...). Locate the
Verdict constant and replace the feedback field's z.string().meta({ description:
"Required if accepted is false" }) with z.string().describe("Required if
accepted is false") so the schema description follows the Router pattern and Zod
conventions.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 1dd14b8b-e9d7-4f78-a020-2bbaab827e35
📒 Files selected for processing (2)
docs/advanced/agent-orchestration.mddocs/config.json
| const Route = z.object({ | ||
| intent: z.enum(["billing", "technical", "refund"]), | ||
| reason: z.string().meta({ description: "One sentence justifying the choice" }), | ||
| }); |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for existing Zod schema patterns in the codebase
rg -n -C2 '\.describe\(' --type=ts
rg -n -C2 '\.meta\(' --type=tsRepository: TanStack/ai
Length of output: 50368
🌐 Web query:
What is the correct Zod method for adding descriptions to schema fields that will appear in JSON Schema output?
💡 Result:
The correct Zod method for adding descriptions to schema fields that appear in JSON Schema output (via z.toJSONSchema) is .describe(description), a shorthand that sets a description field in the schema's metadata registered in z.globalRegistry. Both .describe("Your description") and .meta({ description: "Your description" }) work, with .describe being simpler for descriptions. Metadata is automatically included in the JSON Schema output. Important notes: - Call .describe or .meta last in the method chain, as subsequent methods (e.g., .min, .extend) create new schema instances without inheriting metadata. - Example: import { z } from "zod"; const schema = z.object({ name: z.string.min(1).describe("The person's name"), age: z.number.int.describe("Age in years"), }); const jsonSchema = z.toJSONSchema(schema); // Outputs JSON Schema with "description" fields for name and age This is supported in Zod v4 (current stable version as of 2026), where native JSON Schema conversion was introduced.
Citations:
- 1: Add descriptions to schemas for conversion to JSON Schema colinhacks/zod#4927
- 2: https://zod.dev/json-schema
- 3: https://zod.dev/?id=describe
- 4: https://v4.zod.dev/json-schema?id=configuration
- 5: https://zod.dev/packages/zod
- 6: https://www.zod.dev/json-schema?id=metadata
- 7:
.meta()is ignored intoJSONSchemaunless its the last chained method (using Zod v4) colinhacks/zod#5447 - 8: https://v4.zod.dev/v4?id=json-schema-conversion
Use .describe() instead of .meta() for Zod schema descriptions.
The .describe() method is the standard Zod approach for adding descriptions to schema fields. When descriptions need to appear in JSON Schema output (especially for LLM consumption), use .describe() rather than .meta({ description: "..." }).
🔧 Proposed fix
const Route = z.object({
intent: z.enum(["billing", "technical", "refund"]),
- reason: z.string().meta({ description: "One sentence justifying the choice" }),
+ reason: z.string().describe("One sentence justifying the choice"),
});🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/advanced/agent-orchestration.md` around lines 54 - 57, Replace the use
of Zod's .meta({ description: ... }) on the Route schema with .describe(...) so
the schema description is attached in the standard Zod way; specifically update
the Route constant (const Route = z.object({...})) to call .describe("One
sentence justifying the choice") on the reason field (and any other fields using
.meta({ description: ... })) so descriptions appear correctly in JSON Schema
output and LLM consumption.
The router snippet referenced `specialists[decision.intent]` without defining specialists, leaving readers to guess at the dispatch target. Inline a concise declaration showing each specialist as its own chat() call with a dedicated system prompt.
1 participant
Summary
docs/advanced/agent-orchestration.mdcovering multi-agent patterns in TanStack AI: router, handoff, orchestrator + parallel workers + synthesizer, and evaluator / critic loop.docs/config.jsonunder Advanced.Test plan
stream: falsefor non-streaming calls.chat/agentic-cycle,advanced/middleware,advanced/debug-logging, andchat/structured-outputsresolve.Summary by CodeRabbit