Agents and Sub-Agents: Structure, When and Why

TL;DR

• A chat prompt is one request and one answer. A workflow is a fixed path of steps you design. An agent decides its own next step in a loop, using tools, until it judges the job done.
• Start with the simplest thing that works: a good prompt, then a fixed workflow, then one agent with a few tools. Add more agents only when you can show the simpler version fails.
• A sub-agent is a helper agent that gets its own fresh context, does a focused job, and returns a short result. It is useful for keeping the main context clean, running independent work in parallel, and giving a helper narrower tools.
• Costs are real: Anthropic reports agents use about 4 times the tokens of a chat and multi-agent systems about 15 times for its research feature [2]. Errors compound over many steps [35], and parallel agents can make conflicting decisions [28].
• Safety comes from design, not wording: least privilege, human approval for risky actions, and never combining private data, untrusted content and outbound communication in one agent [38][39][41].
• Evaluate on outcomes across repeated runs, not on one impressive demo [7][33].

All product and framework details are "as of 2026-10-17" and may have changed; items marked [VERIFY] could not be confirmed on a stable official page.

1. Chat prompt, workflow, agent: three different things #

People use "agent" loosely, so start with a plain split. Anthropic draws the line this way: in a workflow, code you write decides the path through the model calls and tools; in an agent, the model itself directs its process and tool use [1]. LangChain's documentation uses the same distinction, describing workflows as predetermined code paths and agents as systems that choose their own steps [24]. Microsoft's guidance adds a third rung below both: a single model call with a good prompt [22].

A one-line test: if you can draw the whole flow chart before you start, you want a workflow; if the next step depends on what the last step discovers, consider an agent. Microsoft's agent framework documentation puts the same rule bluntly: if you can write a plain function to do the job, do that instead of using an agent [23].

Try these prompts: choosing the right shape #

• create-ai-workflow-design-0002: Choose Between a Script, a No-Code Flow and an AI Agent
• create-ai-workflow-design-0001: Map a Repetitive Task Into an Automation Spec
• create-ai-workflow-design-0013: Inbox Triage Agent Specification With Human Approval Points
• create-ai-workflow-design-0021: Personal Admin Agent Boundaries and Permissions Plan
• create-ai-governance-safety-0003: Human-in-the-Loop Approval Design
• create-ai-evaluation-testing-0010: Acceptance Criteria for an Automation Project
• audit-ai-agent-workflows-0007: Workflow Automation Inventory Audit: What Runs, Who Owns It, What Breaks
• audit-ai-agent-workflows-0004: Agent Permission and Risk Review for a Proposed Automation
• create-ai-governance-safety-0013: Agent Permission Matrix and Least-Privilege Review

2. The core loop: plan, tools, act, observe #

Every agent, from a coding assistant to a research assistant, runs the same loop. Claude Code's documentation describes it as three phases that blend together: gather context, take action, verify results, repeat [11]. The research version of the idea is ReAct, which interleaves reasoning steps with actions so the model can look things up, check, and correct its plan [29]. Provider documentation for tool calling describes the mechanics: you describe tools to the model; it replies with a request to call one with chosen arguments; your code (not the model) runs it; the result goes back; the model decides what to do next [18][19].

          +-----------------------------+
 goal --> |  MODEL (reads context)      |
          +--------------+--------------+
                         | decides
                         v
                +----------------+
                | PLAN / THINK   |  <-- what is the next step?
                +--------+-------+
                         v
                +----------------+
                | ACT: call tool |  --> search, read file, run code, send...
                +--------+-------+
                         v
                +----------------+
                | OBSERVE result |  --> added back into context
                +--------+-------+
                         |
              done? ---- no ----> loop back to the model
                |
               yes
                v
           final answer (+ evidence)

Two related research ideas explain why the loop is built this way: Reflexion has an agent write short notes about what went wrong after each attempt and keep them in memory for the next try [30], and Toolformer showed that a model can learn when to call tools such as a calculator or search instead of guessing [31].

Three things make or break a loop:

1. A stop condition. Without one, loops run forever or quit early. Google Cloud warns that poorly defined exit conditions cause endless loops [20], and Microsoft recommends iteration limits [22].
2. A way to verify. Claude Code's best-practice guide calls a check the agent can run (tests, a build, a screenshot comparison) the difference between a session you must watch and one you can leave; without it, "looks done" is the only signal [12].
3. Evidence over claims. Anthropic's evaluation guidance says what matters is the real end state, such as whether the booking exists in the database, not the agent's statement that it succeeded [7].

3. The parts of an agent #

Two parts deserve extra attention.

Context is a budget. Anthropic treats context as a finite resource whose value declines as it fills [4], and Claude Code's guide says most of its recommendations follow from that constraint [12]. A third-party study of 18 models found accuracy became less reliable as inputs grew, even on simple tasks, and that distracting but related text made it worse [36]. So agents that read many files or pages should keep only what they need, fetch the rest on demand, and summarise.

Memory comes in layers. Short-term memory is the context window; long-term memory is an external store the agent reads and writes [34]. Practical forms include a progress file, a task list, and git history [5], plus "skills": folders of instructions that load in stages so the agent only reads details when relevant [6].

Try these prompts: agent building blocks #

• create-ai-agent-prompts-tools-0001: System Prompt for a Single-Purpose Assistant
• create-ai-agent-prompts-tools-0002: Tool Description Writer for Function Calling
• create-ai-agent-prompts-tools-0016: Tool Description Writer: Clear Schemas for an Agent's Functions
• create-ai-agent-prompts-tools-0017: Memory Notes Design for a Long-Running Assistant
• create-ai-agent-prompts-tools-0008: Memory and Context Handover Prompt
• create-ai-agent-prompts-tools-0020: Retrieval Instructions: How an Agent Should Use Search Results
• create-ai-agent-prompts-tools-0021: Error Handling Instructions for an Assistant That Uses Tools
• create-ai-agent-prompts-tools-0024: Output Format Contracts: Make Agent Responses Machine-Safe
• create-ai-governance-safety-0014: Audit Log Specification for AI Actions
• audit-ai-agent-workflows-0001: Agent Prompt Audit: Clarity, Conflicts and Missing Rules
• audit-ai-agent-workflows-0003: Tool Description Audit: Overlap, Ambiguity and Missing Error Cases

4. Single-agent versus multi-agent #

A single agent is one model loop with a set of tools. Google Cloud recommends it as the starting point and says to revisit the choice only as requirements change [20]. Microsoft calls it often the right default for enterprise use because it is simpler to debug and test [22].

A multi-agent system uses several model loops that coordinate. Microsoft lists the genuine reasons to go there: a single agent cannot reliably handle the task because of prompt complexity, too many tools, or security boundaries; and the price is coordination overhead, latency and more failure modes [22].

Pros and cons at a glance #

Cognition's widely discussed argument is that parallel sub-agents often fail because each sees only its slice of the task, so their unstated assumptions diverge, as in two helpers building mismatched parts of one app. Their two rules: share the full context (not just the instruction), and remember that every action carries a decision that can conflict with another agent's [28]. Anthropic's team, by contrast, reports a clear gain from a lead agent with parallel sub-agents for open-ended research, while saying the pattern fits tasks that split into independent parts and is a poor fit for tasks that need shared context or have many dependencies between agents [2]. Both can be right: the difference is the task. Research and search split well; tightly coupled editing does not.

5. Multi-agent patterns #

Vendors catalogue overlapping patterns under different names [1][20][22][24]. This table merges them.

Diagram 1: orchestrator and workers #

                      +------------------+
   user goal -------> |   ORCHESTRATOR   |
                      |  plan + delegate |
                      +----+----+----+---+
                           |    |    |
              brief + tools|    |    |brief + tools
                +----------+    |    +-----------+
                v               v                v
          +-----------+   +-----------+    +-----------+
          | WORKER A  |   | WORKER B  |    | WORKER C  |   each: own context,
          | (search)  |   | (search)  |    | (analyse) |   own tools, own limit
          +-----+-----+   +-----+-----+    +-----+-----+
                | short summary | short summary  | short summary
                +-------+-------+----------------+
                        v
                +------------------+
                |   ORCHESTRATOR   |  checks, merges, cites, answers
                +------------------+

Diagram 2: generator and reviewer #

 brief --> [GENERATOR] --draft--> [REVIEWER (fresh context, criteria)]
              ^                         |
              |   fix list + pass/fail  |
              +-------------------------+
                (stop when it passes or after N rounds)

Claude Code's guide notes why a fresh reviewer helps: it sees the diff and criteria, not the reasoning that produced the change. It also warns that a reviewer asked to find gaps will usually find some, so tell it to flag only issues that affect correctness or the stated requirements [12].

Diagram 3: router with human approval #

 request --> [ROUTER] --> billing agent --\
                |-------> tech agent -----+--> [APPROVAL GATE] --> action
                \-------> unknown --------/        (human for refunds,
                                                    deletes, sending)

Try these prompts: patterns in practice #

• create-ai-agent-prompts-tools-0007: Planner and Executor Prompt Pair
• create-ai-agent-prompts-tools-0019: Planner and Executor Prompts for a Multi-Step Task
• create-ai-agent-prompts-tools-0018: Agent Hand-Off Prompt: Passing Work Between Specialist Agents
• create-ai-agent-prompts-tools-0014: Agent Handoff Note Between Two Tools
• create-ai-workflow-design-0024: Support Ticket Routing Agent With Confidence and Fallbacks
• create-ai-workflow-design-0016: Customer Email Drafting Agent With Policy Lookup and Escalation Rules
• create-ai-workflow-design-0015: Research Assistant Agent Loop With Source Tracking
• create-ai-workflow-design-0019: Lead Qualification Agent Rubric and Hand-Off Rules
• create-ai-workflow-design-0023: Content Repurposing Agent: One Source, Many Formats
• create-ai-workflow-design-0009: Lead Follow-Up Sequencing With Guardrails
• create-ai-agent-prompts-tools-0003: Research Agent Instructions With Source Rules

6. What sub-agents are, and why use them #

A sub-agent is an agent started by another agent to do one bounded job. Anthropic's Claude Code documentation describes a sub-agent as a specialised assistant that runs in its own context window with its own system prompt, tool access and permissions, does the task, and returns only a summary to the main conversation [10]. The same page lists the benefits: keeping exploration out of the main context, enforcing tool restrictions, reusing configurations, and routing simple work to cheaper models [10].

Why use them

1. Context isolation. Reading fifty files fills the window; a sub-agent can read them and report five lines. This is the main reason in practice [4][10][12].
2. Parallelism. Independent searches or reviews can run at the same time [2][20].
3. Specialisation. A narrow prompt and a small tool set beat one giant prompt [22].
4. Cost and speed control. Easy sub-tasks can use a smaller model [10].
5. Independent review. A fresh context is less biased toward work it did not write [12].
6. Permission separation. A reviewer may need read-only tools; a deployer may need more. Separate agents allow separate rights [22].

What sub-agents are not

• They are not free. Each uses tokens and counts toward usage limits [2][10].
• They do not automatically share your conversation. In Claude Code, a new sub-agent does not see the main history unless it is a fork [10]; so your delegation message must carry everything it needs [2][28].
• They are not a substitute for clear instructions. Anthropic found that vague delegations produced duplicated work and gaps among sub-agents [2].
• Nesting rules vary. As of 2026-10-17, Claude Code's documentation says sub-agents can themselves spawn sub-agents by default up to a set depth, adjustable by a setting [10]. [VERIFY] before relying on it, because this changes between versions.
• Models can over-delegate. Anthropic notes that some of its models have a strong tendency to spawn sub-agents where a direct search would do, and suggests a rule such as "use sub-agents for parallel, isolated, independent work; otherwise do it directly" [9].

Worked example: should this use sub-agents? #

Try these prompts: delegation and hand-offs #

• create-ai-agent-prompts-tools-0018: Agent Hand-Off Prompt: Passing Work Between Specialist Agents
• create-ai-agent-prompts-tools-0014: Agent Handoff Note Between Two Tools
• create-ai-agent-prompts-tools-0007: Planner and Executor Prompt Pair
• create-ai-agent-prompts-tools-0019: Planner and Executor Prompts for a Multi-Step Task
• create-ai-agent-prompts-tools-0008: Memory and Context Handover Prompt
• create-ai-workflow-design-0015: Research Assistant Agent Loop With Source Tracking
• create-ai-workflow-design-0017: Spreadsheet Reconciliation Agent Plan
• create-ai-workflow-design-0004: Meeting-to-Tasks Pipeline
• create-ai-workflow-design-0014: Meeting-to-Action-Items Agent Workflow

7. When NOT to use an agent #

Use something simpler when:

• One good prompt works. Test this first. Microsoft's complexity ladder starts with a direct model call and advises the lowest level that reliably meets your needs [22]. Anthropic's advice is the same: add complexity only when it measurably improves results [1].
• The steps are known. Use a fixed workflow or an ordinary script [1][23].
• Mistakes are costly and irreversible, and you cannot add a human check.
• Latency or cost matter more than flexibility. Agents and multi-agent systems take more tokens and more time [2].
• You cannot say what "done" looks like or test it. If you cannot define success, you cannot evaluate an agent [7].
• The task is tightly coupled (many interdependent edits): parallel agents will conflict [28].
• You would be giving broad access to private data and untrusted content together (see section 11) [39][41].

Google Cloud also states that for predictable tasks that a single model call can handle, non-agentic approaches are often more cost-effective [20].

Decision flowchart: should I use an agent? #

START: What do I need done?
 |
 v
Can ONE well-written prompt (with pasted material) do it reliably?
 |-- yes --> Use a prompt. STOP.
 |-- no
 v
Can I list all the steps in advance (draw the flow chart)?
 |-- yes --> Build a WORKFLOW (chain, router, parallel steps) or a plain script. STOP.
 |-- no
 v
Can I define "done" and check it automatically or by sampling?
 |-- no  --> Not ready: write success criteria and a test set first. STOP.
 |-- yes
 v
Would a mistake be costly or hard to undo?
 |-- yes --> Add human approval for those actions, narrow tools, a sandbox. Continue.
 |
 v
Try ONE agent with a few well-described tools.
 |
 v
Does it fail because of (a) context overload, (b) truly independent subtasks,
(c) conflicting roles/permissions?
 |-- no  --> Improve prompt, tools, evals. Stay with one agent.
 |-- yes --> Add a sub-agent for THAT problem only, measure cost and quality
             against the single agent. Keep it only if it wins.

Try these prompts: decision and scoping #

• create-ai-workflow-design-0002: Choose Between a Script, a No-Code Flow and an AI Agent
• create-ai-evaluation-testing-0010: Acceptance Criteria for an Automation Project
• create-ai-governance-safety-0002: Risk Register for an AI Feature
• create-ai-governance-safety-0003: Human-in-the-Loop Approval Design
• create-ai-workflow-design-0001: Map a Repetitive Task Into an Automation Spec
• audit-ai-agent-workflows-0007: Workflow Automation Inventory Audit: What Runs, Who Owns It, What Breaks
• create-ai-workflow-design-0021: Personal Admin Agent Boundaries and Permissions Plan
• create-ai-evaluation-testing-0017: Agent Pilot Plan: Safe Rollout to a Small Group

8. Trade-offs: cost, latency, reliability #

The numbers above come from specific vendor tests and benchmarks; use them as orders of magnitude, not guarantees.

9. Failure modes and how to reduce them #

Researchers analysed over 1,600 traces from seven multi-agent frameworks and grouped 14 failure modes into three families: system design problems, misalignment between agents, and weak task verification [32]. Practitioners report the same shapes. Here are the common ones.

10. Guardrails and human-in-the-loop #

Guardrails are checks placed around the agent. OpenAI's Agents SDK describes input checks, output checks, and tool-level checks, which can stop a run when a "tripwire" fires, and documents limits: for example, input checks apply only to the first agent in a chain and output checks to the last, and tool checks do not cover every kind of tool or handoff [17]. The lesson is general: know exactly what each guardrail covers.

Layer your controls:

1. Scope. Give only the tools the job needs. OWASP names excessive functionality, excessive permissions, and excessive autonomy as the three root causes of agent harm [38].
2. Authorise outside the model. Enforce permissions in the systems the tools call, not by asking the model to behave [38].
3. Human approval for high-impact actions. Deleting data, spending money, sending messages, changing shared systems [8][38]. Anthropic's example prompt for this: encourage reversible local actions, ask before destructive or hard-to-reverse ones, and never bypass safety checks as a shortcut [9].
4. Reversibility. Prefer actions you can undo. Claude Code snapshots file edits so they can be rewound, but notes that actions on remote systems cannot be checkpointed [11].
5. Logging. OWASP notes that logging and rate limiting do not prevent harm but limit its damage [38].
6. Approval fatigue. Claude Code's guide observes that after many prompts people click through rather than review, so combine allowlists and sandboxing so that approvals are rare and meaningful [12].

Human-in-the-loop is not just a button. Design where the human looks (before the irreversible step), what they see (the action, the data, the reason), and what happens on "no".

Try these prompts: guardrails and approval #

• create-ai-governance-safety-0003: Human-in-the-Loop Approval Design
• create-ai-governance-safety-0013: Agent Permission Matrix and Least-Privilege Review
• create-ai-governance-safety-0015: Human Escalation Rules for an AI Assistant
• create-ai-governance-safety-0017: Kill Switch and Rollback Plan for Automations
• create-ai-agent-prompts-tools-0022: Confirmation-Before-Action Prompt Pattern
• create-ai-governance-safety-0009: Permissions Review for Connected Tools
• create-ai-governance-safety-0014: Audit Log Specification for AI Actions
• audit-ai-safety-0003: Human-in-the-Loop Design Audit: Where Approvals Add Safety and Where They Add Noise
• audit-ai-agent-workflows-0004: Agent Permission and Risk Review for a Proposed Automation
• create-ai-governance-safety-0008: Incident Response Plan for an AI Mistake

11. Security and permissions #

Agents widen the attack surface because they read outside content and act. Four ideas carry most of the weight.

Prompt injection. Text in an email, web page or file can try to give the agent new orders. OWASP says there is no foolproof prevention and recommends least privilege, labelled untrusted content, output validation, human approval and adversarial testing [37].

The lethal trifecta. Simon Willison's rule: an agent becomes dangerous when it has all three of (1) access to private data, (2) exposure to untrusted content, and (3) a way to send data out [39]. Meta's "Agents Rule of Two" turns this into a design rule: in one session, combine no more than two of untrusted input, sensitive data or systems, and the ability to change state or communicate externally; if a task truly needs all three, require a fresh session with human supervision or another reliable check [41].

Structural patterns. A paper summarised by Willison lists patterns that restrict an agent after it sees untrusted input: an action selector that never reads tool results, fixed plan-then-execute sequences, map-reduce with constrained answers, a dual-model setup where a quarantined model handles untrusted text, and minimising context [40]. These trade flexibility for safety.

Permissions. Claude Code's documentation shows a tiered model: reads are allowed in the working directory, while shell commands, edits, and web fetches ask first, with allowlists and sandboxing to reduce prompts [13]. Anthropic's agent framework stresses human control over high-stakes steps, transparency, and user control over which tools an agent can use [8].

Quick security checklist

• [ ] List every tool and the data it can reach. Remove what is not needed.
• [ ] Use read-only credentials for read-only jobs, scoped to the user [38].
• [ ] Never let one agent have private data, untrusted input and outbound communication together [39][41].
• [ ] Label pasted or fetched content as data, not instructions [37].
• [ ] Require approval for sending, deleting, paying, publishing.
• [ ] Log tool calls with inputs and outputs (and redact secrets).
• [ ] Test with hostile content before launch.
• [ ] Have a kill switch and a rollback plan.

Try these prompts: security #

• audit-ai-safety-0001: Prompt Injection Exposure Audit for Your Own Assistant (Defensive)
• audit-ai-safety-0002: Agent Logging and Privacy Audit
• audit-ai-agent-workflows-0004: Agent Permission and Risk Review for a Proposed Automation
• create-ai-evaluation-testing-0005: Prompt Injection Test Cases for My Assistant
• create-ai-evaluation-testing-0013: Defensive Red-Team Checklist for a Customer Support Agent
• create-ai-governance-safety-0013: Agent Permission Matrix and Least-Privilege Review
• create-ai-governance-safety-0016: Data Handling Rules for Assistants: What Goes In, What Stays Out
• create-ai-governance-safety-0004: Data Handling Rules for Prompts
• create-ai-governance-safety-0017: Kill Switch and Rollback Plan for Automations
• audit-ai-agent-workflows-0008: Data Used in Prompts Audit: Is Anything Sensitive Being Sent?

12. Evaluation and observability #

Anthropic's guide to agent evals gives a vocabulary: a test case (input plus success definition), trials (several attempts, because agents vary), graders (code, model, or human), a transcript (everything that happened), and the outcome (what actually changed). It recommends grading the outcome rather than the exact path, since agents often find valid routes you did not anticipate [7]. It also distinguishes pass@k (at least one of k tries succeeds) from pass^k (all k succeed), which matters when users need consistency [7]. A benchmark of tool-using agents found reliability drops sharply on repeated trials [33].

Anthropic's multi-agent write-up offers a practical starting point: begin with about 20 realistic queries, use an LLM judge with a rubric (accuracy, citation quality, completeness, source quality, tool efficiency), and add human testing to catch what automation misses [2]. Huyen adds checks specific to agents: are plans valid, are tool calls valid, does each tool work alone, and how efficient is the agent against a baseline [35].

Observability basics

Try these prompts: evaluation and monitoring #

• create-ai-evaluation-testing-0012: Agent Test Case Suite Designer
• create-ai-evaluation-testing-0014: Evaluation Rubric for Agent Answers
• create-ai-evaluation-testing-0015: Golden Examples Set: Collecting and Maintaining Reference Answers
• create-ai-evaluation-testing-0007: Human Review Sampling Plan for Automated Output
• create-ai-evaluation-testing-0008: Failure Log and Root Cause Template for AI Workflows
• create-ai-evaluation-testing-0011: Monitoring Dashboard Spec for a Live AI Feature
• audit-ai-evaluation-0001: Test Suite Coverage Audit for an Agent or Assistant
• audit-ai-evaluation-0003: Agent Quality Metrics Dashboard Audit: What to Measure and What to Ignore
• audit-ai-agent-workflows-0002: Agent Run Transcript Review: What Went Wrong and Why
• audit-ai-agent-workflows-0005: Automation Failure Post-Mortem Template and Review of One Incident
• create-ai-evaluation-testing-0017: Agent Pilot Plan: Safe Rollout to a Small Group

13. How to write good agent and sub-agent prompts #

Agent prompts differ from chat prompts because the agent acts. Anthropic advises system prompts "at the right altitude": specific enough to steer, flexible enough to allow judgement, and not a pile of brittle if-then rules; and a few diverse examples rather than a list of every edge case [4]. Claude Code's guidance for instruction files adds a test for each line: would removing this cause mistakes? If not, cut it [12].

The anatomy of an agent prompt #

ROLE AND GOAL
You are a [role] helping [who]. Your goal: [outcome in one sentence].

SUCCESS = [observable definition of done, e.g. "all tests pass and the report
cites a source for every figure"].

TOOLS
- search_orders(customer_id): read-only. Use first. Do not guess IDs.
- issue_refund(order_id, amount): needs approval. Never over 50 without asking.

RULES
- Prefer reversible actions. Ask before anything destructive or visible to others.
- If information is missing or sources conflict, say so; do not guess.
- Stop and report if you have taken more than 15 steps without progress.

PROCESS
1. Restate the task and your plan in two lines.
2. Gather what you need with the read-only tools.
3. Act, then verify with [check]. Show the evidence.

OUTPUT
Return: summary (3 lines), actions taken, evidence, open questions.

The anatomy of a sub-agent brief (delegation message) #

Anthropic's multi-agent write-up found that sub-agents need a detailed objective, an output format, guidance on tools, and clear task boundaries, and that vague briefs caused duplicate work [2]. Cognition adds that the helper should receive the relevant context, not only the instruction [28].

OBJECTIVE   Find the three most-cited objections to [topic] in sources
            published since 2023. (One question only.)
CONTEXT     We are writing a briefing for [audience]; the main claim is [X].
            Already covered by another worker: [Y]. Do not repeat it.
SCOPE       Use web search and the provided PDFs. Do not use social media.
TOOLS       search, fetch_page. Max 10 tool calls.
OUTPUT      A table: objection | source title | date | URL | one-line quote.
            If you cannot verify a source, mark it UNVERIFIED.
STOP WHEN   You have three sourced objections or hit the call limit.
RETURN      Under 200 words. Facts only, no recommendations.

Tool descriptions #

Anthropic's tool-writing guidance: pick a few tools that map to real jobs rather than wrapping every endpoint; merge steps that always occur together; use clear names and prefixes; return readable, meaningful results; keep outputs compact with pagination or filters; make errors explain how to fix the call; and describe each tool as you would onboard a new colleague [3]. OpenAI's function-calling guide agrees on clear descriptions of when to use and not use a function, enums and typed objects to rule out invalid inputs, and limiting the number of functions exposed at once [18].

{
  "name": "search_orders",
  "description": "Find a customer's orders. Use when the user asks about an order status. Returns up to 5 recent orders (id, date, status, total). Do NOT use for refunds; use issue_refund. If no match, returns an empty list.",
  "parameters": {
    "customer_email": {"type": "string", "description": "Exact email address on the account"},
    "status": {"type": "string", "enum": ["open", "shipped", "cancelled", "any"]}
  }
}

Try these prompts: agent and sub-agent prompts #

• create-ai-agent-prompts-tools-0001: System Prompt for a Single-Purpose Assistant
• create-ai-agent-prompts-tools-0002: Tool Description Writer for Function Calling
• create-ai-agent-prompts-tools-0016: Tool Description Writer: Clear Schemas for an Agent's Functions
• create-ai-agent-prompts-tools-0007: Planner and Executor Prompt Pair
• create-ai-agent-prompts-tools-0019: Planner and Executor Prompts for a Multi-Step Task
• create-ai-agent-prompts-tools-0018: Agent Hand-Off Prompt: Passing Work Between Specialist Agents
• create-ai-agent-prompts-tools-0015: System Prompt for a Scheduling Assistant With Clear Limits
• create-ai-agent-prompts-tools-0021: Error Handling Instructions for an Assistant That Uses Tools
• create-ai-agent-prompts-tools-0023: Persona and Boundary Prompt for a Customer-Facing Assistant
• create-ai-agent-prompts-tools-0009: Browser Task Agent Instructions With Safety Limits
• audit-ai-agent-workflows-0001: Agent Prompt Audit: Clarity, Conflicts and Missing Rules
• audit-ai-agent-workflows-0003: Tool Description Audit: Overlap, Ambiguity and Missing Error Cases

14. File and context hand-off conventions #

Because each agent or session starts without the last one's memory, you need a written hand-off. Patterns drawn from the sources:

Suggested minimal hand-off file:

HANDOFF.md
Goal:            [one sentence]
Done:            [bullets with evidence/links]
In progress:     [item, state, next step]
Decisions made:  [decision, reason] (do not reopen without cause)
Open questions:  [for the human]
Do not touch:    [files/areas]
How to verify:   [commands/checks]

Try these prompts: hand-offs and memory #

• create-ai-agent-prompts-tools-0008: Memory and Context Handover Prompt
• create-ai-agent-prompts-tools-0014: Agent Handoff Note Between Two Tools
• create-ai-agent-prompts-tools-0017: Memory Notes Design for a Long-Running Assistant
• create-ai-agent-prompts-tools-0018: Agent Hand-Off Prompt: Passing Work Between Specialist Agents
• create-ai-workflow-design-0008: Weekly Report Compilation Flow
• create-ai-workflow-design-0018: Weekly Report Agent: From Raw Updates to a One-Page Summary
• create-ai-workflow-design-0014: Meeting-to-Action-Items Agent Workflow
• create-ai-governance-safety-0014: Audit Log Specification for AI Actions

15. Example architectures #

A. Personal admin assistant (one agent, human approval). One agent with read-only calendar and email search, a draft-only email tool, and an approval gate before sending or booking. No sub-agents: the task is small and sequential.

B. Research assistant (orchestrator and workers). A lead agent plans three to five sub-questions, spawns workers with separate briefs, each returns a table of sourced claims; a final step checks every claim against a source and removes the unsupported ones. This follows the lead-plus-sub-agents shape Anthropic describes, including a separate citation step [2].

C. Support triage (router plus specialists). A router classifies tickets; specialists handle billing, technical or account questions with different tools; refunds above a threshold require approval. This is the router/handoff pattern [1][16].

D. Coding change (single agent plus independent reviewer). One agent plans, edits and runs tests; a reviewer sub-agent with read-only tools checks the diff against the plan and criteria [12].

E. Long-running build (initializer and workers across sessions). An initializer creates the task list, progress log and first commit; later sessions each take one item, test it, commit, and update notes [5].

Try these prompts: end-to-end designs #

• create-ai-workflow-design-0013: Inbox Triage Agent Specification With Human Approval Points
• create-ai-workflow-design-0015: Research Assistant Agent Loop With Source Tracking
• create-ai-workflow-design-0021: Personal Admin Agent Boundaries and Permissions Plan
• create-ai-workflow-design-0024: Support Ticket Routing Agent With Confidence and Fallbacks
• create-ai-workflow-design-0017: Spreadsheet Reconciliation Agent Plan
• create-ai-workflow-design-0022: Multi-Step Trip Planning Agent With Budget Guardrails
• create-ai-workflow-design-0016: Customer Email Drafting Agent With Policy Lookup and Escalation Rules
• create-ai-workflow-design-0020: Document Intake Agent for Forms, Receipts and Contracts
• create-ai-workflow-design-0025: Invoice Processing Agent With Approval Thresholds
• create-ai-workflow-design-0028: Hiring Screen Assistant With Fairness Guardrails

16. Protocols and frameworks (as of 2026-10-17) #

Frameworks help, but Anthropic notes the most successful implementations it saw used simple, composable patterns rather than heavy frameworks, and cautions that frameworks can hide the prompts and responses you need to debug [1]. Know what the framework does before you adopt it.

17. Common mistakes #

18. Checklist: before you launch an agent #

• [ ] I tried a single prompt and a fixed workflow and wrote down why they failed.
• [ ] The goal and the definition of done are written in one place.
• [ ] Each tool has one job, a clear description, typed parameters, and minimum permissions.
• [ ] Irreversible or external actions require human approval.
• [ ] There is a step limit, a cost limit, and a stop rule.
• [ ] The agent verifies work with a check it can run, and shows evidence.
• [ ] For sub-agents: each brief has objective, context, scope, tools, output format.
• [ ] Hand-off files exist for long or multi-session work.
• [ ] I have a test set of realistic tasks, multiple trials, and an outcome grader.
• [ ] Logging captures transcripts, tool calls, costs and approvals.
• [ ] I ran hostile-content tests and applied the Rule of Two.
• [ ] A kill switch and rollback plan exist.

19. Glossary #

• Agent: an application where a model plans its own steps and calls tools in a loop until it decides the task is done [14].
• Workflow: a predefined path of model calls and tools controlled by code [1].
• Harness: the code around a model that supplies tools, context management and permissions [11].
• Tool / function calling: the model requests a function with arguments; your code runs it and returns the result [18].
• Sub-agent: a helper agent with its own context, instructions and tools that returns a result to a parent [10].
• Orchestrator: the agent that plans and delegates to workers [1].
• Router: a classifier that sends input to the right specialist [1].
• Handoff: transferring control of a conversation to another agent [16].
• Evaluator-optimizer: a generate-critique-improve loop [1].
• Context window: the text the model can consider at once.
• Context engineering: curating everything that enters the context, not only the prompt [4].
• Compaction: summarising a long context to continue in a fresh window [4].
• Guardrail: a check on inputs, outputs or actions [17].
• Human-in-the-loop: a person approves or reviews at defined points [20].
• Prompt injection: malicious instructions hidden in content the agent reads [37].
• Least privilege: giving only the permissions the job needs [38].
• Trial / pass@k / pass^k: repeated attempts; at least one success; all successes [7].
• MCP / A2A: standards for agent-to-tool and agent-to-agent communication [26][27].

Sources #

All sources accessed 2026-10-17. Dates are those shown on the page ("none shown" if absent). Numbers match the bracketed citations.

1. Building effective agents. Anthropic Engineering. https://www.anthropic.com/engineering/building-effective-agents (2024-12-19)
2. How we built our multi-agent research system. Anthropic. https://www.anthropic.com/engineering/multi-agent-research-system (2025-06-13)
3. Writing effective tools for agents. Anthropic Engineering. https://www.anthropic.com/engineering/writing-tools-for-agents (2025-09-11)
4. Effective context engineering for AI agents. Anthropic Engineering. https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents (2025-09-29)
5. Effective harnesses for long-running agents. Anthropic Engineering. https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents (2025-11-26)
6. Equipping agents for the real world with Agent Skills. Anthropic Engineering. https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills (2025-10-16)
7. Demystifying evals for AI agents. Anthropic Engineering. https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents (2026-01-09)
8. Our framework for developing safe and trustworthy agents. Anthropic. https://www.anthropic.com/news/our-framework-for-developing-safe-and-trustworthy-agents (2025-08-04)
9. Prompting best practices. Anthropic docs. https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices (none shown)
10. Create custom subagents. Claude Code docs. https://code.claude.com/docs/en/sub-agents (none shown)
11. How Claude Code works. Claude Code docs. https://code.claude.com/docs/en/how-claude-code-works (none shown)
12. Best practices for Claude Code. Claude Code docs. https://code.claude.com/docs/en/best-practices (none shown)
13. Configure permissions. Claude Code docs. https://code.claude.com/docs/en/permissions (none shown)
14. Agent SDK overview. Claude Code docs. https://code.claude.com/docs/en/agent-sdk/overview (none shown)
15. OpenAI Agents SDK. OpenAI. https://openai.github.io/openai-agents-python/ (none shown)
16. Handoffs. OpenAI Agents SDK docs. https://openai.github.io/openai-agents-python/handoffs/ (none shown)
17. Guardrails. OpenAI Agents SDK docs. https://openai.github.io/openai-agents-python/guardrails/ (none shown)
18. Function calling. OpenAI. https://developers.openai.com/api/docs/guides/function-calling (none shown)
19. Function calling with the Gemini API. Google AI for Developers. https://ai.google.dev/gemini-api/docs/function-calling (none shown)
20. Choose a design pattern for your agentic AI system. Google Cloud Architecture Center. https://docs.cloud.google.com/architecture/choose-design-pattern-agentic-ai-system (last reviewed 2026-05-28)
21. Template agent workflows. Google Agent Development Kit docs. https://adk.dev/agents/workflow-agents/ (none shown)
22. AI Agent Orchestration Patterns. Microsoft Learn, Azure Architecture Center. https://learn.microsoft.com/en-us/azure/architecture/ai-ml/guide/ai-agent-design-patterns (page metadata: 2026-02-12, updated 2026-09-21)
23. Microsoft Agent Framework Overview. Microsoft Learn. https://learn.microsoft.com/en-us/agent-framework/overview/ (2026-07-29)
24. Workflows and agents. LangChain (LangGraph) docs. https://docs.langchain.com/oss/python/langgraph/workflows-agents (none shown)
25. Crews. crewAI docs. https://docs.crewai.com/en/concepts/crews (none shown)
26. What is the Model Context Protocol (MCP)? https://modelcontextprotocol.io/docs/getting-started/intro (none shown)
27. A2A Protocol. Linux Foundation. https://a2a-protocol.org/latest/ (none shown)
28. Yan, W. Don't Build Multi-Agents. Cognition. https://cognition.com/blog/dont-build-multi-agents (2025-06-12)
29. Yao et al. ReAct: Synergizing Reasoning and Acting in Language Models. arXiv. https://arxiv.org/abs/2210.03629 (2022; rev. 2023)
30. Shinn et al. Reflexion: Language Agents with Verbal Reinforcement Learning. arXiv. https://arxiv.org/abs/2303.11366 (2023)
31. Schick et al. Toolformer: Language Models Can Teach Themselves to Use Tools. arXiv. https://arxiv.org/abs/2302.04761 (2023)
32. Cemri et al. Why Do Multi-Agent LLM Systems Fail? arXiv. https://arxiv.org/abs/2503.13657 (2025)
33. Yao et al. tau-bench: A Benchmark for Tool-Agent-User Interaction in Real-World Domains. arXiv. https://arxiv.org/abs/2406.12045 (2024)
34. Weng, L. LLM Powered Autonomous Agents. https://lilianweng.github.io/posts/2023-06-23-agent/ (2023-06-23)
35. Huyen, C. Agents. https://huyenchip.com/2025/01/07/agents.html (2025-01-07)
36. Context Rot: How Increasing Input Tokens Impacts LLM Performance. Chroma. https://www.trychroma.com/research/context-rot (2025-07-14)
37. LLM01:2025 Prompt Injection. OWASP Gen AI Security Project. https://genai.owasp.org/llmrisk/llm01-prompt-injection/ (2025)
38. LLM06:2025 Excessive Agency. OWASP Gen AI Security Project. https://genai.owasp.org/llmrisk/llm062025-excessive-agency/ (2025)
39. Willison, S. The lethal trifecta for AI agents. https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/ (2025-06-16)
40. Willison, S. Design Patterns for Securing LLM Agents against Prompt Injections. https://simonwillison.net/2025/Jun/13/prompt-injection-design-patterns/ (2025-06-13)
41. Agents Rule of Two: A Practical Approach to AI Agent Security. Meta. https://ai.meta.com/blog/practical-ai-agent-security/ (2025-10-31)

Last updated: 2026-10-17