Feature: Expose advisor_20260301 on AgentDefinition

[haseebrj17]

Allow sub-agents declared via ClaudeAgentOptions(agents={...}) to be configured with the advisor_20260301 server-side tool (shipped April 9, 2026). Currently the advisor tool is only configurable via the raw anthropic SDK with the advisor-tool-2026-03-01 beta header — it cannot be attached to an AgentDefinition.

Use case

We're building a system with nested sub-agents: a top-level orchestrator delegates to specialized sub-agents via agents={}, and we want each specialized sub-agent to run as a Sonnet executor with an Opus advisor consulted at decision points. Anthropic's published benchmarks for this pattern show ~73% cost reduction vs. Opus-solo with comparable quality, which is the main reason we want it.

We want the entire hierarchy inside the Agent SDK (rather than dropping to raw anthropic for the leaf agents) so we keep Hooks, Tool Search, output_format json_schema coercion, OTEL trace propagation, and per-sub-agent cost telemetry.

What's missing

AgentDefinition.tools accepts client-side tool names (MCP tools, Read, Grep, etc.). It doesn't expose configuration for server-side beta tools that take parameters at request-declaration time, nor a way to set per-sub-agent beta headers.

Proposed API

Two shapes — happy with either.

Option A — Typed fields

AgentDefinition(
    description="...",
    prompt="...",
    model="sonnet",
    tools=["Read", "mcp__svc__do_thing"],
    server_tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",
            "model": "claude-opus-4-7",
            "max_uses": 5,
            "caching": {"type": "ephemeral", "ttl": "5m"},
        }
    ],
    betas=["advisor-tool-2026-03-01"],
)

Option B — Escape hatch

AgentDefinition(
    ...,
    extra_request_params={
        "tools": [{"type": "advisor_20260301", ...}],
        "betas": ["advisor-tool-2026-03-01"],
    },
)

Less type-safe, unblocks any future server-side tool. Could be a stopgap.

Why this matters

Without this, current options are all bad:

1. Hybrid: top-level orchestrator uses agents={}, leaf sub-agents drop to raw anthropic behind a wrapper. Loses Hooks, Tool Search, and StructuredOutput coercion exactly where we need them most.
2. Skip the advisor pattern: lose the documented ~73% cost reduction. (Our current temporary choice.)
3. All raw SDK: discard agents={} entirely. Loses every SDK-managed primitive.

A few behaviors we found prototyping that would benefit from being inside the SDK rather than worked around:

• Echo filtering: in multi-turn loops mixing client-side tools and the advisor server-tool, server_tool_use and advisor_tool_result blocks must be stripped from echoed assistant turns or the next request returns 400 (input schema is narrower than output schema for these blocks).
• Token accounting: advisor tokens live in usage.iterations[], not top-level usage. SDK-managed cost telemetry would handle this transparently.
• StructuredOutput coercion: the SDK's output_format json_schema mechanism reliably enforces JSON-shaped output. Free-form-via-prompt JSON does not when the loop also includes advisor consultations (we observed prose output despite explicit JSON instructions in 1/1 of integrated tests). Native advisor support would let us keep the SDK's coercion while adding advisor consultation.

Acceptance criteria (suggested)

• AgentDefinition exposes server-side tool configuration (Option A or B)
• betas settable per-sub-agent without leaking to the parent
• Advisor token usage surfaced in ResultMessage.usage.iterations[] accessible to the parent
• Hooks (PreToolUse, PostToolUse) fire on advisor invocations with name == "advisor" distinguishable
• Documentation example

Anything I can help with

We have a raw-SDK prototype exercising the advisor tool in a multi-turn loop with both client-side and server-side tools. Happy to share the wire-format gotchas, test cases, or the prototype itself if useful.

Environment

• claude-agent-sdk 0.1.65+
• anthropic 0.75.0
• Models: claude-sonnet-4-6 (executor), claude-opus-4-7 (advisor) — pair validated, no 400