OpenAI AgentKit & Agents SDK

The middle rung of three

OpenAI offers three ways to build an agent, and the useful thing to understand first is that they are a ladder rather than alternatives.

The SDK is the middle rung. The documentation is direct that it "runs inside your application" rather than being a managed service, so you deploy it, you scale it, and the agent's behaviour is in your codebase.

Claude Agent SDK makes the same choice explicit, and the reasoning transfers: a hosted agent is less to run and less to change, and a raw API is more work and more control.

What it gives you over a hand-written loop

Agent is the unit: a model, instructions, and the tools it may call.

Runner drives the loop and handles handoffs between agents. That is the piece worth having, because manual implementation shows the loop is about forty lines and the interesting part is the stopping conditions and the error handling around it.

Sessions hold conversation state, either in your own storage or the SDK's. That choice matters more than it looks: your storage means you own retention and can answer questions about it, which is the concern security and privacy concerns frames.

Handoffs let one agent pass work to another. This is the orchestration primitive, and multi-agent systems is the page on whether you want it: about 15 times the tokens of a chat, and coordination costs that do not show up in a token count.

Guardrails are a feature, not a promise

The SDK offers guardrails as a first-class concept, which is useful and easy to over-read.

A guardrail is a check you configure. It is not an enforcement boundary the model cannot cross, and constraining inputs and outputs covers where a constraint has to live to be one. A guardrail that runs in the same process as the agent, on output the agent produced, is a validation step. Validation steps are worth having; they are not a security model.

Treat them as the place to put the checks you would otherwise write by hand, and keep anything that must hold in code the agent cannot influence.

Choosing between the three rungs

Hosted Agents API when the agent is standard-shaped and you would rather not operate it. Less to run, and less you can change.

Agents SDK when you want the loop handled but the behaviour, the tools and the storage to be yours. The common answer for a product feature.

Responses API when the pipeline is a few steps and you would rather own the prompt assembly. For one retrieval-augmented call, an agent framework is more moving parts than the task has.

Before any of them, agent use cases is the question underneath: whether the loop earns roughly four times a chat interaction at all. A framework makes building an agent easy and does not make the agent a good idea.

Where to look when it goes wrong

Two habits, both from the general agent pages.

Log the fully assembled request rather than the SDK's inputs, for the reason LLM observability gives: a framework assembles the payload, and a bad answer is a payload you did not write.

Cap the iterations explicitly. The loop is the framework's, and the stopping condition is still a decision, which ReAct prompting covers.

Further reading

• OpenAI, Agents: the three approaches, the core objects and where state lives.
• Claude Agent SDK: the same decision at another provider.
• Manual implementation: the loop a framework replaces.
• Agent use cases: whether to build one at all.