Using SDKs Directly

The smallest thing that works

A model call is an HTTP POST. The provider's own client wraps it in types, retries and a streaming helper, and stops there. Anthropic publishes client SDKs for seven languages: Python, TypeScript, C#, Go, Java, PHP and Ruby. It describes what they are for in one line worth taking literally:

The CLI, client SDKs, and libraries are for calling the Claude API yourself: you send each request and handle each response.

That is the whole proposition. Agent loops, tool execution, memory and orchestration sit above it, in a different tier of tooling with a different set of trades.

What the direct call gives you

The argument for starting here is not minimalism. It is that the things you will spend your time on are all visible.

You can read the request. Every token you are paying for is in an object you constructed. When the bill is wrong or the context is full, you look at the thing you built rather than at what a framework assembled.

You can read the response. stop_reason, the usage figures, the content blocks. A framework that returns a string has thrown away the fields that tell you whether the answer was truncated, what it cost, and whether a tool was requested.

Errors arrive as themselves. A rate limit is a rate limit, not a wrapped exception two layers down with the status code stripped.

Upgrades are yours. A provider ships a parameter and you can pass it the same day, rather than waiting for an abstraction to expose it.

What you are opting out of

Being honest about the other side: a framework is not nothing.

You write the agent loop yourself, which manual implementation covers in about forty lines. You write conversation state, which is state and historical context. You write retrieval if you need it. None of that is hard, and all of it is work.

The case for doing it anyway is that these are the parts of your application that are specific to your application. A framework's agent loop is a guess at what everyone needs; yours is a match for what you need. But if you are building something whose shape the framework already fits, the framework is a reasonable answer and Claude Agent SDK covers what it buys.

Portability is a real consideration and a smaller one than it looks

The usual argument for a framework is that it lets you change provider. That is worth examining, because the abstraction that buys it is not free.

Providers already converge on each other's surfaces: most of the ecosystem speaks the OpenAI chat schema, and Anthropic publishes an OpenAI SDK compatibility layer. OpenAI-compatible APIs covers how far that goes, which is further than you expect for the common path and not as far as the word "compatible" suggests.

The part that does not port is the part that matters: caching semantics, tool result shapes, how thinking is returned, what a stop reason is called. A framework can hide those differences only by refusing to expose the features that differ, which is a portability you paid for in capability.

Where to start

Call the API directly for the first version. Read the response object. Look at the usage fields. Handle the stop reason.

Then add the specific thing you find you need, rather than the bundle that contains it. Most applications turn out to need a loop, a place to keep state, and a way to validate output before acting on it, and each of those is a decision worth making on purpose.

Reach for a framework when you can name what it does that you would otherwise write, and when what it does matches what you want. "It might be useful later" is not that.

Further reading

• Anthropic, CLI, SDKs and libraries: the client SDKs, and the line between calling the API and running an agent.
• Claude Messages API: the request and response shape underneath the client.
• Manual implementation: the loop, written out, so you can judge what a framework saves.
• Claude Agent SDK: the tier above, and what it covers.