The Claude Agent SDK takes the harness that powers Claude Code — agentic loop, file tools, bash, context management — and packages it as a library you can run on your own infrastructure.
Building an agent directly on the Claude API means writing your own `while stop_reason == "tool_use"` loop, defining every tool with its JSON schema, handling shell command execution, managing permissions, and deciding how to compress context as the conversation grows. The Claude Agent SDK (`claude-agent-sdk` in Python, `@anthropic-ai/claude-agent-sdk` in TypeScript) solves all of that out of the box: it ships with Read, Write, Edit, Bash, Glob, Grep, WebSearch, and WebFetch already implemented, built-in context management, hook support, subagents, and the same permission system Claude Code uses.
It's important not to confuse it with the standard API's "tool runner" (`client.beta.messages.tool_runner`), which is a much lighter helper that only automates the call-execute-repeat cycle over tools you define, with no built-in tools or filesystem access. The Agent SDK is Claude Code packaged as a library; the tool runner is a helper over `POST /v1/messages`. Both require you to host the compute — neither includes managed infrastructure (that's what Managed Agents, a separate product, offers).
The entry point is the `query(prompt, options)` function, which returns a stream of events as the agent reasons, uses tools, and produces text:
Underneath, this runs the same Claude model you'd use via the direct API, with the full harness for turn management, tool execution, and context compaction already solved.
The SDK exposes a permission system with three modes: `default` (asks for confirmation on sensitive actions), `acceptEdits` (auto-approves file edits but not shell commands), and a fully autonomous mode meant only for already-isolated environments like an ephemeral container. For more granular control, hooks let you intercept every tool invocation before or after it runs — useful for audit logging, input validation, or blocking specific command patterns.
This is the same pattern Claude Code uses internally for its `settings.json` system — the SDK simply gives you the same mechanism programmatically.
Like Claude Code, the SDK supports subagents: instances with their own system prompt, restricted tool set, and isolated context, invoked for scoped tasks without polluting the main context with intermediate detail. This is particularly valuable in long-running agents — a code review agent, for example, can delegate "review the authentication module for vulnerabilities" to a subagent, receive only the findings summary, and continue with the main context intact.
For long conversations, the SDK automatically manages compaction as context nears the model's limit — summarizing old turns instead of truncating them, preserving the coherence of the running task without you having to implement that logic yourself.
The SDK accepts MCP servers with the same configuration as Claude Code, letting you connect the agent to internal systems (databases, corporate APIs, ticketing systems) without writing the integration connector from scratch — you just declare the MCP server and the set of tools it exposes. You can also define your own tools with a standard JSON schema when the logic is specific to your application and doesn't warrant a separate MCP server.
If you need a "coding assistant"-type agent running on your own infrastructure — CI/CD, an internal backend, a technical support tool with file and command access — the Agent SDK is the most direct option: less of your own code than a manual loop, full control over where it runs. If instead you want Anthropic to host both the agent loop and the execution sandbox (persistent sessions, per-session containers, no infrastructure of your own to maintain), the right option is Managed Agents, a separate product with its own API. And if you only need to automate a handful of your own tools without the whole Claude Code apparatus, the standard API's tool runner is lighter and sufficient.
Carlos Montiel is an enterprise AI solutions architect. He implements LLMs, Agents, RAG, and orchestrators for companies across Guatemala and Latin America. Reach out for a consultation.
Contact Carlos Montiel