The Claude Agent SDK Loop

One loop underneath every agent

Strip away the branding and every useful agent runs the same loop:

gather context → take action → verify work → repeat.

The Claude Agent SDK is Anthropic's packaged version of this loop — the same machinery that powers Claude Code, exposed so you can build your own agents. Understanding the three phases tells you exactly where to invest when your agent underperforms.

Phase 1: gather context

The agent needs to know enough to act, without drowning its context window.

• Start with agentic search — the agent running grep, glob, and file reads over a filesystem, one query at a time. Each result informs the next search, so only relevant slices ever enter the window.
• Add semantic search later. Embedding-based retrieval (pre-indexing documents as vectors) is faster but adds infrastructure and can surface stale or irrelevant chunks. Add it only when measured performance demands it.
• Use subagents for parallel exploration. A subagent explores in its own context window and returns only a summary — the exploration mess never lands in the main conversation.
• Rely on compaction for long runs. When the window nears its limit, the SDK summarizes the conversation and continues with the compressed version.

Phase 2: take action

Tools are the agent's hands, and they sit prominently in the context window — so design them around the most frequent actions, not around your API's shape.

Three tiers of action, in order of preference by situation:

1. Purpose-built tools for the operations the agent does constantly.
2. Bash and scripts for general computer work — the flexible fallback.
3. Generated code when output must be precise, composable, and reusable. Writing a script that processes 500 files beats 500 tool calls.
4. MCP servers for standard integrations (Slack, GitHub, Asana) — connection and auth handled by the protocol instead of custom glue.

Permissions gate this phase. The SDK lets you allowlist specific tools and commands, prompt the user for risky ones, or run a classifier that blocks only dangerous actions. The design goal: prompts stay rare enough that each one gets real attention — after the tenth approval you're not reviewing, you're clicking.

Hooks are the deterministic layer: user-defined shell commands that fire at lifecycle events (before a tool runs, after a file edit, when the agent tries to stop). Unlike instructions in a prompt — which are advisory — hooks always run. A pre-tool-use hook can hard-block rm -rf; a post-edit hook can auto-run a formatter; a stop hook can run the test suite and refuse to let the turn end until it passes.

Phase 3: verify work

This phase separates agents that compound errors from agents that fix them. An agent needs ground truth from the environment — a signal it didn't generate itself. Three kinds:

Without a check it can run, "looks done" is the agent's only signal — and you become the verification loop.

When you don't need an agent at all

An agent earns its cost only on open-ended problems where you can't predict the number of steps. If you can write the steps down — fetch, transform, post — a linear script with LLM calls at fixed points is faster, cheaper, and debuggable. This is the SDK team's own guidance: a hardcodable workflow should stay a workflow.

A worked example: the email assistant

An email-triage agent shows all three phases:

1. Gather: it searches the inbox with targeted queries ("from:billing after:Monday") instead of loading every thread into context.
2. Act: it drafts a reply using a send_draft tool — gated by a permission rule that requires human approval for anything leaving the machine.
3. Verify: a checker step confirms the draft's tone matches guidelines and every factual claim traces to a real thread before send.

Debugging the loop

When an agent underperforms, walk the loop backwards and ask, in order:

• Does it lack information it needed? (gather problem)
• Could search be restructured — better tools, better file layout? (gather)
• Should a soft rule become a hard tool-call constraint or hook? (act)
• Does it need more or better-shaped tools? (act)
• Do you have a representative test set to even measure any of this? (verify)

Most "the model is dumb" complaints resolve into one of these five, and only the last one requires new evals — the rest are engineering you control.