docs: add multi-agent orchestration section to agent-to-agent recipe

[keydunov]

Explain how an orchestrating agent routes questions across multiple Cube agents by POSTing to each agent's Chat API URL. Cover system-prompt listing vs. a discovery tool, with a worked LangChain example.

Check List

• Tests have been run in packages where changes have been made if available
• Linter has been run for changed code
• Tests for the changes have been added if not covered yet
• Docs have been added / updated if required

[claude]

Claude finished @keydunov's task in 1m 40s —— View job

---

Review of PR #10924

• Gather context and read changed files
• Review documentation content quality
• Review code examples for correctness
• Check for security considerations
• Provide final review feedback

---

Overall: This is a well-written, focused documentation addition. The new "Orchestrating multiple Cube agents" section (lines 367–468) is a clean extension of the existing recipe. The prose is clear, the two routing patterns (system-prompt listing vs. discovery tool) are practical, and the LangChain example is complete enough to copy-paste. A few observations:

What looks good

• Clean abstraction: the ask_cube_agent tool delegates to the existing query_cube_agent helper, just swapping the URL — nice reuse of the pattern already established earlier in the doc.
• Error handling in ask_cube_agent: the agent is None check returns a helpful message listing available agents instead of a stack trace — good DX.
• Discovery vs. hardcoded: presenting both patterns and explaining when each fits is the right call. The <Info> callout reminding readers they can skip the discovery tool is a nice touch.
• Reference links: [ref-multi-agent] and [ref-spaces] are properly added at the bottom.

Minor suggestions (non-blocking)

1. query_cube_agent signature mismatch (line 449): the code calls query_cube_agent(question, chat_api_url=agent["url"]), but the query_cube_agent function defined earlier in the doc (line 94) uses CUBE_CHAT_API_URL as a module-level constant and doesn't accept a chat_api_url parameter. The prose at line 395–397 explains it's "extended to accept a chat_api_url argument," but a reader copy-pasting both snippets will get a TypeError. Consider either: (a) showing the updated signature inline (even a one-line note like def query_cube_agent(question: str, *, chat_api_url: str) -> str:), or (b) adding a brief comment in the code block pointing back to the helper.

2. Broken anchor (line 374): [Chat API URL](#endpoint) links to #endpoint, but I don't see a heading with that ID in this file. If it refers to a heading on a different page, a full path like /reference/embed-apis/chat-api#endpoint would be more reliable.

3. CUBE_API_KEY not shown in the multi-agent snippet: the earlier examples read CUBE_API_KEY from env and pass it in the Authorization header. The multi-agent code block (lines 399–449) relies on query_cube_agent to handle auth, which is fine, but worth noting that the reader needs the helper from earlier — a one-line comment like # Uses query_cube_agent from above at the top of the block would reduce ambiguity.

4. Missing import requests in the multi-agent snippet: the block imports json and os but not requests. Since it delegates to query_cube_agent this isn't strictly needed in this snippet, but it's inconsistent with the earlier examples. Adding it (or not importing json either, since it's only used inside list_cube_agents) would be more consistent.

Security

• No sensitive values are hardcoded; API keys come from environment variables throughout.
• The sessionSettings / externalId pattern for user-scoped access is correctly demonstrated.
• No issues here.

Summary

Solid docs addition — the multi-agent routing section fills a real gap. The main actionable item is the query_cube_agent signature mismatch (suggestion 1) and the broken #endpoint anchor (suggestion 2), which could confuse readers who copy the code verbatim. The rest are polish items.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🔴 Failed	–	May 20, 2026, 8:19 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.