2026-09-28 → 2026-10-04

Agents & Workflows

Choose between a single call, a workflow and an agent for any scenario; name the five patterns; build a guarded agent with the Agent SDK.

https://www.anthropic.com/engineering/building-effective-agents

https://github.com/anthropics/anthropic-cookbook/tree/main/patterns/agents

https://docs.claude.com/en/api/agent-sdk/overview

https://docs.claude.com/en/api/agent-sdk/python

https://docs.claude.com/en/api/agent-sdk/subagents

https://docs.claude.com/en/api/agent-sdk/sessions

https://www.anthropic.com/engineering/multi-agent-research-system

https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool

https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-fetch-tool

https://docs.claude.com/en/docs/agents-and-tools/tool-use/code-execution-tool

https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview

https://www.anthropic.com/engineering/building-effective-agents

https://www.anthropic.com/engineering/writing-tools-for-agents

Workflow: LLM calls orchestrated by code along predefined paths. Predictable, testable, cheap, easy to debug. Prefer this whenever the steps are known.

Agent: the model decides the path — choosing tools in a loop, observing results, until done. Use only when the task genuinely needs open-ended decisions and the number of steps is unknown. Costs more, harder to test, needs guardrails.

Rule: find the simplest solution possible; increase complexity only when it demonstrably improves outcomes. Many "agent" requests are really a single well-crafted prompt.

A → gate → B → C · task decomposes into fixed steps; add programmatic checks between steps · more latency; each step must be verifiable

classify → specialised prompt/model · distinct input categories handled differently (support tiers, cheap vs expensive model) · misroutes; keep the classifier cheap and evaluated

sectioning (split work) or voting (same task N times) · independent subtasks; need multiple perspectives or confidence · cost × N; aggregation logic

lead model plans sub-tasks dynamically, delegates, merges · sub-tasks not predictable in advance (multi-file code change, research) · token cost; workers need clear briefs and return summaries

generator ↔ critic loop · clear evaluation criteria and iteration measurably helps (translation, code with tests) · infinite loops — cap iterations

Receive task → (model reasons → picks tool → your code runs it → result appended) × N → model signals done. Ground truth comes from tool results, so tool result quality drives agent quality.

Always give the agent: a clear goal and stopping condition, a small well-described tool set, max turns, a budget, and checkpoints for human approval before side effects.

Failure modes and guards: loops → loop detection + max turns; runaway cost → token/USD budget; hallucinated tools/args → strict schemas, is_error feedback; lost context → compaction, memory/scratchpad files, subagents; destructive actions → permission callbacks/hooks, dry-run tools.

The framework behind Claude Code, exposed as a library (Python and TypeScript). You describe the task; it runs the loop with built-in tools (file read/edit, bash, grep, web), permission handling, automatic context compaction, CLAUDE.md/project context, MCP servers, subagents, hooks and session persistence.

Key knobs: allowed_tools / disallowed tools, permission_mode, max_turns, system prompt, MCP config, custom tools (in-process MCP), subagent definitions.

Use it when you want an agent that acts on files/systems; use the raw Messages API when you want tight control or a simple workflow.

A subagent runs in its own context window with its own system prompt and tool set and returns a result to the parent. Benefits: isolation, parallelism, specialised roles. Cost: extra tokens; the parent only sees a summary — brief it well.

Short-term memory = the context window; long-term = files, a memory tool, a database, or a retrieval store the agent reads and writes.

Server tools (web search, web fetch, code execution, computer use, text editor, bash) execute on Anthropic's infrastructure; you add them to tools and get results and citations back without running anything.

Skills: folders of instructions (SKILL.md) plus scripts/resources that Claude loads progressively when the task matches — knowledge and procedures, not actions. Tools do things; Skills teach how.

import asyncio

from claude_agent_sdk import query, ClaudeAgentOptions

async def main():

opts = ClaudeAgentOptions(

allowed_tools=["Read","Grep","Glob"], # read-only

max_turns=10,

system_prompt="You are a code reviewer. Report, don't edit.")

async for msg in query(prompt="Find error handling gaps in src/", options=opts):

print(msg)

asyncio.run(main())

https://www.anthropic.com/engineering/building-effective-agents

Workflows = LLMs and tools orchestrated through predefined code paths. Agents = LLMs dynamically direct their own process and tool use.

Building block: the augmented LLM (LLM + retrieval + tools + memory); MCP is one way to wire in tools.

Five workflow patterns: prompt chaining (sequential steps with programmatic gates; trades latency for accuracy); routing (classify → specialised prompt/model); parallelisation — sectioning (independent subtasks) and voting (same task several times); orchestrator–workers (central LLM dynamically decomposes and delegates; for unpredictable subtasks); evaluator–optimizer (generator + feedback loop; needs clear evaluation criteria).

Autonomous agent: LLM in a loop using tools on environmental feedback ('ground truth' each step), pausing for human checkpoints; stops on completion or a stopping condition (e.g. max iterations).

Start with the simplest solution; add agentic complexity only when it demonstrably improves outcomes — agents bring higher cost and compounding errors.

Three principles: simplicity, transparency (show planning), a well-crafted agent–computer interface (thorough tool docs, tested).

Tool-design appendix: formats close to natural text; avoid formatting overhead; docstring-quality descriptions; poka-yoke arguments (e.g. require absolute paths).

https://code.claude.com/docs/en/agent-sdk/overview

Agent SDK = Claude Code as a library: same tools, agent loop and context management, in Python and TypeScript only. Other languages: run the CLI with -p and --output-format json.

Positioning: Agent SDK (runs the loop in your process) vs Claude Code CLI (interactive) vs Client SDK (raw API — you write the tool loop) vs Managed Agents (hosted; Anthropic runs the sandbox).

Capabilities: built-in tools (read/write/edit files, run commands, web search), hooks, subagents, MCP, permissions, sessions (resume/fork), skills/commands/memory from .claude/ and ~/.claude/, plugins.

Install: pip install claude-agent-sdk / npm install @anthropic-ai/claude-agent-sdk; Python 3.10+ / Node 18+; bundles the Claude Code binary.

Auth: ANTHROPIC_API_KEY in the process environment (the SDK does not load .env); CLAUDE_CODE_USE_BEDROCK / VERTEX / FOUNDRY for cloud platforms.

Branding: 'Powered by Claude' allowed; 'Claude Code' branding not permitted for third-party products.

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(

prompt="Review utils.py for bugs and report them.",

options=ClaudeAgentOptions(allowed_tools=["Read","Grep","Glob"], max_turns=10)):

if hasattr(message, "result"): print(message.result)

https://code.claude.com/docs/en/agent-sdk/python

query() = new session per call, single exchange, no interrupts. ClaudeSDKClient = persistent multi-turn session with interrupt(); use async with.

ClaudeAgentOptions: allowed_tools=[], disallowed_tools, permission_mode (default | acceptEdits | plan | dontAsk | bypassPermissions | auto), system_prompt, mcp_servers={}, max_turns, max_budget_usd, cwd, setting_sources (None = user+project+local; [] = none), continue_conversation, resume, fork_session, model, output_format (json_schema), hooks.

allowed_tools AUTO-APPROVES the listed tools — it does not restrict Claude to them; use disallowed_tools to remove tools.

can_use_tool callback fires only when permission evaluation falls through to a prompt; to intercept every call use a PreToolUse hook.

Custom in-process tools: @tool(name, description, input_schema) + create_sdk_mcp_server(name, tools=[…]) passed via mcp_servers.

Message types: AssistantMessage, UserMessage, ResultMessage (subtype, session_id, total_cost_usd), SystemMessage, StreamEvent; blocks TextBlock/ThinkingBlock/ToolUseBlock/ToolResultBlock.

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, ResultMessage

opts = ClaudeAgentOptions(permission_mode="acceptEdits", max_turns=5, max_budget_usd=1.0)

async with ClaudeSDKClient(options=opts) as client:

await client.query("Add input validation to api/handlers.py")

async for m in client.receive_response():

if isinstance(m, ResultMessage): print(m.subtype, m.total_cost_usd)

https://code.claude.com/docs/en/agent-sdk/subagents

Define via the agents={…} option (recommended), .claude/agents/*.md files, or the built-in general-purpose agent. Programmatic definitions override same-named files.

Context isolation: a subagent starts fresh — its own prompt, project CLAUDE.md and tool definitions; NOT the parent's history or system prompt. Only the final message returns to the parent (marked with parent_tool_use_id).

Subagents run in the background by default and can nest: default max depth 3 (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH), max concurrent 20.

Completed subagents can be resumed by agentId with the same definitions; built-in Explore/Plan are one-shot.

from claude_agent_sdk import AgentDefinition

opts = ClaudeAgentOptions(

allowed_tools=["Read","Grep","Glob","Agent"],

agents={"reviewer": AgentDefinition(

description="Strict code reviewer. Use after any change under src/.",

prompt="Review for error handling and security. Report file:line. Never edit.",

tools=["Read","Grep","Glob"], model="sonnet")})

https://code.claude.com/docs/en/agent-sdk/sessions

A session = conversation history persisted to disk automatically; it persists the conversation, not the filesystem (use file checkpointing for that).

continue_conversation=True → most recent session in the cwd, no ID. resume=<id> → a specific session. resume + fork_session=True → new session ID with a copy of history; the original is unchanged.

Storage: ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl; CLAUDE_CONFIG_DIR overrides. Cross-host resume needs a session store adapter or moving the file.

Resume after error_max_turns / error_max_budget_usd with higher limits. Helpers: list_sessions(), get_session_messages(), rename_session(), tag_session().

async for m in query(prompt="Now outline OAuth2 instead",

options=ClaudeAgentOptions(resume=session_id, fork_session=True)):

if isinstance(m, ResultMessage): forked_id = m.session_id

https://www.anthropic.com/engineering/writing-tools-for-agents

Workflow: prototype → wrap in a local MCP server → realistic multi-step evals → agentic loop evals → read transcripts → let Claude analyse transcripts and rewrite tool descriptions.

More tools don't mean better outcomes: consolidate multi-step flows (schedule_event instead of list_users + list_events + create_event); prefer search over list.

Namespace names by service/resource (asana_projects_search). Return semantic context (names over UUIDs); offer a response_format enum (detailed / concise) — concise cut ~⅔ of tokens in the example.

Token efficiency: pagination, filtering, truncation with sensible defaults; actionable error messages instead of opaque codes.

Descriptions are prompt engineering: state query formats, terminology, relationships; unambiguous parameter names (user_id, not user).

https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool

Tool name web_search; type web_search_20250305 (newer types add dynamic filtering and response_inclusion). Must be enabled by an org admin in the Console, else 400.

Params: max_uses; allowed_domains / blocked_domains — mutually exclusive (400 if both); user_location {type:'approximate', city, region, country, timezone}.

Response: server_tool_use (srvtoolu_…) → web_search_tool_result with web_search_result items (url, title, encrypted_content, page_age); citations via web_search_result_location. encrypted_content must be passed back unchanged in multi-turn.

Errors: too_many_requests, invalid_tool_input, max_uses_exceeded, query_too_long, request_too_large, unavailable.

Pricing $10 per 1,000 searches plus tokens; failed searches aren't billed; usage.server_tool_use.web_search_requests. May return stop_reason pause_turn on long searches — send the response back to continue.

Supports streaming, caching, Batches; Claude 4.6+ on the Claude API, Vertex and Foundry (not Bedrock). Web fetch is a companion server tool (web_fetch) that retrieves a URL's content.

r = client.messages.create(model="claude-sonnet-5", max_tokens=2048,

tools=[{"type":"web_search_20250305","name":"web_search","max_uses":3,

"blocked_domains":["untrusted.example"]}],

messages=[{"role":"user","content":"Latest Kubernetes CVE this month? Cite sources."}])

https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool

name code_execution; types code_execution_20250825 / 20260120 (REPL state, programmatic tool calling). No beta header needed now.

Sandbox: Python 3.11, Linux, 1 CPU, 5 GiB RAM, 5 GiB disk, NO internet; 90 s per REPL cell. Pre-installed: pandas, numpy, scipy, scikit-learn, matplotlib, openpyxl, python-docx, python-pptx, pypdf, reportlab…

Files in via the Files API (container_upload); outputs written to $OUTPUT_DIR come back as file_ids (downloadable).

Pricing: free with web search/fetch; otherwise 1,550 free container-hours per org per month, then $0.05/hour (5-minute minimum). Haiku 4.5: no REPL persistence.

r = client.messages.create(model="claude-sonnet-5", max_tokens=4096,

tools=[{"type":"code_execution_20250825","name":"code_execution"}],

messages=[{"role":"user","content":"Compute mean and p95 of these latencies: 120, 340, 90, 1500, 210"}])

r2 = client.messages.create(container=r.container.id, ...) # reuse state

https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview

Frontmatter: name (≤64 chars, lowercase/digits/hyphens, no 'anthropic'/'claude') and description (≤1,024 chars; must say what it does AND when to use it) — both required.

Progressive disclosure: L1 metadata always loaded (~100 tokens per skill); L2 SKILL.md body on trigger (<5k tokens recommended); L3 bundled files only when accessed.

Surfaces: Claude API (pre-built pptx/xlsx/docx/pdf + custom via /v1/skills; REQUIRES the code execution tool), Claude Code (custom only, ~/.claude/skills/ or .claude/skills/), claude.ai (per-user).

API: container={skills:[{type:'anthropic', skill_id:'pptx', version:'latest'}]}; max 20 skills per request; upload ≤30 MB; Skills API endpoints under /v1/skills.

Sandbox has no network and no runtime package install. Treat third-party skills like installing software.

r = client.messages.create(model="claude-sonnet-5", max_tokens=4096,

container={"skills":[{"type":"anthropic","skill_id":"xlsx","version":"latest"}]},

tools=[{"type":"code_execution_20250825","name":"code_execution"}],

messages=[{"role":"user","content":"Build a workbook of last quarter's incident counts by service."}])

https://docs.claude.com/en/api/agent-sdk/overview

Framework landscape: Claude Agent SDK (Anthropic; Claude Code's loop as a library), LangGraph (graph of nodes/edges with explicit state, checkpoints, human-in-the-loop interrupts), LangChain agents, CrewAI (role-based crews), AutoGen (conversational multi-agent), plus DIY loops on the Messages API.

Anthropic's guidance: frameworks are fine to start but add abstraction that hides prompts and responses; understand the underlying calls; prefer the simplest thing that works.

LangGraph concepts worth recognising: state (typed dict), nodes (functions/LLM calls), edges (conditional routing), checkpointer (persist state between steps → resumability and time travel), interrupt() for human approval — maps to the workflow patterns (routing = conditional edge; orchestrator = node that fans out).

Memory management: short-term = the context window (manage with summarisation, context editing/compaction); working memory = scratchpad files or state objects; long-term = retrieval store (vector/keyword DB), a memory tool, or Claude Code's auto memory; episodic = session logs. Write durable facts to persistent storage before compaction.

Deployment models: in-process library (Agent SDK), headless CLI in CI (claude -p), hosted Managed Agents (Anthropic-run sandbox, session-hour pricing), your own container with the SDK; choose by control vs operations burden.

Manager hierarchies: orchestrator delegates to workers (subagents) with narrow briefs and restricted tools; results summarised back; depth and concurrency limits prevent runaway trees.