I built a working three-agent research pipeline on a Thursday afternoon and demoed it Friday morning. That basically never happens. I've spent longer configuring a CI runner.
Then on Monday, Gwen sent me a message with three question marks and a screenshot of the usage dashboard. So — this teardown is a love letter with a warning label stapled to it.
What it is
A small Python (and now TypeScript) library for building agents: things that take instructions, call tools, and can hand work to other agents. It replaced the older Swarm experiment. Four core concepts and that's genuinely it:
- Agents — a model plus instructions plus tools.
- Handoffs — one agent passing control to another.
- Guardrails — validation that runs alongside, and can stop, a run.
- Sessions & tracing — conversation history and a visual trace of everything that happened.
Comparing it with LangGraph: LangGraph gives you more control over the graph and state, and more rope to hang yourself with. The Agents SDK is opinionated and gets you moving in an afternoon. For a first production agent, I'd choose this. For a complex stateful workflow with branching approvals, I'd choose LangGraph.
What we built with it
Pipeline 1 — competitive research briefs. A planner agent breaks a topic into questions, a searcher agent gathers sources with web search, a writer agent produces a two-page brief with citations. Runs on demand, about 30 times a week.
Pipeline 2 — RFP triage. Incoming tender documents get classified, key requirements extracted into a structured schema, and a go/no-go recommendation drafted for a human. Roughly 15 documents a week, each 40–120 pages.
Key specs
| Feature | Our experience |
|---|---|
| Language support | Python is mature; the TypeScript version was fine but a step behind on examples. |
| Tracing UI | Best-in-class. Free with an API account. This alone justified trying it. |
| Guardrails | Input and output validators run concurrently and can halt a run. We use one to block anything containing client names leaving our tenant. |
| Sessions / memory | Built-in conversation persistence, including SQLite for local work. Saved us writing our own. |
| Model flexibility | Officially OpenAI-first, but works with any Chat Completions-compatible endpoint. We route some steps to a cheaper local model. |
| Human-in-the-loop | Possible, but you build the pause/resume pattern yourself. This is the biggest gap for business use. |
Pricing (it's the model bill, that's all)
The SDK is free and open source. What you pay is tokens. Here's our actual month-two spend, once we'd stopped being silly:
| Pipeline | Runs/month | Avg cost/run (before tuning) | Avg cost/run (after) |
|---|---|---|---|
| Research briefs | 128 | $1.94 | $0.61 |
| RFP triage | 62 | $3.40 | $1.12 |
| Monthly total | 190 | $459 | $147 |
The tuning was three things: routing the planner and searcher to a smaller model, capping handoff depth at 3, and trimming what gets passed along on each handoff. That last one was the big one — we were forwarding the entire conversation history to every agent for no reason at all.
What we loved
- Time to first working agent: about 40 minutes. Including reading the docs and making tea.
- The tracing view. You can see every tool call, every handoff, every token. Debugging agents without this is guesswork.
- Small API surface. Four concepts, learnable in a sitting. Onboarding a second developer took an hour.
- Guardrails are first-class, not an afterthought. Our compliance colleague was pleasantly surprised.
- Genuinely good examples repo. The customer-service and research-bot samples are close to production shapes.
What we'd warn you about
- Default handoff behaviour is expensive. Trim context deliberately or you'll pay to re-read the same history four times per run.
- Easy to over-architect. Handoffs are so pleasant to write that you make five agents where two would do. See our loops thread.
- Human-in-the-loop needs building. For anything customer-facing you'll write your own approval queue.
- Moves fast. Two minor breaking changes in five weeks. Pin your versions.
- Provider gravity. It works with other models, but the smooth path is OpenAI's. Know what you're signing up for.
Crew verdict — 7.9 / 10
The best developer experience we've had for building agents, and the tracing is worth the price of admission on its own. Docked marks for cost-safety defaults and the missing human-approval pattern, both of which matter enormously in a business context.
Use it if: you have a developer and a genuinely multi-step task. Skip it if: your "agent" is really one prompt and a tool call — just call the API directly and save yourself the abstraction. And if nobody on your team writes code, go and read the n8n teardown instead.
Our starter checklist
- Set
max_turnsand a handoff depth limit before you write anything else. - Add an output guardrail that blocks sensitive data leaving the run.
- Turn tracing on and actually look at a full trace before you ship. You will find something surprising.
- Route cheap steps to a cheap model. Planners and routers rarely need a frontier model.
- Log a cost estimate per run into your own database, tagged by project. Future-you and your finance lead will be grateful.
Official links
- Agents SDK documentation
- GitHub repository & examples
- Current model pricing
- Agents guide on the platform docs
Crew replies
The "easy to over-architect" warning is the truest thing in this teardown. It's so nice to write handoffs that you forget every handoff is a full model call with a growing context. Two agents beats five, almost always.
From the non-engineering side: the tracing view is the first AI debugging tool I've been able to sit in front of and roughly follow. That matters more than people think — it's how a manager stops treating the system as magic.
Building your first one?
Sam's weekend guide covers the same journey without assuming you can code. Start there, then come back to this when you outgrow it.
Read the beginner guide → All teardowns