Docs: "Chat as a tool" multi-agent delegation recipe

Motivation

Pydantic AI's agent-delegation pattern — one agent calls another agent via a tool call — covers most of the practical value people reach for "multi-agent frameworks" for, without needing a graph/orchestration layer. chatlas can already do this today with zero new API: register one Chat's .chat() method (wrapped in a closure with a docstring, exactly like any other tool) as a tool on another Chat via register_tool() (chatlas/_chat.py). This pattern currently isn't documented anywhere — not in docs/tool-calling/ (how-it-works.qmd, displays.qmd, approval.qmd) nor docs/misc/.

Proposed approach

Add a docs article, e.g. docs/tool-calling/multi-agent.qmd (added as a 4th entry to the existing "Tool calling" section in docs/_quarto.yml's sidebar, alongside how-it-works.qmd/displays.qmd/approval.qmd — that section is the natural home since this is fundamentally a tool-calling pattern, not new API).

Minimal accurate example to include (verified against _chat.py's register_tool/chat signatures):

from chatlas import ChatOpenAI

sql_specialist = ChatOpenAI(
    system_prompt="You are a SQL expert. Given a natural-language question and a "
    "table schema, write a single correct SQL query. Return only the query.",
)

def ask_sql_specialist(question: str, schema: str) -> str:
    """
    Delegate a natural-language question to a SQL-writing specialist.

    Parameters
    ----------
    question
        The natural-language question to translate into SQL.
    schema
        The relevant table schema(s) as DDL or a plain-text description.
    """
    return str(sql_specialist.chat(f"Schema:\n{schema}\n\nQuestion: {question}", echo="none"))

coordinator = ChatOpenAI(system_prompt="You help users explore their data.")
coordinator.register_tool(ask_sql_specialist)
coordinator.chat("How many orders were placed last week? (orders table: id, placed_at, status)")

Points to cover in the article:

• System-prompt separation: the specialist gets its own focused system prompt; the coordinator's stays general. This is the main value over "one chat with many tools."
• Cost accounting across chats: each Chat has its own get_cost() (_chat.py); there is no combined/rollup accounting across a coordinator + specialist(s) today. State this plainly as a limitation — anyone wanting a total spend needs to sum coordinator.get_cost() + sql_specialist.get_cost() themselves.
• When to prefer this over one chat with many tools: when a sub-task needs a materially different system prompt, tool set, or even a different/cheaper model, or when you want to cap what context a sub-task is exposed to.
• Note register_tool's model= parameter for cases where the specialist call needs more structured input than plain strings.

Alternatives / prior art

Related: #43 (a gallery/collection of common tool-calling recipes) — this could live as one gallery entry there instead of/in addition to a standalone article; worth cross-linking either way.

Open questions

• Standalone article vs. a section added to an existing tool-calling page?
• Should this also mention to_solver()/InspectAI as a tangential way to evaluate sub-agents, or keep scope tight to the delegation pattern itself?

Drafted from a competitive review of llm / Pydantic AI / LangChain / LiteLLM (July 2026); filed via Claude Code on behalf of @cpsievert.

Read docs/tool-calling/how-it-works.qmd, the neighboring tool-calling pages, docs/_quarto.yml, and chatlas/_chat.py's register_tool(), chat(), and get_cost() definitions. Add a focused multi-agent delegation article or agreed section, cross-linking issue #43 where appropriate, and verify the example and documented cost-accounting limitation against the current API.