Orchestrating Agents

SURFACE ROUTING — read first

Fan-out has three possible engines. Which exist depends on where you are running. Pick the engine before writing any orchestration code.

Primary discriminator — check the tool list, not the filesystem. If an Agent, Task, or Workflow tool is callable, native subagents exist. That single fact decides the row. Everything below is elaboration.

If native subagents exist (Cowork, Claude Code, CCotw)

Use them. Do not hand-roll from this skill. The managed runtime gives 16-concurrent / 1000-agent ceilings, an approval gate, adversarial cross-review, and in-session resume — all of which this skill would reimplement worse. Route model and effort per agent-routing (calibrated on 300 measured Haiku calls); do not re-derive that here.

Cowork adds one option Claude Code doesn't: subagents can be declared rather than spawned ad hoc, as agents/*.md in a plugin — frontmatter name, description, model, effort, maxTurns, tools, disallowedTools, skills, memory, background, isolation: worktree. They appear as plugin-name:agent-name. Note hooks, mcpServers, and permissionMode are refused in plugin agents for security, so a declared agent inherits the session's MCP connections and cannot bring its own.

Reach back into this skill on those surfaces only for what the runtime lacks: stall detection, or a long-lived ConversationThread. Inter-agent messaging is NOT on that list — the runtime ships SendMessage and ListAgents, and AgentPool reimplements them worse.

Native inter-agent messaging — SendMessage / ListAgents

ListAgents discovers reachable agents; SendMessage delivers plain text to one by name or id. Both reach subagents, agent-team teammates, and independent sessions. Official docs: code.claude.com/docs/en/cross-session-messaging (shipped v2.1.224, macOS and Linux).

Four measured behaviors the docs do not state. Each cost a round trip to find; full method and verbatim receipts in oaustegard/experiments → subagent-messaging/RESULTS.md.

• NEVER reply using the incoming envelope's from attribute. For subagents that value is the agent type (general-purpose), not an address, and the send fails with No agent named 'general-purpose' is reachable. Two same-type peers emit identical from values, so it cannot distinguish senders even in principle. Both the SendMessage description and the harness footer on every delivered message instruct otherwise. Capture the agentId from the spawn result and address that.
• Subagents have no ListAgents. ToolSearch("select:ListAgents") returns No matching deferred tools found — absent, not unloaded. A subagent reaches "main" and any address handed to it in its prompt, and nothing else. The topology is a star through the main conversation, not a mesh: hand every peer its siblings' ids at spawn, or they cannot coordinate.
• Delivery queues and never interrupts. The receiver reads between tool calls, so a peer inside a long Bash call is unreachable until it surfaces.
• A send to a completed agent resumes it with full context, and the agent cannot tell. Asked directly, a resumed agent reports no gap or restart marker. Instructions shaped as "if you were resumed, do X" never fire — state the resume in the message. Each resume replays the transcript: ~40k tokens for a small agent, and a measured eight-round chain ran 199k → 324k. Batch questions into one send.

Contested: anthropics/claude-code#48160 and ruvnet/ruflo#2028 report that subagents can receive but not originate SendMessage. A CCotw subagent originated three sends successfully on 2026-08-12 with no CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS set. Verify origination in your own environment before designing around either claim.

If native subagents do NOT exist (claude.ai chat and project sessions)

Two engines, and Gemini is the default — see subagent-delegation-protocol in ops. Use this skill's httpx fan-out when you specifically want Claude-family output, multi-turn threads with cached history, or inter-agent messaging.

Gemini via Cloudflare — available on every surface

Even where native subagents exist, Gemini is the right call for mechanical-but-large work (extractions, ports, boilerplate, schema transforms) and for a genuinely independent second opinion in a judge panel — a different model family fails differently, which is the whole point of a panel.

Call mechanics live in invoking-gemini; do not duplicate them here. Three things that bite:

• Pass the explicit model string gemini-3.6-flash. The flash alias still resolves to 3.5 until that plugin's model table regenerates.
• thinking_level is a string in {minimal, low, medium, high}, default medium. Set minimal for mechanical generation or the model silently spends its output budget reasoning — symptom is an empty or truncated response.
• Credentials come from the CF AI Gateway config, BYOK. Requests route through the gateway rather than Google directly.

Non-negotiable on all surfaces

Review is not delegable. Diff security- and protocol-critical paths line-by-line against source, run syntax/lint checks, live-test whatever is network-testable. Delegated output ships only after your own review, regardless of which model produced it or which engine ran it.

Cross-model review tools (challenge, verify_patch) keep their own model config, often deliberately a Claude. This routing does not silently repoint them.

Orchestrating Agents

This skill enables programmatic API invocations for advanced workflows including parallel processing, task delegation, and multi-agent analysis using the Anthropic API.

Quick Start

Single Invocation

import sys
sys.path.append('/mnt/skills/user/orchestrating-agents/scripts')
from claude_client import invoke_claude

response = invoke_claude(
    prompt="Analyze this code for security vulnerabilities: ...",
    model="claude-sonnet-5-5"
)
print(response)

Default model is claude-sonnet-5-5 ($2/$10 per MTok); claude-opus-5-5 ($4/$20) for open-ended work and claude-haiku-5-5 ($0.10/$0.50, prompts up to 100K tokens, 1M context) for cheap first-pass calls. These models reject non-default sampling parameters, so temperature / top_p / top_k are accepted by the wrappers but only sent to legacy (4.x / 3.x) model ids. They also think adaptively; the wrappers return the joined text blocks, never content[0].

Parallel Multi-Perspective Analysis

from claude_client import invoke_parallel

prompts = [
    {
        "prompt": "Analyze from security perspective: ...",
        "system": "You are a security expert"
    },
    {
        "prompt": "Analyze from performance perspective: ...",
        "system": "You are a performance optimization expert"
    },
    {
        "prompt": "Analyze from maintainability perspective: ...",
        "system": "You are a software architecture expert"
    }
]

results = invoke_parallel(prompts, model="claude-sonnet-5-5")

for i, result in enumerate(results):
    print(f"\n=== Perspective {i+1} ===")
    print(result)

Parallel with Shared Cached Context (Recommended)

For parallel operations with shared base context, use caching to reduce costs by up to 90%:

from claude_client import invoke_parallel

# Large context shared across all sub-agents (e.g., codebase, documentation)
base_context = """
<codebase>
...large codebase or documentation (1000+ tokens)...
</codebase>
"""

prompts = [
    {"prompt": "Find security vulnerabilities in the authentication module"},
    {"prompt": "Identify performance bottlenecks in the API layer"},
    {"prompt": "Suggest refactoring opportunities in the database layer"}
]

# First sub-agent creates cache, subsequent ones reuse it
results = invoke_parallel(
    prompts,
    shared_system=base_context,
    cache_shared_system=True  # 90% cost reduction for cached content
)

Multi-Turn Conversation with Auto-Caching

For sub-agents that need multiple rounds of conversation:

from claude_client import ConversationThread

# Create a conversation thread (auto-caches history)
agent = ConversationThread(
    system="You are a code refactoring expert with access to the codebase",
    cache_system=True
)

# Turn 1: Initial analysis
response1 = agent.send("Analyze the UserAuth class for issues")
print(response1)

# Turn 2: Follow-up (reuses cached system + turn 1)
response2 = agent.send("How would you refactor the login method?")
print(response2)

# Turn 3: Implementation (reuses all previous context)
response3 = agent.send("Show me the refactored code")
print(response3)

Streaming Responses

For real-time feedback from sub-agents:

from claude_client import invoke_claude_streaming

def show_progress(chunk):
    print(chunk, end='', flush=True)

response = invoke_claude_streaming(
    "Write a comprehensive security analysis...",
    callback=show_progress
)

Parallel Streaming

Monitor multiple sub-agents simultaneously:

from claude_client import invoke_parallel_streaming

def agent1_callback(chunk):
    print(f"[Security] {chunk}", end='', flush=True)

def agent2_callback(chunk):
    print(f"[Performance] {chunk}", end='', flush=True)

results = invoke_parallel_streaming(
    [
        {"prompt": "Security review: ..."},
        {"prompt": "Performance review: ..."}
    ],
    callbacks=[agent1_callback, agent2_callback]
)

Interruptible Operations

Cancel long-running parallel operations:

from claude_client import invoke_parallel_interruptible, InterruptToken
import threading
import time

token = InterruptToken()

# Run in background
def run_analysis():
    results = invoke_parallel_interruptible(
        prompts=[...],
        interrupt_token=token
    )
    return results

thread = threading.Thread(target=run_analysis)
thread.start()

# Interrupt after 5 seconds
time.sleep(5)
token.interrupt()

Core Functions

Full signatures, parameters, and worked examples for each: references/function-reference.md.