Advanced Agent Orchestration

1. The Core Concept: Tactical vs. Strategic Reasoning

In marketing automation, many tasks are mechanical (e.g., formatting an email or extracting data), but the high-level strategy (e.g., deciding which market segment to target) requires the deepest reasoning.

• Executor Model: Handles the bulk of token generation at lower rates.
• Advisor Model: Reads the full transcript and provides a high-level plan or course correction (typically 400–700 text tokens) to keep the executor on track.

2. Model Compatibility

For the architect certification, remember that the advisor must be at least as capable as the executor. Valid pairs include:

• Executor: Claude Sonnet 5.5 → Advisor: Claude Opus 5.5
• Executor: Claude Haiku 5.5 → Advisor: Claude Opus 5.5
• Executor: Claude Opus 5.5 → Advisor: Claude Fable 5.1

3. Mechanics of the Sub-Inference

The entire process happens within a single /v1/messages request, no extra round trips are required on the client side.

• The executor model emits a server_tool_use block for the advisor.
• Anthropic runs a separate, server-side inference on the advisor model, passing it the full transcript (system prompt, tools, and history).
• The advisor's thinking blocks are dropped; only the final advice reaches the executor as an advisor_tool_result. With a 5.5-generation (or Fable) advisor that advice arrives encrypted: the block's content is an advisor_redacted_result with encrypted_content, not an advisor_result with text. The executor still uses it; your code just cannot read it, so switch on content.type rather than reading .text.
• The executor resumes generating, informed by the advisor's strategic plan.

4. Advisor-Side Caching

For long-horizon marketing research involving repeated calls, you should enable advisor-side caching in the tool definition.

• Break-even Point: Caching costs more than it saves for one or two calls. It generally breaks even at three advisor calls per conversation and improves thereafter.
• Implementation: Set the caching parameter to {"type": "ephemeral", "ttl": "1h"} to preserve the advisor's transcript across multiple calls.

5. Guiding Throughput with Effort

The effort parameter is soft guidance for how thoroughly Claude reasons across all tokens, text, tool calls, and thinking. The strategic pairing for this pattern:

• Executor (Sonnet 5.5): Set effort="medium" for balanced cost and quality on high-volume generation tasks.
• Advisor (Opus 5.5): the advisor tool has no effort field; it takes model, plus optional max_uses, max_tokens, and caching. Shape the advisor's spend with max_uses and max_tokens, and set effort only on the executor request.

6. Implementation Task

Add the advisor tool to your strategist's tool configuration, with effort set on the executor.

Beta Header Required: advisor-tool-2026-03-01

# Executor-Advisor pattern (beta: advisor-tool-2026-03-01)
response = client.beta.messages.create(
    model="claude-sonnet-5-5",                 # Faster, lower-cost executor
    max_tokens=16000,
    betas=["advisor-tool-2026-03-01"],
    output_config={"effort": "medium"},        # effort applies to the executor
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",
            "model": "claude-opus-5-5",        # High-intelligence advisor
            "max_uses": 3,
            "caching": {"type": "ephemeral", "ttl": "1h"}  # Breaks even at ~3 calls
        }
    ],
    messages=[{"role": "user", "content": "Develop a complex multi-channel marketing launch for our new AI tool."}]
)

# An Opus 5.5 advisor returns encrypted advice: branch on the content type.
for block in response.content:
    if block.type == "advisor_tool_result":
        if block.content.type == "advisor_tool_result_error":
            print("advisor failed:", block.content.error_code)
        # advisor_redacted_result: encrypted, consumed by the executor only

6. Usage and Billing Analysis

• Separate Iterations: Advisor calls are billed as advisor_message iterations at the advisor model's rates.
• Top-level usage: The top-level input_tokens and output_tokens in the API response represent only the executor's usage; you must inspect the usage.iterations array for a full cost breakdown.
• Iteration items are dicts: use .get() for safe access. The list is empty unless a sub-inference (Advisor, Compaction) actually fired.

# Iterations are only populated if a sub-inference (Advisor, Compaction) occurred
if hasattr(response.usage, "iterations") and response.usage.iterations:
    for i, it in enumerate(response.usage.iterations):
        # Use .get() to safely access dictionary keys
        kind = it.get("type", "?")
        input_tokens = it.get("input_tokens", 0)
        output_tokens = it.get("output_tokens", 0)

        print(f"Iteration {i}: Type='{kind}' | Input={input_tokens} | Output={output_tokens}")

        if kind == "advisor_message":
            # Advisor sub-inferences are billed at the advisor model's specific rates
            print(f"  -> Billed at Advisor rates")
        elif kind == "message":
            print(f"  -> Billed at Executor rates")
else:
    print("No iterations recorded.")

Lab Exercise: Executor-Advisor Strategy

Objective: compare tactical generation with advisor-assisted strategic reasoning.

1. Configure a Sonnet executor with an Opus advisor and the required beta header.
2. Run the same strategic prompt with and without the advisor tool.
3. Inspect `usage.iterations` and separate executor costs from advisor costs.
4. Adjust advisor effort and caching, then explain when the extra cost is justified.