0Pricing
Claude Architect · Lesson

Support Agent & Multi-Agent Research

Escalation, hooks, hub-and-spoke and synthesis with citations.

Support Agent & Multi-Agent Research is a free Claude Architect lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Claude Architect learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Two Scenarios, One Lesson

The exam shows you 4 of 8 scenarios. Two of the highest-value ones share a hidden spine: Scenario 1 (Customer Support Agent) and Scenario 3 (Multi-Agent Research System). Both are really about the same architect-grade judgment — when a model decides, and when deterministic code must guarantee.

  • Support Agent: identity preconditions, hook-enforced policy, and disciplined escalation.
  • Multi-Agent Research: a hub-and-spoke coordinator that fans out, then synthesises findings with citations and coverage annotations.

This lesson walks the decisions an examiner tests on both, weighted toward Domain 1 (Orchestration, 27%) with strong pulls from Tool Design, Prompt Engineering, and Reliability.

Preconditions Before Side Effects

The support agent has four tools: get_customer, lookup_order, process_refund, and escalate_to_human. The first decision the exam tests: a refund is a side effect, so it must be gated behind a verified identity.

A programmatic precondition — block process_refund until get_customer has returned a verified ID — is a deterministic guarantee. Prompt guidance ("please verify the customer first") is roughly 90% probabilistic; it will eventually let an unverified refund through. For an action with financial consequence, that gap is unacceptable.

# The precondition lives in HARD CODE, not the prompt.
def handle_refund(state, args):
    if not state.get("verified_customer_id"):
        return {
            "is_error": True,
            "errorCategory": "permission",
            "message": "Identity not verified. Call get_customer first.",
        }
    return process_refund(args)

Multiple Matches: Ask, Never Guess

A subtle but frequently-tested case: get_customer returns more than one match. The wrong answer picks the first row, or the highest-spending account, or guesses by recency. The right answer asks for more identifiers.

Guessing identity on an account that can issue refunds is exactly the kind of unrecoverable, high-stakes mistake the precondition was meant to prevent. When the input is ambiguous, the model's job is to disambiguate with the user — request an order number, email, or postal code — not to resolve the ambiguity on its own.

Hooks: 100% Deterministic Enforcement

Suppose policy says refunds over $500 require a manager. A system prompt that says "never refund more than $500 without approval" is probabilistic — it holds most of the time and fails silently the rest. When failure has financial, legal, or safety consequences, you reach for a hook.

  • An outgoing-call hook intercepts the action before it executes and blocks any policy-violating call.
  • A PostToolUse hook intercepts a tool's result before the model sees it — useful for redaction or for injecting a verified fact.

Hooks are 100% deterministic; prompts are ~90% probabilistic. That number is the whole answer on these questions.

A Hook That Blocks a $500 Refund

Here the guarantee is enforced in code that the model cannot talk its way past. Even if a clever user convinces the agent to attempt a $900 refund, the hook denies the call outright.

On the exam, any answer that enforces a hard money/legal/safety rule with prompt wording alone is a distractor. The deterministic option wins.

# Outgoing-call hook: deterministic policy gate.
def before_process_refund(call):
    if call.tool == "process_refund" and call.input["amount"] > 500:
        return {
            "decision": "block",
            "reason": "Refunds over $500 require human approval.",
        }
    return {"decision": "allow"}
# Prompts persuade; hooks guarantee.

Escalation: Good Triggers vs Bad Triggers

Escalation is where most candidates lose points. Memorise the two lists.

Good triggers (escalate):

  • An explicit human request — escalate immediately, no further attempts.
  • A policy gap the agent has no rule for.
  • No progress after genuine attempts.
  • A threshold violation (e.g. refund over the policy cap).

Bad triggers (never escalate on these):

  • Sentiment analysis of the customer's tone.
  • The model's own self-rated confidence ("I'm 4/10 sure").
  • Untrained classifiers.

Sentiment and self-rated confidence are unreliable signals; building escalation on them is a classic anti-pattern.

The Emotion-Handling Pattern

An upset customer is not, by itself, an escalation trigger. The exam-correct sequence is a three-step pattern:

  1. Acknowledge the emotion — briefly and genuinely.
  2. Propose a concrete solution — try to actually solve the problem.
  3. Escalate only if the request is reiterated — i.e. the customer explicitly asks again for a human, or the solution doesn't land.

This keeps a human in the loop for the cases that truly need one, without routing every frustrated message to a person. Note the contrast with an explicit "get me a human" — that you escalate immediately.

# Emotion != escalation. Reiteration or explicit ask = escalation.
# 1. acknowledge -> 2. propose solution -> 3. escalate if repeated
if user_explicitly_requested_human:
    escalate_to_human(reason="explicit request")  # immediate
elif solution_offered and user_reiterated_request:
    escalate_to_human(reason="unresolved after attempt")

Pivot: The Research Coordinator

Now Scenario 3. A research question spanning five sources is too much for one agent — attention dilutes and the context window fills with noise. The fix is hub-and-spoke: a coordinator decomposes the question and delegates each slice to a focused specialist subagent.

The coordinator owns five jobs: decompose, delegate, aggregate, route, handle errors. Delegation is itself a tool call, so the coordinator's allowedTools must include "Task". Each specialist is an AgentDefinition (name, description, system_prompt, allowed_tools) with a least-privilege tool set.

coordinator = AgentDefinition(
    name="research_lead",
    description="Decomposes a research question, delegates to specialists, synthesises a cited answer.",
    system_prompt="Decompose the question, delegate each part via Task, then synthesise findings with citations.",
    allowed_tools=["Task"],  # REQUIRED, or it cannot delegate
)

Context Isolation and Parallel Fan-Out

The most-tested fact about subagents: they do not inherit the coordinator's conversation history. Each one starts clean and knows only what the coordinator writes into its Task prompt. If a constraint, date window, or prior finding matters, the coordinator must restate it explicitly — every time.

This isolation is a feature: it keeps each spoke's context focused. And because multiple Task calls emitted in one response run in parallel, the coordinator fans out across independent sources simultaneously.

  • Parallel Task calls for independent sub-tasks (different sources/files).
  • Sequential delegation when a later step depends on an earlier result.
# Fan out to independent sources in ONE response -> parallel execution.
task(subagent="web_specialist",     prompt=CONTEXT + "Find 2025 EV adoption stats. Cite each.")
task(subagent="filings_specialist", prompt=CONTEXT + "Pull Q4 revenue from the 10-K. Cite the page.")
task(subagent="news_specialist",    prompt=CONTEXT + "Summarise regulatory changes. Cite source + date.")

Errors and Partial Results, Not Aborts

One subagent failing must not abort the whole research run. The exam wants structured error propagation and graceful degradation:

  • Distinguish an access failure (retryable?) from a valid empty result (no matches — a real answer).
  • Recover transient faults locally inside the subagent; only escalate the non-recoverable.
  • When escalating, carry partial results and structured context: failure type, attempted query, alternatives.
  • Annotate coverage gaps in the final report — say what you couldn't reach, never silently suppress it.

A generic "Operation failed" blocks intelligent routing; a structured error (with errorCategory and isRetryable) enables it.

# Subagent returns structure, not a bare string.
return {
    "is_error": True,
    "errorCategory": "transient",   # transient | validation | business | permission
    "isRetryable": True,
    "attempted_query": "site:sec.gov 10-K revenue",
    "partial_results": rows_collected_so_far,
    "message": "Source timed out after 2 retries; partial data attached.",
}

Synthesis With Provenance

The coordinator's final job is synthesis — and on the exam, synthesis without provenance is wrong. Keep an explicit claim→source mapping for every assertion: URL, document name, the quote, and the publication date.

  • When two sources conflict, annotate the discrepancy rather than arbitrarily picking one. Dates often resolve the apparent contradiction (an old figure vs a current one).
  • Render by content type: tables for financials, prose for news, lists for technical findings.
  • State coverage explicitly — which sub-questions were fully answered, partially answered, or unreachable.

A confident, well-formatted answer with no traceable sources is a trap; the cited, coverage-annotated answer is the architect-grade one.

Exam Scenario

A support agent confirms exactly one customer via get_customer and the customer, sounding frustrated, asks for a $750 refund. Company policy caps automated refunds at $500. Which design is exam-correct?

Key Takeaways

Across both scenarios, the same architect instincts decide the answer:

  • Guarantee with code, persuade with prompts. Identity preconditions and money/legal/safety caps go in hooks and programmatic checks — never prompt wording alone.
  • Escalate on objective signals (explicit request, policy gap, no progress, threshold violation). Never on sentiment, self-rated confidence, or untrained classifiers.
  • Emotion pattern: acknowledge → propose a solution → escalate only if reiterated. Explicit human requests escalate immediately. Ambiguous identity → ask, don't guess.
  • Hub-and-spoke: coordinator decomposes, delegates via "Task", aggregates. Subagents inherit no history — pass context explicitly. Independent slices run in parallel.
  • Fail gracefully: structured errors with errorCategory/isRetryable, recover transient faults locally, carry partial results, annotate coverage gaps.
  • Synthesise with provenance: claim→source mappings, conflict annotations resolved by date, render by content type.

Match the enforcement mechanism to the cost of failure, and you'll pick the right answer every time.

Frequently asked questions

Is the “Support Agent & Multi-Agent Research” lesson free?

Yes — the full text of “Support Agent & Multi-Agent Research” is free to read here on the web, and the Claude Architect course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Claude Architect course, upgrade to CoddyKit PRO.

What will I learn in “Support Agent & Multi-Agent Research”?

Escalation, hooks, hub-and-spoke and synthesis with citations. You practise Claude Architect with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Claude Architect?

No prior experience is required. Claude Architect on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Support Agent & Multi-Agent Research” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Claude Architect lesson?

Yes. Every Claude Architect lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Support Agent & Multi-Agent Research
  2. Code Gen & Developer Productivity
  3. CI/CD & Structured Extraction
  4. Conversational Patterns & Agentic Tools
← Back to Claude Architect