SDK Overview —
Why Not Just Call the API?
The core idea
Imagine you hire a contractor. Instead of standing over their shoulder issuing one instruction at a time, you hand them a goal and they figure out the steps, do the work, check the result, and come back when done. The Agent SDK does exactly that — you give it a prompt and it runs the think → act → verify loop until the task is complete.
The problem with the raw API
When you use the Anthropic API client directly and want Claude to use tools, you have to write the execution loop yourself:
response = client.messages.create(...)
# You must implement this
while response.stop_reason == "tool_use":
result = your_executor(response)
response = client.messages.create(
tool_result=result,
...
) async for msg in query(
prompt="Fix the bug"
):
print(msg)
# read → edit → test → done What the SDK gives you
Quick install
terminal# Python pip install claude-agent-sdk # TypeScript / Node.js npm install @anthropic-ai/claude-agent-sdk # Set your API key export ANTHROPIC_API_KEY=sk-ant-...
Hello, agent
Here's the minimum code to run an agent that reads a file, finds a bug, and fixes it — in Python:
Python — hello_agent.pyimport asyncio from claude_agent_sdk import query, ClaudeAgentOptions async def main(): async for message in query( prompt="Find and fix the bug in auth.py", options=ClaudeAgentOptions( allowed_tools=["Read", "Edit", "Bash"] ) ): print(message) # Claude reads → finds bug → edits → done asyncio.run(main())
SDK vs raw API — when to use which
| Criteria | Raw API Client | Agent SDK |
|---|---|---|
| Setup complexity | Low — plain API call | Medium — but does far more |
| Tool execution | You implement yourself | SDK handles it all |
| Best for | Chat UI, simple Q&A | Automation, pipelines, CI/CD |
| Control level | Fine-grained, per-step | Goal-level, loop is managed |
| Context length | You manage | Auto-compacted |
Tip: Many teams use both — the raw API client for interactive chat UI, and the Agent SDK for background automation pipelines. They're complementary, not mutually exclusive.
What's next
In the next post we'll go deep on query() — the central function of the SDK.
We'll cover all its parameters, the four message types you get back from the stream,
and how to write clean handlers for each.