Reusable Patterns for Claude Managed Agents

The third time you build a Claude Managed Agent, you stop reinventing structure and start reaching for patterns. The same shapes keep working: how you frame the orchestrator's job, how you scope a tool so the model uses it correctly, how you pass context to a subagent without drowning it. This post is a pattern catalog — reusable, code-level building blocks for outcome-driven and multi-agent systems on Claude, with the prompt scaffolding that makes each one reliable.

Patterns are not rules; they are defaults that survive contact with production. Each one below earned its place by failing first in some other form. I will show the shape, the prompt or schema that anchors it, and the failure mode it prevents.

Key takeaways

• Give the orchestrator a role contract, not a task list — it plans better when it understands its job than when it follows steps.
• Tool descriptions are prompts; write the when and the guardrails, not just the what.
• Pass subagents a context slice — goal, inputs, and acceptance test — never the full transcript.
• Make every result structured and self-describing so the orchestrator can reconcile without re-deriving.
• Encode the success rubric as data the verifier can iterate over, not prose it must interpret.

Pattern 1: the orchestrator role contract

The most common mistake is prompting the orchestrator like a script: "First do X, then Y." That fights the model's strength. Instead, give it a role and a contract. Tell it what it is responsible for, what tools and subagents it commands, what "done" means, and what it must never do. Then let it plan.

You are the orchestrator for a reconciliation outcome.
RESPONSIBILITY: deliver a report meeting every success criterion below.
YOU COMMAND: subagents [ledger_fetcher, invoice_fetcher, comparator].
DONE WHEN: all criteria pass the verifier.
NEVER: mutate external systems; trust a subagent's "done" without
       checking its output against the criteria.
SUCCESS CRITERIA:
  - every invoice line matched or flagged
  - totals recomputed independently

This framing consistently produces better decompositions because the model owns the goal rather than executing a brittle recipe. When inputs surprise it, a role-contracted orchestrator adapts; a scripted one derails.

The "NEVER" clauses earn their keep more than any other part of the contract. They are cheap to write and they close off whole categories of failure: an orchestrator that knows it must never mutate external systems will route mutations to a gated tool rather than improvising one; an orchestrator told never to trust an unverified "done" will actually invoke the verifier instead of taking a worker's word. Treat the never-list as a small policy the model carries through every turn. When you discover a new failure mode in a trace, the fix often belongs here as one more line, not as a rewrite of the whole prompt.

Pattern 2: tools as guarded, self-documenting functions

A tool definition is read by the model every turn, so it is prompt real estate. The pattern: each description states what the tool does, when to reach for it, and what not to do with it. Inputs are tightly typed; outputs are structured so the next step does not have to parse prose.

flowchart TD
  A["Orchestrator role contract"] --> B["Plan: decompose outcome"]
  B --> C["Select tool by description"]
  C --> D{"Inputs valid vs schema?"}
  D -->|No| E["Repair args, retry once"]
  D -->|Yes| F["Tool returns structured result"]
  F --> G["Attach result to durable state"]
  G --> H["Reconcile vs success rubric"]

The validate-and-repair node in that flow is itself a pattern: when arguments fail the schema, let the model see the validation error and retry once before escalating. Most argument errors are self-correcting if you feed the error back; blind retries without the error are just dice rolls.

Pattern 3: the context slice for subagents

Subagents fail when they are handed too much. The pattern is to construct a minimal context slice: the subtask goal, only the inputs it needs, and an explicit acceptance test it can self-check against. Everything else — the report's narrative, the orchestrator's reasoning — stays out.

subagent_brief = {
  "goal": "Fetch all PO lines for vendor V-204, Q1.",
  "inputs": {"vendor_id": "V-204",
             "start_date": "2026-01-01",
             "end_date": "2026-03-31"},
  "acceptance": "Return one row per PO line; non-empty if POs exist; "
                "include line_id, qty, unit_price.",
  "tools_allowed": ["get_purchase_orders"]
}

The acceptance field is the quiet hero. It lets the subagent grade its own output before returning, which catches empty or malformed results at the edge instead of letting them poison the comparison three steps later.

There is a subtle discipline here worth naming: the slice should be built by the orchestrator at delegation time, not copied wholesale from its own context. It is easy to slip into handing a subagent "everything I know so far" because it feels safer. It is not. A subagent that receives the orchestrator's full reasoning starts second-guessing the plan instead of executing its slice, and it burns tokens re-deriving decisions that were already made. The slice is a contract: here is your goal, here are your inputs, here is how you know you succeeded, and nothing else is your concern.

Pattern 4: structured, self-describing results

Make every subagent return a typed object with a status, the payload, and a short note — never a free-text blob the orchestrator must re-parse. When results are structured, reconciliation becomes a comparison over fields, not an act of reading comprehension. A worker that returns {"status": "ok", "rows": [...], "note": "12 PO lines, 1 zero-qty"} is trivially reconcilable; one that returns a paragraph is not.

This pattern also makes runs debuggable. When something goes wrong, a structured trace tells you exactly which subagent returned what, with what status. Free-text traces force you to re-read the model's prose to reconstruct what happened. The note field is where you let the worker editorialize briefly — a one-line human-readable summary that helps you skim a trace — while the status and payload stay strictly machine-consumable.

A useful refinement is to standardize the result envelope across every subagent type so the orchestrator never has to special-case shapes. Whether a subagent fetched rows, ran a comparison, or summarized findings, it returns the same outer object — status, payload, note — and the payload varies underneath. That uniformity means your reconciliation logic, and the verifier, can be written once against the envelope rather than re-implemented per subagent. It also makes adding a new subagent type cheap: as long as it speaks the envelope, the orchestrator already knows how to consume it.

Pattern 5: the rubric-as-data verifier

Encode success criteria as a list the verifier iterates over, each with an id, an assertion, and a how-to-check note. The verifier then returns a per-criterion verdict, not a single thumbs-up. This turns "did it pass?" into "which criteria passed and which failed?" — which is what the orchestrator needs to decide whether to iterate and on what.

Pattern	Prevents	Anchor
Role contract	Brittle scripted plans	System prompt
Guarded tools	Misuse, opaque calls	Tool description + schema
Context slice	Drowned subagents	Subagent brief
Structured results	Re-parse errors	Typed return object
Rubric-as-data	Vague pass/fail	Criteria list

Common pitfalls

• Scripting the orchestrator. Step-by-step prompts break on novel input. Give a role and a goal instead.
• Thin tool descriptions. "Gets data" tells the model nothing. State when to use it and what not to do.
• Fat subagent context. The full transcript dilutes attention. Pass a slice with an acceptance test.
• Prose results. Free-text returns force re-parsing and hide failures. Return typed objects.
• Single-bit verdicts. A lone pass/fail can't guide iteration. Verify per criterion.

Apply the patterns in 5 steps

1. Rewrite your orchestrator prompt as a role contract with explicit "never" clauses.
2. Audit each tool description: does it say when and what not to do?
3. Replace full-transcript handoffs with a context slice plus acceptance test.
4. Make every subagent return a typed object with status and note.
5. Convert your success criteria into a rubric list and have the verifier report per item.

Frequently asked questions

Why is a role contract better than step-by-step instructions?

Because Claude plans well when it owns the goal but follows recipes poorly when inputs deviate. A role contract states responsibility, authority, and constraints, then lets the model decompose — which adapts gracefully to surprises that a fixed script would crash on.

How small should a context slice be?

As small as the subtask's acceptance test allows. Include the goal, the exact inputs, the allowed tools, and a checkable definition of success — and nothing about other subtasks. If removing a piece of context would not change whether the subagent can pass its acceptance test, leave it out.

Do these patterns work outside Managed Agents?

Yes. They are general agent-engineering patterns; the role contract, guarded tools, context slices, structured results, and rubric-as-data all apply equally when you write your own loop with the Agent SDK. Managed Agents just give you a runtime that expects work shaped this way.

Patterns that hold up on the phone

CallSphere leans on these exact patterns to keep voice and chat agents reliable under live pressure — role-contracted orchestration, guarded tools, and verified outcomes per call. Hear the patterns at work at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.