Agent SDKs and Frameworks

What an SDK is — and what you are buying

An SDK (software development kit) is a box of ready-made parts for one specific job. Nothing exotic: someone did the boring work once and handed you the result as a library you install with one command.

Here is why you should care. Tools and function calling showed that an agent is a while loop around an API call — and you could honestly write that loop yourself in an afternoon. What you cannot write in an afternoon is everything around it: turning your Python functions into the JSON descriptions the model needs, checking that the model’s arguments are valid, retrying when the provider says “too many requests,” logging every step so you can debug step nine, handling the model returning nonsense. That surrounding work is the plumbing, and it is where agent projects actually spend their time. An SDK is the plumbing, already written, tested by thousands of other people, and maintained for you.

The trade is simple: you give up a little control and get your weekends back.

So what exactly is in the box? A short list, and it is worth being precise:

• The loop itself — you define tools and a goal; the SDK runs think, act, observe, repeat until the model says done.
• A tool registry — declare functions once (often from type hints or docstrings); the SDK generates the schemas (machine-readable descriptions of each tool’s arguments), validates arguments, routes calls.
• Handoffs and structure — ready-made primitives for letting one agent pass control to another (a handoff), or for forcing outputs into typed schemas so the result is predictable.
• Retries and error handling — rate limits (the provider telling you to slow down), timeouts, malformed tool calls: the boring failure modes, handled the same way everywhere.
• Tracing and observability — a step-by-step log of every prompt, tool call and token count. When an agent misbehaves at step nine, this is how you find out why.

None of it is magic. All of it is code you could write. The question is whether writing and maintaining it yourself is worth your time.

The two native SDKs

The SDKs from the model providers are thin and close to the metal. Here are minimal agents side by side:

1# pip install openai-agents
2from agents import Agent, Runner, function_tool
3import requests
4 
5@function_tool
6def get_weather(city: str) -> str:
7  #98c379">"""Get current weather for a city."""
8  r = requests.get(#98c379">"https://wttr.in/" + city,
9                   params={#98c379">"format": "3"}, timeout=10)
10  return r.text
11 
12agent = Agent(
13  name=#98c379">"WeatherBot",
14  instructions=#98c379">"Answer weather questions briefly.",
15  tools=[get_weather],
16)
17 
18result = Runner.run_sync(agent, #98c379">"Umbrella in Prague today?")
19print(result.final_output)
20# the SDK ran the whole loop for you

Notice the honest difference in character. The OpenAI Agents SDK is a lightweight library: you write tools, it runs the loop, and it adds handoffs and guardrails as first-class concepts. The Claude Agent SDK is closer to “Claude Code as a library” — it ships with built-in tools (files, shell, search) and a permission system, so you are configuring an agent rather than assembling one from parts. Choose by what you need: custom tools and orchestration, or a ready-made coding/ops agent with guardrails.

The frameworks

LangChain and LlamaIndex sit one level higher. LangChain is a large toolbox of abstractions — agents, memory, document loaders, vector store integrations — with a plugin ecosystem covering hundreds of services. LlamaIndex started as the RAG framework and grew agent capabilities on top; if your agent’s job is mostly “search my documents and reason over them,” it fits naturally.

The trade-off is real on both sides. Frameworks give you speed to the first demo and a lot of pre-built integrations. They also give you an extra layer of abstraction — a friendly name for code that hides complicated code underneath — over API calls you already understand. That is fine until something breaks inside the layer, and then you debug through someone else’s abstractions.

Framework APIs also churn: abstractions get renamed and rewritten between major versions, and your code comes along for the ride.

Not sure which way to go? Describe your situation to a chat assistant and let it argue both sides. Copy this, fill in the brackets, paste it into ChatGPT, Claude or any chat with a model:

I am building an AI agent and I cannot decide whether I need an SDK or a framework. Here is my situation:

- What the agent should do: [one sentence]
- Tools it needs: [list them, or write "none"]
- How many steps: [one step / a loop of several steps]
- Programming language: [Python / JavaScript / I do not code]
- What I care about most: [ship it today / see every step for debugging / be able to swap models later]

Please answer:
1. For my case, is calling the API directly enough, or do I need an SDK or a framework? Say which and why.
2. If I skip the SDK, list the exact things I will have to write and maintain myself.
3. If I use an SDK, which one fits and what will it cost me in control?
Answer in plain language first, code second. Explain any jargon you use.

What to actually evaluate

Whichever option you pick, ask the same five questions:

• Tracing: can I see every prompt, tool call, and token count in a UI?
• Model portability: how hard is it to swap providers later?
• Escape hatch: can I drop to raw API calls for one weird case?
• Failure behavior: what happens on a tool crash, a rate limit, a bad JSON argument — silently swallowed or surfaced?
• Maintenance signal: release cadence, changelog, how the project handled its last breaking change.

Check yourself

Where to go from here

You now know what SDKs give you and what they cost you in control. A related stop later in the roadmap: MCP — the USB port for AI, the open standard that decouples your tools from any one SDK. And if the terms in this article still feel abstract, the earlier lesson on what an AI agent actually is is the right place to back up.