const{Fragment:e,jsx:n,jsxs:l}=arguments[0];function _createMdxContent(r){const s={a:"a",code:"code",figure:"figure",h1:"h1",h2:"h2",h3:"h3",hr:"hr",li:"li",ol:"ol",p:"p",pre:"pre",span:"span",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...r.components};return l(e,{children:[n(s.h1,{children:"Claude Agent Architecture: Tools, Guardrails, and Multi-Agent Patterns"}),"\n",n(s.p,{children:"Claude is a reasoning engine. It doesn't take actions by itself. The\narchitecture you build around it — the tools, the memory layer, the error\nhandling, the human checkpoints — determines whether you ship something\npowerful or something fragile. This article is the reference guide engineers\nbookmark: how to design each layer correctly, and when each pattern actually\nmakes sense."}),"\n",n(s.h2,{children:"Single-Agent vs Multi-Agent: The Real Trade-off"}),"\n",n(s.p,{children:"The default assumption should be: start with a single agent. Multi-agent\nsystems are genuinely more powerful for certain workloads, but they cost\nroughly 58% more in token overhead for independent topologies and up to 285%\nmore for centralized orchestration. That overhead only pays off when your task\nhas at least one of three characteristics:"}),"\n",l(s.ol,{children:["\n",l(s.li,{children:[n(s.strong,{children:"Parallelism is possible"})," — subtasks are independent and can run concurrently"]}),"\n",l(s.li,{children:[n(s.strong,{children:"Specialization matters"})," — different domains need different system prompts and context"]}),"\n",l(s.li,{children:[n(s.strong,{children:"The context window is the bottleneck"})," — one agent would need too much information to function well"]}),"\n"]}),"\n",n(s.p,{children:"For a support agent, a code reviewer, or a content generator: single agent,\nwell-prompted, well-tooled. For a research pipeline that fans out to 10\nsources simultaneously, or a SaaS backend where different agents own different\ndomains — multi-agent pays off."}),"\n",n(s.h2,{children:"Tool Design: The Foundation"}),"\n",n(s.p,{children:"Tools are the interface between Claude's reasoning and your system. Getting the\nschema right is the most important architecture decision you'll make."}),"\n",n(s.h3,{children:"Type Everything with Zod"}),"\n",n(s.p,{children:"Define tool schemas in TypeScript first, derive the JSON Schema from them, and\nvalidate all tool outputs against the same types. Never hand-write JSON Schema\nfor a tool — you'll have a type mismatch within a week."}),"\n",n(s.figure,{"data-rehype-pretty-code-figure":"",children:n(s.pre,{tabIndex:"0","data-language":"typescript","data-theme":"github-dark-dimmed",children:l(s.code,{"data-language":"typescript","data-theme":"github-dark-dimmed",style:{display:"grid"},children:[l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"import"}),n(s.span,{style:{color:"#ADBAC7"},children:" { z } "}),n(s.span,{style:{color:"#F47067"},children:"from"}),n(s.span,{style:{color:"#96D0FF"},children:' "zod"'}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"import"}),n(s.span,{style:{color:"#ADBAC7"},children:" zodToJsonSchema "}),n(s.span,{style:{color:"#F47067"},children:"from"}),n(s.span,{style:{color:"#96D0FF"},children:' "zod-to-json-schema"'}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:"// Define the input schema"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"const"}),n(s.span,{style:{color:"#6CB6FF"},children:" LookupOrderInput"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#ADBAC7"},children:" z."}),n(s.span,{style:{color:"#DCBDFB"},children:"object"}),n(s.span,{style:{color:"#ADBAC7"},children:"({"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" order_id: z."}),n(s.span,{style:{color:"#DCBDFB"},children:"string"}),n(s.span,{style:{color:"#ADBAC7"},children:"()."}),n(s.span,{style:{color:"#DCBDFB"},children:"describe"}),n(s.span,{style:{color:"#ADBAC7"},children:"("}),n(s.span,{style:{color:"#96D0FF"},children:'"The order ID to look up (e.g. ORD-12345)"'}),n(s.span,{style:{color:"#ADBAC7"},children:"),"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" include_shipping: z"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" ."}),n(s.span,{style:{color:"#DCBDFB"},children:"boolean"}),n(s.span,{style:{color:"#ADBAC7"},children:"()"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" ."}),n(s.span,{style:{color:"#DCBDFB"},children:"default"}),n(s.span,{style:{color:"#ADBAC7"},children:"("}),n(s.span,{style:{color:"#6CB6FF"},children:"false"}),n(s.span,{style:{color:"#ADBAC7"},children:")"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" ."}),n(s.span,{style:{color:"#DCBDFB"},children:"describe"}),n(s.span,{style:{color:"#ADBAC7"},children:"("}),n(s.span,{style:{color:"#96D0FF"},children:'"Whether to include shipping timeline in the response"'}),n(s.span,{style:{color:"#ADBAC7"},children:"),"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"});"})}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:"// Define the output schema"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"const"}),n(s.span,{style:{color:"#6CB6FF"},children:" LookupOrderOutput"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#ADBAC7"},children:" z."}),n(s.span,{style:{color:"#DCBDFB"},children:"object"}),n(s.span,{style:{color:"#ADBAC7"},children:"({"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" found: z."}),n(s.span,{style:{color:"#DCBDFB"},children:"boolean"}),n(s.span,{style:{color:"#ADBAC7"},children:"(),"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" status: z."}),n(s.span,{style:{color:"#DCBDFB"},children:"enum"}),n(s.span,{style:{color:"#ADBAC7"},children:"(["}),n(s.span,{style:{color:"#96D0FF"},children:'"pending"'}),n(s.span,{style:{color:"#ADBAC7"},children:", "}),n(s.span,{style:{color:"#96D0FF"},children:'"shipped"'}),n(s.span,{style:{color:"#ADBAC7"},children:", "}),n(s.span,{style:{color:"#96D0FF"},children:'"delivered"'}),n(s.span,{style:{color:"#ADBAC7"},children:", "}),n(s.span,{style:{color:"#96D0FF"},children:'"cancelled"'}),n(s.span,{style:{color:"#ADBAC7"},children:"])."}),n(s.span,{style:{color:"#DCBDFB"},children:"optional"}),n(s.span,{style:{color:"#ADBAC7"},children:"(),"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" items: z."}),n(s.span,{style:{color:"#DCBDFB"},children:"array"}),n(s.span,{style:{color:"#ADBAC7"},children:"(z."}),n(s.span,{style:{color:"#DCBDFB"},children:"object"}),n(s.span,{style:{color:"#ADBAC7"},children:"({ sku: z."}),n(s.span,{style:{color:"#DCBDFB"},children:"string"}),n(s.span,{style:{color:"#ADBAC7"},children:"(), quantity: z."}),n(s.span,{style:{color:"#DCBDFB"},children:"number"}),n(s.span,{style:{color:"#ADBAC7"},children:"() }))."}),n(s.span,{style:{color:"#DCBDFB"},children:"optional"}),n(s.span,{style:{color:"#ADBAC7"},children:"(),"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" shipping_eta: z."}),n(s.span,{style:{color:"#DCBDFB"},children:"string"}),n(s.span,{style:{color:"#ADBAC7"},children:"()."}),n(s.span,{style:{color:"#DCBDFB"},children:"optional"}),n(s.span,{style:{color:"#ADBAC7"},children:"(),"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"});"})}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"type"}),n(s.span,{style:{color:"#F69D50"},children:" LookupOrderInput"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#F69D50"},children:" z"}),n(s.span,{style:{color:"#ADBAC7"},children:"."}),n(s.span,{style:{color:"#F69D50"},children:"infer"}),n(s.span,{style:{color:"#ADBAC7"},children:"<"}),n(s.span,{style:{color:"#F47067"},children:"typeof"}),n(s.span,{style:{color:"#ADBAC7"},children:" LookupOrderInput>;"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"type"}),n(s.span,{style:{color:"#F69D50"},children:" LookupOrderOutput"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#F69D50"},children:" z"}),n(s.span,{style:{color:"#ADBAC7"},children:"."}),n(s.span,{style:{color:"#F69D50"},children:"infer"}),n(s.span,{style:{color:"#ADBAC7"},children:"<"}),n(s.span,{style:{color:"#F47067"},children:"typeof"}),n(s.span,{style:{color:"#ADBAC7"},children:" LookupOrderOutput>;"})]}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:"// Derive the Anthropic tool definition from the Zod schema"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"const"}),n(s.span,{style:{color:"#6CB6FF"},children:" lookupOrderTool"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" Anthropic"}),n(s.span,{style:{color:"#ADBAC7"},children:"."}),n(s.span,{style:{color:"#F69D50"},children:"Tool"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#ADBAC7"},children:" {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" name: "}),n(s.span,{style:{color:"#96D0FF"},children:'"lookup_order"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" description:"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#96D0FF"},children:' "Look up an order by ID. Call this before discussing order status, refunds, or shipping."'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" input_schema: "}),n(s.span,{style:{color:"#DCBDFB"},children:"zodToJsonSchema"}),n(s.span,{style:{color:"#ADBAC7"},children:"(LookupOrderInput) "}),n(s.span,{style:{color:"#F47067"},children:"as"}),n(s.span,{style:{color:"#F69D50"},children:" Anthropic"}),n(s.span,{style:{color:"#ADBAC7"},children:"."}),n(s.span,{style:{color:"#F69D50"},children:"Tool"}),n(s.span,{style:{color:"#ADBAC7"},children:"["}),n(s.span,{style:{color:"#96D0FF"},children:'"input_schema"'}),n(s.span,{style:{color:"#ADBAC7"},children:"],"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"};"})}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:"// Implement with validated I/O"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"async"}),n(s.span,{style:{color:"#F47067"},children:" function"}),n(s.span,{style:{color:"#DCBDFB"},children:" lookupOrder"}),n(s.span,{style:{color:"#ADBAC7"},children:"("}),n(s.span,{style:{color:"#F69D50"},children:"rawInput"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#6CB6FF"},children:" unknown"}),n(s.span,{style:{color:"#ADBAC7"},children:")"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" Promise"}),n(s.span,{style:{color:"#ADBAC7"},children:"<"}),n(s.span,{style:{color:"#6CB6FF"},children:"string"}),n(s.span,{style:{color:"#ADBAC7"},children:"> {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" const"}),n(s.span,{style:{color:"#6CB6FF"},children:" input"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#ADBAC7"},children:" LookupOrderInput."}),n(s.span,{style:{color:"#DCBDFB"},children:"parse"}),n(s.span,{style:{color:"#ADBAC7"},children:"(rawInput); "}),n(s.span,{style:{color:"#768390"},children:"// throws on bad input"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" const"}),n(s.span,{style:{color:"#6CB6FF"},children:" result"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#F47067"},children:" await"}),n(s.span,{style:{color:"#ADBAC7"},children:" db.orders."}),n(s.span,{style:{color:"#DCBDFB"},children:"findById"}),n(s.span,{style:{color:"#ADBAC7"},children:"(input.order_id);"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" const"}),n(s.span,{style:{color:"#6CB6FF"},children:" output"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#ADBAC7"},children:" LookupOrderOutput."}),n(s.span,{style:{color:"#DCBDFB"},children:"parse"}),n(s.span,{style:{color:"#ADBAC7"},children:"(result); "}),n(s.span,{style:{color:"#768390"},children:"// throws on unexpected output shape"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#6CB6FF"},children:" JSON"}),n(s.span,{style:{color:"#ADBAC7"},children:"."}),n(s.span,{style:{color:"#DCBDFB"},children:"stringify"}),n(s.span,{style:{color:"#ADBAC7"},children:"(output);"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"}"})})]})})}),"\n",n(s.p,{children:"This pattern catches two classes of bugs: bad inputs from Claude (Claude\noccasionally generates tool calls that don't match the schema) and bad outputs\nfrom your data layer (your DB returning unexpected shapes)."}),"\n",n(s.h3,{children:"Tool Description Quality"}),"\n",n(s.p,{children:"Claude uses the tool description — not just the schema — to decide whether and\nwhen to call a tool. Vague descriptions cause missed calls or incorrect calls.\nBe explicit:"}),"\n",n(s.figure,{"data-rehype-pretty-code-figure":"",children:n(s.pre,{tabIndex:"0","data-language":"typescript","data-theme":"github-dark-dimmed",children:l(s.code,{"data-language":"typescript","data-theme":"github-dark-dimmed",style:{display:"grid"},children:[n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:"// Bad — too vague"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:"description"}),n(s.span,{style:{color:"#ADBAC7"},children:": "}),n(s.span,{style:{color:"#96D0FF"},children:'"Get customer information"'})]}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:"// Good — precise about trigger conditions"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:"description"}),n(s.span,{style:{color:"#ADBAC7"},children:": "}),n(s.span,{style:{color:"#96D0FF"},children:'"Fetch account details for a customer by email or account ID'}),n(s.span,{style:{color:"#FF938A",fontStyle:"italic"},children:"."})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:"Call "}),n(s.span,{style:{color:"#6CB6FF"},children:"this"}),n(s.span,{style:{color:"#ADBAC7"},children:" when the user references their account, subscription, billing address,"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:"or payment method. Do "}),n(s.span,{style:{color:"#6CB6FF"},children:"NOT"}),n(s.span,{style:{color:"#ADBAC7"},children:" call "}),n(s.span,{style:{color:"#6CB6FF"},children:"this"}),n(s.span,{style:{color:"#ADBAC7"},children:" for order lookups — use lookup_order instead."}),n(s.span,{style:{color:"#96D0FF"},children:'"'})]})]})})}),"\n",n(s.h3,{children:"Allow-Lists for Dangerous Capabilities"}),"\n",n(s.p,{children:"Any tool with side effects — writes, deletions, external API calls that cost\nmoney — belongs on an explicit allow-list. The agent must hold the capability,\nbut your executor decides whether to act."}),"\n",n(s.figure,{"data-rehype-pretty-code-figure":"",children:n(s.pre,{tabIndex:"0","data-language":"typescript","data-theme":"github-dark-dimmed",children:l(s.code,{"data-language":"typescript","data-theme":"github-dark-dimmed",style:{display:"grid"},children:[l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"type"}),n(s.span,{style:{color:"#F69D50"},children:" ToolPermission"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#96D0FF"},children:' "read"'}),n(s.span,{style:{color:"#F47067"},children:" |"}),n(s.span,{style:{color:"#96D0FF"},children:' "write"'}),n(s.span,{style:{color:"#F47067"},children:" |"}),n(s.span,{style:{color:"#96D0FF"},children:' "dangerous"'}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"const"}),n(s.span,{style:{color:"#6CB6FF"},children:" TOOL_PERMISSIONS"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" Record"}),n(s.span,{style:{color:"#ADBAC7"},children:"<"}),n(s.span,{style:{color:"#6CB6FF"},children:"string"}),n(s.span,{style:{color:"#ADBAC7"},children:", "}),n(s.span,{style:{color:"#F69D50"},children:"ToolPermission"}),n(s.span,{style:{color:"#ADBAC7"},children:"> "}),n(s.span,{style:{color:"#F47067"},children:"="}),n(s.span,{style:{color:"#ADBAC7"},children:" {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" lookup_order: "}),n(s.span,{style:{color:"#96D0FF"},children:'"read"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" lookup_refund_eligibility: "}),n(s.span,{style:{color:"#96D0FF"},children:'"read"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" search_knowledge_base: "}),n(s.span,{style:{color:"#96D0FF"},children:'"read"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" escalate_ticket: "}),n(s.span,{style:{color:"#96D0FF"},children:'"write"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" issue_refund: "}),n(s.span,{style:{color:"#96D0FF"},children:'"dangerous"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" delete_account: "}),n(s.span,{style:{color:"#96D0FF"},children:'"dangerous"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" send_email: "}),n(s.span,{style:{color:"#96D0FF"},children:'"write"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"};"})}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"async"}),n(s.span,{style:{color:"#F47067"},children:" function"}),n(s.span,{style:{color:"#DCBDFB"},children:" dispatchToolCall"}),n(s.span,{style:{color:"#ADBAC7"},children:"("})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" toolName"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#6CB6FF"},children:" string"}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" input"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#6CB6FF"},children:" unknown"}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" context"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" AgentContext"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:")"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" Promise"}),n(s.span,{style:{color:"#ADBAC7"},children:"<"}),n(s.span,{style:{color:"#6CB6FF"},children:"string"}),n(s.span,{style:{color:"#ADBAC7"},children:"> {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" const"}),n(s.span,{style:{color:"#6CB6FF"},children:" permission"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#6CB6FF"},children:" TOOL_PERMISSIONS"}),n(s.span,{style:{color:"#ADBAC7"},children:"[toolName];"})]}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" if"}),n(s.span,{style:{color:"#ADBAC7"},children:" ("}),n(s.span,{style:{color:"#F47067"},children:"!"}),n(s.span,{style:{color:"#ADBAC7"},children:"permission) {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" throw"}),n(s.span,{style:{color:"#F47067"},children:" new"}),n(s.span,{style:{color:"#DCBDFB"},children:" Error"}),n(s.span,{style:{color:"#ADBAC7"},children:"("}),n(s.span,{style:{color:"#96D0FF"},children:"`Unknown tool: ${"}),n(s.span,{style:{color:"#ADBAC7"},children:"toolName"}),n(s.span,{style:{color:"#96D0FF"},children:"}`"}),n(s.span,{style:{color:"#ADBAC7"},children:");"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" }"})}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" if"}),n(s.span,{style:{color:"#ADBAC7"},children:" (permission "}),n(s.span,{style:{color:"#F47067"},children:"==="}),n(s.span,{style:{color:"#96D0FF"},children:' "dangerous"'}),n(s.span,{style:{color:"#F47067"},children:" &&"}),n(s.span,{style:{color:"#F47067"},children:" !"}),n(s.span,{style:{color:"#ADBAC7"},children:"context.operatorApproved) {"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:" // Pause execution, push to HITL queue"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#F47067"},children:" await"}),n(s.span,{style:{color:"#DCBDFB"},children:" requestHITLApproval"}),n(s.span,{style:{color:"#ADBAC7"},children:"(toolName, input, context);"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" }"})}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#F47067"},children:" await"}),n(s.span,{style:{color:"#DCBDFB"},children:" executeToolImpl"}),n(s.span,{style:{color:"#ADBAC7"},children:"(toolName, input);"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"}"})})]})})}),"\n",n(s.h2,{children:"The Agentic Loop"}),"\n",n(s.p,{children:"The core loop is simple: call Claude, check if it wants to use tools, execute\nthem, feed results back. The complexity lives in error handling."}),"\n",n(s.figure,{"data-rehype-pretty-code-figure":"",children:n(s.pre,{tabIndex:"0","data-language":"typescript","data-theme":"github-dark-dimmed",children:l(s.code,{"data-language":"typescript","data-theme":"github-dark-dimmed",style:{display:"grid"},children:[l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"import"}),n(s.span,{style:{color:"#ADBAC7"},children:" Anthropic "}),n(s.span,{style:{color:"#F47067"},children:"from"}),n(s.span,{style:{color:"#96D0FF"},children:' "@anthropic-ai/sdk"'}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"type"}),n(s.span,{style:{color:"#F69D50"},children:" Message"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#F69D50"},children:" Anthropic"}),n(s.span,{style:{color:"#ADBAC7"},children:"."}),n(s.span,{style:{color:"#F69D50"},children:"MessageParam"}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"async"}),n(s.span,{style:{color:"#F47067"},children:" function"}),n(s.span,{style:{color:"#DCBDFB"},children:" runAgentLoop"}),n(s.span,{style:{color:"#ADBAC7"},children:"("})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" client"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" Anthropic"}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" systemPrompt"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#6CB6FF"},children:" string"}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" userMessage"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#6CB6FF"},children:" string"}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" tools"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" Anthropic"}),n(s.span,{style:{color:"#ADBAC7"},children:"."}),n(s.span,{style:{color:"#F69D50"},children:"Tool"}),n(s.span,{style:{color:"#ADBAC7"},children:"[],"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" maxIterations"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#6CB6FF"},children:" 10"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:")"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" Promise"}),n(s.span,{style:{color:"#ADBAC7"},children:"<"}),n(s.span,{style:{color:"#6CB6FF"},children:"string"}),n(s.span,{style:{color:"#ADBAC7"},children:"> {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" const"}),n(s.span,{style:{color:"#6CB6FF"},children:" messages"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" Message"}),n(s.span,{style:{color:"#ADBAC7"},children:"[] "}),n(s.span,{style:{color:"#F47067"},children:"="}),n(s.span,{style:{color:"#ADBAC7"},children:" [{ role: "}),n(s.span,{style:{color:"#96D0FF"},children:'"user"'}),n(s.span,{style:{color:"#ADBAC7"},children:", content: userMessage }];"})]}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" for"}),n(s.span,{style:{color:"#ADBAC7"},children:" ("}),n(s.span,{style:{color:"#F47067"},children:"let"}),n(s.span,{style:{color:"#ADBAC7"},children:" i "}),n(s.span,{style:{color:"#F47067"},children:"="}),n(s.span,{style:{color:"#6CB6FF"},children:" 0"}),n(s.span,{style:{color:"#ADBAC7"},children:"; i "}),n(s.span,{style:{color:"#F47067"},children:"<"}),n(s.span,{style:{color:"#ADBAC7"},children:" maxIterations; i"}),n(s.span,{style:{color:"#F47067"},children:"++"}),n(s.span,{style:{color:"#ADBAC7"},children:") {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" const"}),n(s.span,{style:{color:"#6CB6FF"},children:" response"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#F47067"},children:" await"}),n(s.span,{style:{color:"#ADBAC7"},children:" client.messages."}),n(s.span,{style:{color:"#DCBDFB"},children:"create"}),n(s.span,{style:{color:"#ADBAC7"},children:"({"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" model: "}),n(s.span,{style:{color:"#96D0FF"},children:'"claude-sonnet-4-5"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" max_tokens: "}),n(s.span,{style:{color:"#6CB6FF"},children:"4096"}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" system: systemPrompt,"})}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" tools,"})}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" messages,"})}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" });"})}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" if"}),n(s.span,{style:{color:"#ADBAC7"},children:" (response.stop_reason "}),n(s.span,{style:{color:"#F47067"},children:"==="}),n(s.span,{style:{color:"#96D0FF"},children:' "end_turn"'}),n(s.span,{style:{color:"#ADBAC7"},children:") {"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:" // No tool calls — extract final text"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" const"}),n(s.span,{style:{color:"#6CB6FF"},children:" text"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#ADBAC7"},children:" response.content."}),n(s.span,{style:{color:"#DCBDFB"},children:"find"}),n(s.span,{style:{color:"#ADBAC7"},children:"(("}),n(s.span,{style:{color:"#F69D50"},children:"b"}),n(s.span,{style:{color:"#ADBAC7"},children:") "}),n(s.span,{style:{color:"#F47067"},children:"=>"}),n(s.span,{style:{color:"#ADBAC7"},children:" b.type "}),n(s.span,{style:{color:"#F47067"},children:"==="}),n(s.span,{style:{color:"#96D0FF"},children:' "text"'}),n(s.span,{style:{color:"#ADBAC7"},children:");"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#ADBAC7"},children:" text?.type "}),n(s.span,{style:{color:"#F47067"},children:"==="}),n(s.span,{style:{color:"#96D0FF"},children:' "text"'}),n(s.span,{style:{color:"#F47067"},children:" ?"}),n(s.span,{style:{color:"#ADBAC7"},children:" text.text "}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#96D0FF"},children:' ""'}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" }"})}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" if"}),n(s.span,{style:{color:"#ADBAC7"},children:" (response.stop_reason "}),n(s.span,{style:{color:"#F47067"},children:"==="}),n(s.span,{style:{color:"#96D0FF"},children:' "tool_use"'}),n(s.span,{style:{color:"#ADBAC7"},children:") {"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:" // Collect all tool calls from this turn"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" const"}),n(s.span,{style:{color:"#6CB6FF"},children:" toolResults"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" Anthropic"}),n(s.span,{style:{color:"#ADBAC7"},children:"."}),n(s.span,{style:{color:"#F69D50"},children:"ToolResultBlockParam"}),n(s.span,{style:{color:"#ADBAC7"},children:"[] "}),n(s.span,{style:{color:"#F47067"},children:"="}),n(s.span,{style:{color:"#ADBAC7"},children:" [];"})]}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" for"}),n(s.span,{style:{color:"#ADBAC7"},children:" ("}),n(s.span,{style:{color:"#F47067"},children:"const"}),n(s.span,{style:{color:"#6CB6FF"},children:" block"}),n(s.span,{style:{color:"#F47067"},children:" of"}),n(s.span,{style:{color:"#ADBAC7"},children:" response.content) {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" if"}),n(s.span,{style:{color:"#ADBAC7"},children:" (block.type "}),n(s.span,{style:{color:"#F47067"},children:"!=="}),n(s.span,{style:{color:"#96D0FF"},children:' "tool_use"'}),n(s.span,{style:{color:"#ADBAC7"},children:") "}),n(s.span,{style:{color:"#F47067"},children:"continue"}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" let"}),n(s.span,{style:{color:"#ADBAC7"},children:" resultContent"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#6CB6FF"},children:" string"}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" try"}),n(s.span,{style:{color:"#ADBAC7"},children:" {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" resultContent "}),n(s.span,{style:{color:"#F47067"},children:"="}),n(s.span,{style:{color:"#F47067"},children:" await"}),n(s.span,{style:{color:"#DCBDFB"},children:" dispatchToolCall"}),n(s.span,{style:{color:"#ADBAC7"},children:"(block.name, block.input, {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" operatorApproved: "}),n(s.span,{style:{color:"#6CB6FF"},children:"false"}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" });"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" } "}),n(s.span,{style:{color:"#F47067"},children:"catch"}),n(s.span,{style:{color:"#ADBAC7"},children:" (err) {"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:" // Return the error to Claude — let it recover"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" resultContent "}),n(s.span,{style:{color:"#F47067"},children:"="}),n(s.span,{style:{color:"#6CB6FF"},children:" JSON"}),n(s.span,{style:{color:"#ADBAC7"},children:"."}),n(s.span,{style:{color:"#DCBDFB"},children:"stringify"}),n(s.span,{style:{color:"#ADBAC7"},children:"({"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" error: err "}),n(s.span,{style:{color:"#F47067"},children:"instanceof"}),n(s.span,{style:{color:"#F69D50"},children:" Error"}),n(s.span,{style:{color:"#F47067"},children:" ?"}),n(s.span,{style:{color:"#ADBAC7"},children:" err.message "}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#96D0FF"},children:' "Tool execution failed"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" });"})}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" }"})}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" toolResults."}),n(s.span,{style:{color:"#DCBDFB"},children:"push"}),n(s.span,{style:{color:"#ADBAC7"},children:"({"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" type: "}),n(s.span,{style:{color:"#96D0FF"},children:'"tool_result"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" tool_use_id: block.id,"})}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" content: resultContent,"})}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" });"})}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" }"})}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:" // Append assistant response + all tool results before next iteration"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" messages."}),n(s.span,{style:{color:"#DCBDFB"},children:"push"}),n(s.span,{style:{color:"#ADBAC7"},children:"({ role: "}),n(s.span,{style:{color:"#96D0FF"},children:'"assistant"'}),n(s.span,{style:{color:"#ADBAC7"},children:", content: response.content });"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" messages."}),n(s.span,{style:{color:"#DCBDFB"},children:"push"}),n(s.span,{style:{color:"#ADBAC7"},children:"({ role: "}),n(s.span,{style:{color:"#96D0FF"},children:'"user"'}),n(s.span,{style:{color:"#ADBAC7"},children:", content: toolResults });"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" continue"}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" }"})}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:" // Unexpected stop reason"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" throw"}),n(s.span,{style:{color:"#F47067"},children:" new"}),n(s.span,{style:{color:"#DCBDFB"},children:" Error"}),n(s.span,{style:{color:"#ADBAC7"},children:"("}),n(s.span,{style:{color:"#96D0FF"},children:"`Unexpected stop_reason: ${"}),n(s.span,{style:{color:"#ADBAC7"},children:"response"}),n(s.span,{style:{color:"#96D0FF"},children:"."}),n(s.span,{style:{color:"#ADBAC7"},children:"stop_reason"}),n(s.span,{style:{color:"#96D0FF"},children:"}`"}),n(s.span,{style:{color:"#ADBAC7"},children:");"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" }"})}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" throw"}),n(s.span,{style:{color:"#F47067"},children:" new"}),n(s.span,{style:{color:"#DCBDFB"},children:" Error"}),n(s.span,{style:{color:"#ADBAC7"},children:"("}),n(s.span,{style:{color:"#96D0FF"},children:"`Agent exceeded maxIterations (${"}),n(s.span,{style:{color:"#ADBAC7"},children:"maxIterations"}),n(s.span,{style:{color:"#96D0FF"},children:"})`"}),n(s.span,{style:{color:"#ADBAC7"},children:");"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"}"})})]})})}),"\n",l(s.p,{children:["Two things are worth calling out: feeding errors back to Claude rather than\nthrowing immediately (Claude is often able to recover and try a different tool\ncall), and the ",n(s.code,{children:"maxIterations"})," guard (prevents runaway loops on pathological\ninputs)."]}),"\n",n(s.h2,{children:"Memory Patterns"}),"\n",n(s.p,{children:"Claude has no persistent memory by default. You build it."}),"\n",n(s.h3,{children:"In-Context Memory"}),"\n",n(s.p,{children:"The simplest approach: include relevant history directly in the system prompt\nor messages. Works well for conversation continuity within a session."}),"\n",n(s.figure,{"data-rehype-pretty-code-figure":"",children:n(s.pre,{tabIndex:"0","data-language":"typescript","data-theme":"github-dark-dimmed",children:l(s.code,{"data-language":"typescript","data-theme":"github-dark-dimmed",style:{display:"grid"},children:[l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"function"}),n(s.span,{style:{color:"#DCBDFB"},children:" buildContextWithMemory"}),n(s.span,{style:{color:"#ADBAC7"},children:"("})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" basePrompt"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#6CB6FF"},children:" string"}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" recentHistory"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" ConversationTurn"}),n(s.span,{style:{color:"#ADBAC7"},children:"[],"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" userProfile"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" UserProfile"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:")"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#6CB6FF"},children:" string"}),n(s.span,{style:{color:"#ADBAC7"},children:" {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#96D0FF"},children:" `${"}),n(s.span,{style:{color:"#ADBAC7"},children:"basePrompt"}),n(s.span,{style:{color:"#96D0FF"},children:"}"})]}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#96D0FF"},children:"USER PROFILE:"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#96D0FF"},children:"- Name: ${"}),n(s.span,{style:{color:"#ADBAC7"},children:"userProfile"}),n(s.span,{style:{color:"#96D0FF"},children:"."}),n(s.span,{style:{color:"#ADBAC7"},children:"name"}),n(s.span,{style:{color:"#96D0FF"},children:"}"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#96D0FF"},children:"- Account tier: ${"}),n(s.span,{style:{color:"#ADBAC7"},children:"userProfile"}),n(s.span,{style:{color:"#96D0FF"},children:"."}),n(s.span,{style:{color:"#ADBAC7"},children:"tier"}),n(s.span,{style:{color:"#96D0FF"},children:"}"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#96D0FF"},children:"- Open tickets: ${"}),n(s.span,{style:{color:"#ADBAC7"},children:"userProfile"}),n(s.span,{style:{color:"#96D0FF"},children:"."}),n(s.span,{style:{color:"#ADBAC7"},children:"openTicketCount"}),n(s.span,{style:{color:"#96D0FF"},children:"}"})]}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#96D0FF"},children:"RECENT CONVERSATION HISTORY (last 3 turns):"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#96D0FF"},children:"${"}),n(s.span,{style:{color:"#ADBAC7"},children:"recentHistory"}),n(s.span,{style:{color:"#96D0FF"},children:"."}),n(s.span,{style:{color:"#DCBDFB"},children:"slice"}),n(s.span,{style:{color:"#96D0FF"},children:"("}),n(s.span,{style:{color:"#F47067"},children:"-"}),n(s.span,{style:{color:"#6CB6FF"},children:"3"}),n(s.span,{style:{color:"#96D0FF"},children:")."}),n(s.span,{style:{color:"#DCBDFB"},children:"map"}),n(s.span,{style:{color:"#96D0FF"},children:"(("}),n(s.span,{style:{color:"#6CB6FF"},children:"t"}),n(s.span,{style:{color:"#96D0FF"},children:") "}),n(s.span,{style:{color:"#F47067"},children:"=>"}),n(s.span,{style:{color:"#96D0FF"},children:" `${"}),n(s.span,{style:{color:"#ADBAC7"},children:"t"}),n(s.span,{style:{color:"#96D0FF"},children:"."}),n(s.span,{style:{color:"#ADBAC7"},children:"role"}),n(s.span,{style:{color:"#96D0FF"},children:"}: ${"}),n(s.span,{style:{color:"#ADBAC7"},children:"t"}),n(s.span,{style:{color:"#96D0FF"},children:"."}),n(s.span,{style:{color:"#ADBAC7"},children:"content"}),n(s.span,{style:{color:"#96D0FF"},children:"}`"}),n(s.span,{style:{color:"#96D0FF"},children:")."}),n(s.span,{style:{color:"#DCBDFB"},children:"join"}),n(s.span,{style:{color:"#96D0FF"},children:"("}),n(s.span,{style:{color:"#96D0FF"},children:'"'}),n(s.span,{style:{color:"#F47067"},children:"\\n"}),n(s.span,{style:{color:"#96D0FF"},children:'"'}),n(s.span,{style:{color:"#96D0FF"},children:")"}),n(s.span,{style:{color:"#96D0FF"},children:"}`"}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"}"})})]})})}),"\n",n(s.h3,{children:"External Memory with Semantic Search"}),"\n",n(s.p,{children:"For anything beyond a single session, you need external memory. The standard\npattern: embed every significant turn, store in a vector DB, retrieve at\nconversation start."}),"\n",n(s.pre,{children:n(s.code,{children:"New conversation begins\n → Embed the opening message\n → Retrieve top-3 semantically similar past conversations\n → Inject summaries into system prompt\n → Agent has relevant context without a bloated context window\n"})}),"\n",n(s.h3,{children:"Structured State"}),"\n",n(s.p,{children:"For agents that need to track workflow state across multiple turns — approval\nworkflows, multi-step onboarding, background research tasks — keep state in a\ntyped object and pass it explicitly."}),"\n",n(s.figure,{"data-rehype-pretty-code-figure":"",children:n(s.pre,{tabIndex:"0","data-language":"typescript","data-theme":"github-dark-dimmed",children:l(s.code,{"data-language":"typescript","data-theme":"github-dark-dimmed",style:{display:"grid"},children:[l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"type"}),n(s.span,{style:{color:"#F69D50"},children:" AgentState"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#ADBAC7"},children:" {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" phase"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#96D0FF"},children:' "triage"'}),n(s.span,{style:{color:"#F47067"},children:" |"}),n(s.span,{style:{color:"#96D0FF"},children:' "investigating"'}),n(s.span,{style:{color:"#F47067"},children:" |"}),n(s.span,{style:{color:"#96D0FF"},children:' "proposing_solution"'}),n(s.span,{style:{color:"#F47067"},children:" |"}),n(s.span,{style:{color:"#96D0FF"},children:' "resolved"'}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" confirmedFacts"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#6CB6FF"},children:" string"}),n(s.span,{style:{color:"#ADBAC7"},children:"[];"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" pendingActions"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#6CB6FF"},children:" string"}),n(s.span,{style:{color:"#ADBAC7"},children:"[];"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" ticketId"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#6CB6FF"},children:" string"}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"};"})})]})})}),"\n",n(s.p,{children:"Never store state in the system prompt by mutation. Keep it in your application\nlayer and inject the current snapshot on each turn."}),"\n",n(s.h2,{children:"Choosing the Right Model for Each Role"}),"\n",n(s.p,{children:"One of the easiest performance wins in a multi-agent system is model selection.\nClaude Haiku is 10-20x cheaper than Sonnet and significantly faster. If a step\ndoesn't require deep reasoning, Haiku is the right choice."}),"\n",n(s.p,{children:"The heuristic: use Haiku for classification, routing, and structured output\ngeneration; use Sonnet for reasoning-heavy tasks — complex tool orchestration,\nnuanced writing, and decisions that involve weighing competing factors."}),"\n",l(s.table,{children:[n(s.thead,{children:l(s.tr,{children:[n(s.th,{children:"Role"}),n(s.th,{children:"Model"}),n(s.th,{children:"Why"})]})}),l(s.tbody,{children:[l(s.tr,{children:[n(s.td,{children:"Input guardrail (SAFE/UNSAFE)"}),n(s.td,{children:"Haiku"}),n(s.td,{children:"Binary classification, no reasoning needed"})]}),l(s.tr,{children:[n(s.td,{children:"Triage (intent, urgency)"}),n(s.td,{children:"Haiku"}),n(s.td,{children:"Structured JSON, pattern matching"})]}),l(s.tr,{children:[n(s.td,{children:"Knowledge retrieval (no LLM needed)"}),n(s.td,{children:"—"}),n(s.td,{children:"Use an embedding model directly"})]}),l(s.tr,{children:[n(s.td,{children:"Main agent (reasoning + tools)"}),n(s.td,{children:"Sonnet"}),n(s.td,{children:"Multi-step reasoning, tool chaining"})]}),l(s.tr,{children:[n(s.td,{children:"HITL confidence scoring"}),n(s.td,{children:"Haiku"}),n(s.td,{children:"Quick yes/no assessment"})]}),l(s.tr,{children:[n(s.td,{children:"Final output guardrail"}),n(s.td,{children:"Haiku"}),n(s.td,{children:"Pattern matching on outbound text"})]})]})]}),"\n",n(s.p,{children:"In a high-volume production system, this split can cut inference costs by 60-80%\ncompared with routing everything through Sonnet."}),"\n",n(s.figure,{"data-rehype-pretty-code-figure":"",children:n(s.pre,{tabIndex:"0","data-language":"typescript","data-theme":"github-dark-dimmed",children:l(s.code,{"data-language":"typescript","data-theme":"github-dark-dimmed",style:{display:"grid"},children:[l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"const"}),n(s.span,{style:{color:"#6CB6FF"},children:" MODEL_SELECTION"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#ADBAC7"},children:" {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" triage: "}),n(s.span,{style:{color:"#96D0FF"},children:'"claude-haiku-4-5"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" guardrail: "}),n(s.span,{style:{color:"#96D0FF"},children:'"claude-haiku-4-5"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" mainAgent: "}),n(s.span,{style:{color:"#96D0FF"},children:'"claude-sonnet-4-5"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" confidenceCheck: "}),n(s.span,{style:{color:"#96D0FF"},children:'"claude-haiku-4-5"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:"} "}),n(s.span,{style:{color:"#F47067"},children:"as"}),n(s.span,{style:{color:"#F47067"},children:" const"}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]})]})})}),"\n",n(s.h2,{children:"Guardrails"}),"\n",n(s.p,{children:"Guardrails are the safety layer between user inputs and the agent's full\ncapabilities. Implement three layers:"}),"\n",l(s.p,{children:[n(s.strong,{children:"Input guardrails"})," — before Claude sees the message:"]}),"\n",l(s.ul,{children:["\n",n(s.li,{children:"PII redaction (regex + NER model for high-stakes use cases)"}),"\n",n(s.li,{children:"Prompt injection detection (classifier or lightweight LLM screen)"}),"\n",n(s.li,{children:"Rate limiting per user"}),"\n"]}),"\n",l(s.p,{children:[n(s.strong,{children:"Output guardrails"})," — after Claude generates a response:"]}),"\n",l(s.ul,{children:["\n",n(s.li,{children:"Block specific patterns (competitor mentions, discouraged phrases)"}),"\n",n(s.li,{children:"PII scan on outbound (catch any PII Claude might inadvertently include)"}),"\n",n(s.li,{children:"Confidence scoring (route low-confidence replies to HITL)"}),"\n"]}),"\n",l(s.p,{children:[n(s.strong,{children:"Tool guardrails"})," — before tool execution:"]}),"\n",l(s.ul,{children:["\n",n(s.li,{children:"Schema validation (Zod, always)"}),"\n",n(s.li,{children:"Allow-list check for dangerous tools"}),"\n",n(s.li,{children:"Dry-run mode for testing"}),"\n"]}),"\n",n(s.figure,{"data-rehype-pretty-code-figure":"",children:n(s.pre,{tabIndex:"0","data-language":"typescript","data-theme":"github-dark-dimmed",children:l(s.code,{"data-language":"typescript","data-theme":"github-dark-dimmed",style:{display:"grid"},children:[l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"async"}),n(s.span,{style:{color:"#F47067"},children:" function"}),n(s.span,{style:{color:"#DCBDFB"},children:" outputGuardrail"}),n(s.span,{style:{color:"#ADBAC7"},children:"("}),n(s.span,{style:{color:"#F69D50"},children:"reply"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#6CB6FF"},children:" string"}),n(s.span,{style:{color:"#ADBAC7"},children:")"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" Promise"}),n(s.span,{style:{color:"#ADBAC7"},children:"<"}),n(s.span,{style:{color:"#6CB6FF"},children:"string"}),n(s.span,{style:{color:"#ADBAC7"},children:"> {"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:" // Strip any PII that slipped through"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" const"}),n(s.span,{style:{color:"#ADBAC7"},children:" { "}),n(s.span,{style:{color:"#6CB6FF"},children:"clean"}),n(s.span,{style:{color:"#ADBAC7"},children:" } "}),n(s.span,{style:{color:"#F47067"},children:"="}),n(s.span,{style:{color:"#DCBDFB"},children:" redactPII"}),n(s.span,{style:{color:"#ADBAC7"},children:"(reply);"})]}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:" // Competitor filter (build your own list)"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" const"}),n(s.span,{style:{color:"#6CB6FF"},children:" blocked"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#6CB6FF"},children:" COMPETITOR_NAMES"}),n(s.span,{style:{color:"#ADBAC7"},children:"."}),n(s.span,{style:{color:"#DCBDFB"},children:"some"}),n(s.span,{style:{color:"#ADBAC7"},children:"(("}),n(s.span,{style:{color:"#F69D50"},children:"name"}),n(s.span,{style:{color:"#ADBAC7"},children:") "}),n(s.span,{style:{color:"#F47067"},children:"=>"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" clean."}),n(s.span,{style:{color:"#DCBDFB"},children:"toLowerCase"}),n(s.span,{style:{color:"#ADBAC7"},children:"()."}),n(s.span,{style:{color:"#DCBDFB"},children:"includes"}),n(s.span,{style:{color:"#ADBAC7"},children:"(name."}),n(s.span,{style:{color:"#DCBDFB"},children:"toLowerCase"}),n(s.span,{style:{color:"#ADBAC7"},children:"())"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" );"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" if"}),n(s.span,{style:{color:"#ADBAC7"},children:" (blocked) {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#96D0FF"},children:' "I\'m not able to discuss other products. Can I help you with something specific about your account?"'}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" }"})}),"\n",n(s.span,{"data-line":"",children:" "}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#ADBAC7"},children:" clean;"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"}"})})]})})}),"\n",n(s.h2,{children:"Orchestrator / Subagent Patterns"}),"\n",n(s.p,{children:"When you do need multiple agents, there are three topologies in production:"}),"\n",n(s.h3,{children:"Hierarchical (Supervisor → Workers)"}),"\n",n(s.p,{children:"One orchestrator agent breaks down the task and dispatches to specialist\nworkers. The orchestrator never does domain work itself — it coordinates."}),"\n",n(s.pre,{children:n(s.code,{children:"Orchestrator\n ├─ ResearchAgent (web search, summarisation)\n ├─ WritingAgent (draft generation)\n └─ ReviewAgent (fact check, style check)\n"})}),"\n",n(s.p,{children:"Best for: pipelines where subtasks are sequential and the orchestrator needs\nto make decisions based on each worker's output before dispatching the next."}),"\n",n(s.h3,{children:"Parallel Workers (Fan-out / Fan-in)"}),"\n",n(s.p,{children:"The orchestrator spawns multiple independent workers simultaneously, waits for\nall results, then synthesizes."}),"\n",n(s.figure,{"data-rehype-pretty-code-figure":"",children:n(s.pre,{tabIndex:"0","data-language":"typescript","data-theme":"github-dark-dimmed",children:l(s.code,{"data-language":"typescript","data-theme":"github-dark-dimmed",style:{display:"grid"},children:[l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"async"}),n(s.span,{style:{color:"#F47067"},children:" function"}),n(s.span,{style:{color:"#DCBDFB"},children:" runParallelAgents"}),n(s.span,{style:{color:"#ADBAC7"},children:"("})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" client"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" Anthropic"}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" tasks"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" AgentTask"}),n(s.span,{style:{color:"#ADBAC7"},children:"[]"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:")"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" Promise"}),n(s.span,{style:{color:"#ADBAC7"},children:"<"}),n(s.span,{style:{color:"#F69D50"},children:"AgentResult"}),n(s.span,{style:{color:"#ADBAC7"},children:"[]> {"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:" // All tasks run concurrently"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#6CB6FF"},children:" Promise"}),n(s.span,{style:{color:"#ADBAC7"},children:"."}),n(s.span,{style:{color:"#DCBDFB"},children:"all"}),n(s.span,{style:{color:"#ADBAC7"},children:"("})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" tasks."}),n(s.span,{style:{color:"#DCBDFB"},children:"map"}),n(s.span,{style:{color:"#ADBAC7"},children:"(("}),n(s.span,{style:{color:"#F69D50"},children:"task"}),n(s.span,{style:{color:"#ADBAC7"},children:") "}),n(s.span,{style:{color:"#F47067"},children:"=>"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#DCBDFB"},children:" runAgentLoop"}),n(s.span,{style:{color:"#ADBAC7"},children:"(client, task.systemPrompt, task.userMessage, task.tools)"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" )"})}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" );"})}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"}"})})]})})}),"\n",n(s.p,{children:"Best for: research tasks, code review from multiple perspectives, processing\nbatches of independent items."}),"\n",n(s.h3,{children:"Specialist Routing"}),"\n",n(s.p,{children:"The orchestrator doesn't coordinate — it routes. Each incoming request goes\nto exactly one specialist agent based on intent."}),"\n",n(s.figure,{"data-rehype-pretty-code-figure":"",children:n(s.pre,{tabIndex:"0","data-language":"typescript","data-theme":"github-dark-dimmed",children:l(s.code,{"data-language":"typescript","data-theme":"github-dark-dimmed",style:{display:"grid"},children:[l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"function"}),n(s.span,{style:{color:"#DCBDFB"},children:" routeToAgent"}),n(s.span,{style:{color:"#ADBAC7"},children:"("}),n(s.span,{style:{color:"#F69D50"},children:"triage"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" TriageResult"}),n(s.span,{style:{color:"#ADBAC7"},children:")"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" AgentConfig"}),n(s.span,{style:{color:"#ADBAC7"},children:" {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" switch"}),n(s.span,{style:{color:"#ADBAC7"},children:" (triage.intent) {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" case"}),n(s.span,{style:{color:"#96D0FF"},children:' "billing"'}),n(s.span,{style:{color:"#ADBAC7"},children:":"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#6CB6FF"},children:" BILLING_AGENT_CONFIG"}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" case"}),n(s.span,{style:{color:"#96D0FF"},children:' "technical"'}),n(s.span,{style:{color:"#ADBAC7"},children:":"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#6CB6FF"},children:" TECHNICAL_AGENT_CONFIG"}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" case"}),n(s.span,{style:{color:"#96D0FF"},children:' "account"'}),n(s.span,{style:{color:"#ADBAC7"},children:":"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#6CB6FF"},children:" ACCOUNT_AGENT_CONFIG"}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" default"}),n(s.span,{style:{color:"#ADBAC7"},children:":"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#6CB6FF"},children:" GENERAL_AGENT_CONFIG"}),n(s.span,{style:{color:"#ADBAC7"},children:";"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" }"})}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"}"})})]})})}),"\n",n(s.p,{children:"Best for: support agents, where different intents need genuinely different\ntools and system prompts, and you don't want one bloated generalist agent."}),"\n",n(s.h2,{children:"Error Handling and Retries"}),"\n",n(s.p,{children:"Production agents encounter errors constantly — tool calls fail, APIs time out,\nClaude generates tool inputs that don't match the schema. Your error handling\nstrategy determines whether these become user-visible failures or invisible\nrecoveries."}),"\n",n(s.p,{children:n(s.strong,{children:"The three-tier error strategy:"})}),"\n",l(s.p,{children:[n(s.strong,{children:"Tier 1: Feed errors back to Claude."})," Most tool errors should be returned as\ntool results, not thrown as exceptions. Claude is often able to reason about\nthe error and try a different approach."]}),"\n",n(s.figure,{"data-rehype-pretty-code-figure":"",children:n(s.pre,{tabIndex:"0","data-language":"typescript","data-theme":"github-dark-dimmed",children:l(s.code,{"data-language":"typescript","data-theme":"github-dark-dimmed",style:{display:"grid"},children:[l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"try"}),n(s.span,{style:{color:"#ADBAC7"},children:" {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" const"}),n(s.span,{style:{color:"#6CB6FF"},children:" result"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#F47067"},children:" await"}),n(s.span,{style:{color:"#DCBDFB"},children:" executeToolImpl"}),n(s.span,{style:{color:"#ADBAC7"},children:"(toolName, input);"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#ADBAC7"},children:" result;"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:"} "}),n(s.span,{style:{color:"#F47067"},children:"catch"}),n(s.span,{style:{color:"#ADBAC7"},children:" (err) {"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#768390"},children:" // Return error as a tool result — let Claude recover"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#6CB6FF"},children:" JSON"}),n(s.span,{style:{color:"#ADBAC7"},children:"."}),n(s.span,{style:{color:"#DCBDFB"},children:"stringify"}),n(s.span,{style:{color:"#ADBAC7"},children:"({"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" error: "}),n(s.span,{style:{color:"#6CB6FF"},children:"true"}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" message: err "}),n(s.span,{style:{color:"#F47067"},children:"instanceof"}),n(s.span,{style:{color:"#F69D50"},children:" Error"}),n(s.span,{style:{color:"#F47067"},children:" ?"}),n(s.span,{style:{color:"#ADBAC7"},children:" err.message "}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#96D0FF"},children:' "Unknown error"'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" suggestion: "}),n(s.span,{style:{color:"#96D0FF"},children:'"Try with different parameters, or use escalate_ticket if this persists."'}),n(s.span,{style:{color:"#ADBAC7"},children:","})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" });"})}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"}"})})]})})}),"\n",l(s.p,{children:[n(s.strong,{children:"Tier 2: Retry with exponential backoff."})," For transient infrastructure\nfailures (rate limits, network timeouts), retry before giving up. But retry\nthe tool call, not the entire agent — preserve the conversation context."]}),"\n",n(s.figure,{"data-rehype-pretty-code-figure":"",children:n(s.pre,{tabIndex:"0","data-language":"typescript","data-theme":"github-dark-dimmed",children:l(s.code,{"data-language":"typescript","data-theme":"github-dark-dimmed",style:{display:"grid"},children:[l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:"async"}),n(s.span,{style:{color:"#F47067"},children:" function"}),n(s.span,{style:{color:"#DCBDFB"},children:" executeWithRetry"}),n(s.span,{style:{color:"#ADBAC7"},children:"("})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#DCBDFB"},children:" fn"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#ADBAC7"},children:" () "}),n(s.span,{style:{color:"#F47067"},children:"=>"}),n(s.span,{style:{color:"#F69D50"},children:" Promise"}),n(s.span,{style:{color:"#ADBAC7"},children:"<"}),n(s.span,{style:{color:"#6CB6FF"},children:"string"}),n(s.span,{style:{color:"#ADBAC7"},children:">,"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F69D50"},children:" maxAttempts"}),n(s.span,{style:{color:"#F47067"},children:" ="}),n(s.span,{style:{color:"#6CB6FF"},children:" 3"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:")"}),n(s.span,{style:{color:"#F47067"},children:":"}),n(s.span,{style:{color:"#F69D50"},children:" Promise"}),n(s.span,{style:{color:"#ADBAC7"},children:"<"}),n(s.span,{style:{color:"#6CB6FF"},children:"string"}),n(s.span,{style:{color:"#ADBAC7"},children:"> {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" for"}),n(s.span,{style:{color:"#ADBAC7"},children:" ("}),n(s.span,{style:{color:"#F47067"},children:"let"}),n(s.span,{style:{color:"#ADBAC7"},children:" attempt "}),n(s.span,{style:{color:"#F47067"},children:"="}),n(s.span,{style:{color:"#6CB6FF"},children:" 1"}),n(s.span,{style:{color:"#ADBAC7"},children:"; attempt "}),n(s.span,{style:{color:"#F47067"},children:"<="}),n(s.span,{style:{color:"#ADBAC7"},children:" maxAttempts; attempt"}),n(s.span,{style:{color:"#F47067"},children:"++"}),n(s.span,{style:{color:"#ADBAC7"},children:") {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" try"}),n(s.span,{style:{color:"#ADBAC7"},children:" {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" return"}),n(s.span,{style:{color:"#F47067"},children:" await"}),n(s.span,{style:{color:"#DCBDFB"},children:" fn"}),n(s.span,{style:{color:"#ADBAC7"},children:"();"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#ADBAC7"},children:" } "}),n(s.span,{style:{color:"#F47067"},children:"catch"}),n(s.span,{style:{color:"#ADBAC7"},children:" (err) {"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" if"}),n(s.span,{style:{color:"#ADBAC7"},children:" (attempt "}),n(s.span,{style:{color:"#F47067"},children:"==="}),n(s.span,{style:{color:"#ADBAC7"},children:" maxAttempts) "}),n(s.span,{style:{color:"#F47067"},children:"throw"}),n(s.span,{style:{color:"#ADBAC7"},children:" err;"})]}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" await"}),n(s.span,{style:{color:"#F47067"},children:" new"}),n(s.span,{style:{color:"#6CB6FF"},children:" Promise"}),n(s.span,{style:{color:"#ADBAC7"},children:"(("}),n(s.span,{style:{color:"#F69D50"},children:"r"}),n(s.span,{style:{color:"#ADBAC7"},children:") "}),n(s.span,{style:{color:"#F47067"},children:"=>"}),n(s.span,{style:{color:"#DCBDFB"},children:" setTimeout"}),n(s.span,{style:{color:"#ADBAC7"},children:"(r, Math."}),n(s.span,{style:{color:"#DCBDFB"},children:"pow"}),n(s.span,{style:{color:"#ADBAC7"},children:"("}),n(s.span,{style:{color:"#6CB6FF"},children:"2"}),n(s.span,{style:{color:"#ADBAC7"},children:", attempt) "}),n(s.span,{style:{color:"#F47067"},children:"*"}),n(s.span,{style:{color:"#6CB6FF"},children:" 200"}),n(s.span,{style:{color:"#ADBAC7"},children:"));"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" }"})}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:" }"})}),"\n",l(s.span,{"data-line":"",children:[n(s.span,{style:{color:"#F47067"},children:" throw"}),n(s.span,{style:{color:"#F47067"},children:" new"}),n(s.span,{style:{color:"#DCBDFB"},children:" Error"}),n(s.span,{style:{color:"#ADBAC7"},children:"("}),n(s.span,{style:{color:"#96D0FF"},children:'"Unreachable"'}),n(s.span,{style:{color:"#ADBAC7"},children:");"})]}),"\n",n(s.span,{"data-line":"",children:n(s.span,{style:{color:"#ADBAC7"},children:"}"})})]})})}),"\n",l(s.p,{children:[n(s.strong,{children:"Tier 3: Hard failure with graceful degradation."})," Some errors should\nterminate the agent turn and route to a human — Claude API unavailable,\ndatabase connection failed, tool returning data that fails schema validation\nafter retries. Design your fallback path before you need it."]}),"\n",n(s.h2,{children:"When to Add a HITL Checkpoint"}),"\n",n(s.p,{children:"Human-in-the-loop checkpoints are explicit pause points in the agentic loop.\nAdd one when:"}),"\n",l(s.ul,{children:["\n",l(s.li,{children:[n(s.strong,{children:"Irreversibility"})," — the action cannot be undone (deletion, financial transaction, email send)"]}),"\n",l(s.li,{children:[n(s.strong,{children:"Low confidence"})," — the agent's reasoning includes explicit uncertainty"]}),"\n",l(s.li,{children:[n(s.strong,{children:"Policy boundary"})," — the action exceeds a defined threshold (refund > $500, etc.)"]}),"\n",l(s.li,{children:[n(s.strong,{children:"Anomaly"})," — the request pattern is unusual for this user"]}),"\n"]}),"\n",n(s.p,{children:"The key design principle: HITL is not a fallback. It is a first-class\narchitectural component. Design your agent to route to it proactively, not\nonly when it fails."}),"\n",n(s.hr,{}),"\n",l(s.p,{children:["These patterns are implemented end-to-end in two production kits. The ",n(s.strong,{children:n(s.a,{href:"/kits/support-agent-workbench",children:"Support Agent Workbench"})})," ($129) is a reference implementation of every pattern in this article — triage, typed tools, guardrails, HITL console, and 42 evals. The ",n(s.strong,{children:n(s.a,{href:"/kits/agent-ready-saas-starter",children:"Agent-Ready SaaS Starter"})})," ($129) wires the full agent layer into a Next.js SaaS skeleton from day one, so you build your product on a solid agentic foundation rather than bolting it on later."]})]})}return{default:function(e={}){const{wrapper:l}=e.components||{};return l?n(l,{...e,children:n(_createMdxContent,{...e})}):_createMdxContent(e)}};