What is an agent SDK?
An agent SDK is a library that runs the agent loop for you: send a prompt, let the model call tools, feed results back, repeat until done. The Claude Agent SDK packages the loop, tools and permissions behind Claude Code for Python and TypeScript. OpenAI's Agents SDK is the equivalent for its models, built on agents, handoffs and guardrails.
Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.
Install the package. Both bundle a native Claude Code binary, so most installs need nothing else; an API key in ANTHROPIC_API_KEY is the default sign-in.
npm install @anthropic-ai/claude-agent-sdk pip install claude-agent-sdkCall query() with a prompt and options such as allowedTools, permissionMode, systemPrompt, mcpServers and maxTurns. It returns an async iterator of messages.
The SDK sends the prompt, system prompt and tool definitions to the model. The model replies with text, one or more tool calls, or both.
The SDK runs each tool: Read, Edit, Bash, Glob, Grep, WebSearch, MCP tools. A PreToolUse hook can block a call. Results go back to the model; that is one turn.
Turns repeat until the model answers with no tool calls. The stream ends with a ResultMessage: text, token usage, cost and a session id you can resume later.
When the context window fills, the SDK compacts older history into a summary on its own and tells you with a compact_boundary message.
Source: Claude Agent SDK overview
Agent SDK versus calling the model directly
The model API gives you one round trip: a request in, a response out. If the response asks for a tool, your code has to run it and send the result back, and keep doing that until the model stops. Everything around that loop is yours to build: which tools exist, which ones need a human's approval, what happens when the context window fills, how to pick a session up tomorrow.
An agent SDK is that surrounding code, written once. You call a single function and consume a stream of messages while the loop runs. The Claude Agent SDK is explicit about where it came from: it is Claude Code as a library. The same Read, Edit, Bash, Glob and Grep tools, the same permission rules, the same .claude/ configuration loading, the same hooks, in a process you operate. OpenAI's Agents SDK comes from the other direction. It grew out of the experimental Swarm project and describes itself as having very few abstractions: an Agent is instructions plus tools, a Runner runs it, and the interesting parts are handoffs between agents, guardrails that validate inputs and outputs, sessions for memory, and tracing.
Example: an agent that fixes a failing test
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Fix the failing tests in auth.ts",
options: {
allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"],
permissionMode: "acceptEdits",
maxTurns: 30
}
})) {
if (message.type === "result") console.log(message.subtype, message.total_cost_usd);
}
Behind that call the SDK runs npm test, reads the failing file, edits it, reruns the tests, and finally answers with text and no tool calls, which ends the loop. Four turns, maybe five. allowedTools pre-approves those five tools so nothing prompts; tools not listed are still available but fall through to the permission mode. maxTurns is the brake: without a limit the loop runs until the model decides it is done, which is fine for a scoped task and unbounded for "improve this codebase". maxBudgetUsd is the other brake: the query stops when the SDK's running cost estimate reaches it. The estimate can overshoot a little, so leave headroom.
When to use one
Use an agent SDK when the agent is a feature of your product or your pipeline rather than something a developer drives from a terminal: a bot that triages issues, a CI step that fixes lint across a repository, a research assistant inside your app. Use the terminal CLI when a person is in the loop anyway. Use the raw API when you need one or two tool calls and want to control every token.
An agent built this way can connect to any MCP server through mcpServers, so it can, for instance, pull and publish an Intraface board exactly as a terminal agent would.
Common mistakes
- Reading
resultbefore checkingsubtype. The text is only present onsuccess.error_max_turnsanderror_max_budget_usdcarry cost and session id but no result. - Putting standing rules in the prompt. Compaction summarises early messages, so instructions there can vanish. Rules that must survive belong in
CLAUDE.md, which is reinjected every request. - Letting every MCP server load all its tools. Each schema costs context. Tool search defers them by default; keep it on, and scope subagents to the tools they need.
- Using
bypassPermissionson a shared machine. It is meant for containers. In TypeScript it also requiresallowDangerouslySkipPermissions: trueas a second deliberate step.
FAQ
- Is the Claude Agent SDK the same as the Claude Code SDK?
- It is the renamed and expanded successor. The docs ship a migration guide from the Claude Code SDK packages to the Agent SDK. Products built on it may say "Claude Agent" or "Powered by Claude" but not "Claude Code", and they must use API key sign-in rather than claude.ai login.
- How is an agent SDK different from the Messages API?
- With the API you write the tool loop: send a request, read the tool call, run it, send the result, repeat. An agent SDK owns that loop and adds the built-in tools, permission rules, hooks, subagents, compaction and sessions. Anthropic's client SDKs also offer a tool runner for a middle ground.
- Which agent SDK should I pick, Claude's or OpenAI's?
- They are tied to their model providers, so the choice usually follows the model. Claude's gives you Claude Code's tools and file-system permissions out of the box. OpenAI's is deliberately small: agents, handoffs between agents, guardrails on inputs and outputs, sessions and tracing, with tools you define yourself.
Stop sending HTMLover Slack.
Create an account in a minute, connect your coding agent, and make your first board.