OpenAI Agents SDK & Native Primitives Best Practices

Ten practices for building on OpenAI Agents SDK, Anthropic Messages tool loops, and peer native kits without accidentally inventing a worse private framework. Use this list in design reviews and before promoting a spike to production.

How to Use This List

Walk A when designing agents; B when wiring tools/MCP/handoffs; C when operating in production.
Tick an item only when code or runbooks prove it, not as aspiration.
Pair with When Native SDK Primitives Are Enough (and When They Aren't) for stay-vs-migrate calls.
Re-check after new tools, new specialists, or provider SDK majors.

A - Design the Agent Surface

1. Keep domain tools pure. No from agents import ... inside business logic modules; adapters own SDK types.
2. One job per agent. Split triage vs specialists when prompts or tool allowlists conflict.
3. Prefer small tool allowlists. Models choose worse as catalogs grow; filter MCP tools aggressively.
4. Put stop conditions in the host. Max turns, wall-clock, cost caps, and cancel flags are not optional prompt hopes.
5. Version prompts and schemas as data. Store next to code with owners; do not leave them only in constructor strings on laptops.

B - Wire Handoffs, Guardrails, MCP, and Loops

6. Use native handoffs for control transfer; agents-as-tools when the manager must synthesize. Do not mix metaphors without a diagram.
7. Place guardrails at the right boundary. Input on the first agent, output on the final agent, tool guardrails on risky function tools; do not assume they wrap every specialist automatically.
8. Scope MCP like production APIs. Allow lists, path roots, require_approval on writes, and server-side authZ - MCP is not a security boundary by itself.
9. Own Anthropic-style loops explicitly. If you are not on a Runner, enforce max_steps, correct tool_result pairing, and error surfacing yourself.
10. Avoid reinventing graphs on top of natives. If you need checkpoints, joins, or multi-day resume, adopt LangGraph / MS workflows / a real state machine instead of agent_os.py.

C - Operate and Evolve

11. Trace every production run. Use provider traces plus your request ids; log last agent name, tool names, and guardrail tripwires.
12. Budget tokens and tool calls per request class. Alert on runaway loops; kill switches beat postmortems.
13. Eval golden paths and failure paths. Include handoff routing, MCP failures, and guardrail blocks in CI or scheduled suites.
14. Pin SDK versions and read changelogs. Native agent kits move fast; verify model ids and APIs at build.
15. Document the exit hatch. Pure tools, schemas, and an ADR stating when multi-cloud or durable graphs force a control-plane change.

Applying These Practices in Order

Design (1-5): cheapest place to prevent lock-in and runaway agents.
Wiring (6-10): launch blockers for multi-agent and tool-connected systems.
Operate (11-15): keeps natives honest under real traffic and SDK churn.

FAQs

Why more than ten checkboxes?

Items 1-10 are the core build practices promised in the title. Items 11-15 extend them into operations so the list stays useful after launch.

What is the single highest-leverage practice?

Pure tools with host-enforced stop conditions. Everything else is easier if those two hold.

Do I need guardrails if tools are read-only?

Still useful for cost and off-topic abuse, but priority rises sharply when tools can write, pay, or exfiltrate.

Should every agent use MCP?

No. Use MCP when externalized servers reduce duplication. Local function tools remain better for core product actions you fully control.

How do I know I am reinventing a framework?

If you are implementing generic checkpointing, complex join semantics, or a plugin graph DSL on top of the SDK, you are there.

Are OpenAI handoffs mandatory for multi-agent?

No. Agents-as-tools or a single agent with tools may be simpler. Use handoffs when specialists should own the conversation.

How strict should MCP approvals be?

Default deny for destructive tools. Auto-approve only narrow read tools with low blast radius after review.

Can best practices differ for Google ADK?

Principles match: pure tools, least privilege, stop conditions, evals. API names and deploy gravity differ; apply the same review questions.

What belongs in on-call runbooks?

How to disable an agent flag, rotate keys, raise guardrail sensitivity, kill runaway tool servers, and read traces for handoff chains.

How often should we revisit stay-vs-migrate?

At least each quarter or when a B-list item from the decision cheatsheet becomes true.

Should product managers see this checklist?

Yes for items about job-per-agent, budgets, and exit strategy. Hide pure API wiring details unless they care.

Is structured `output_type` a substitute for guardrails?

No. Schemas enforce shape; guardrails enforce policy. You often want both on high-risk flows.

OpenAI Agents SDK Basics - first agent and tools
Handoffs and Guardrails in the OpenAI Agents SDK - routing and tripwires
Native MCP Support in the OpenAI Agents SDK - MCP transports
Anthropic's Tool Use Primitives for Building Agents Directly - explicit loops
When Native SDK Primitives Are Enough (and When They Aren't) - decision cheatsheet
Comparing OpenAI Agents SDK to Google's Agent Development Kit (ADK) - peer native comparison
What Native Provider Agent Primitives Give You Over a Framework - conceptual framing

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

OpenAI Agents SDK & Native Primitives Best Practices

How to Use This List

Walk A when designing agents; B when wiring tools/MCP/handoffs; C when operating in production.
Tick an item only when code or runbooks prove it, not as aspiration.
Pair with When Native SDK Primitives Are Enough (and When They Aren't) for stay-vs-migrate calls.
Re-check after new tools, new specialists, or provider SDK majors.

A - Design the Agent Surface

1. Keep domain tools pure. No from agents import ... inside business logic modules; adapters own SDK types.
2. One job per agent. Split triage vs specialists when prompts or tool allowlists conflict.
3. Prefer small tool allowlists. Models choose worse as catalogs grow; filter MCP tools aggressively.
4. Put stop conditions in the host. Max turns, wall-clock, cost caps, and cancel flags are not optional prompt hopes.
5. Version prompts and schemas as data. Store next to code with owners; do not leave them only in constructor strings on laptops.

B - Wire Handoffs, Guardrails, MCP, and Loops

6. Use native handoffs for control transfer; agents-as-tools when the manager must synthesize. Do not mix metaphors without a diagram.
7. Place guardrails at the right boundary. Input on the first agent, output on the final agent, tool guardrails on risky function tools; do not assume they wrap every specialist automatically.
8. Scope MCP like production APIs. Allow lists, path roots, require_approval on writes, and server-side authZ - MCP is not a security boundary by itself.
9. Own Anthropic-style loops explicitly. If you are not on a Runner, enforce max_steps, correct tool_result pairing, and error surfacing yourself.
10. Avoid reinventing graphs on top of natives. If you need checkpoints, joins, or multi-day resume, adopt LangGraph / MS workflows / a real state machine instead of agent_os.py.

C - Operate and Evolve

11. Trace every production run. Use provider traces plus your request ids; log last agent name, tool names, and guardrail tripwires.
12. Budget tokens and tool calls per request class. Alert on runaway loops; kill switches beat postmortems.
13. Eval golden paths and failure paths. Include handoff routing, MCP failures, and guardrail blocks in CI or scheduled suites.
14. Pin SDK versions and read changelogs. Native agent kits move fast; verify model ids and APIs at build.
15. Document the exit hatch. Pure tools, schemas, and an ADR stating when multi-cloud or durable graphs force a control-plane change.

Applying These Practices in Order

Design (1-5): cheapest place to prevent lock-in and runaway agents.
Wiring (6-10): launch blockers for multi-agent and tool-connected systems.
Operate (11-15): keeps natives honest under real traffic and SDK churn.

FAQs

Why more than ten checkboxes?

Items 1-10 are the core build practices promised in the title. Items 11-15 extend them into operations so the list stays useful after launch.

What is the single highest-leverage practice?

Pure tools with host-enforced stop conditions. Everything else is easier if those two hold.

Do I need guardrails if tools are read-only?

Still useful for cost and off-topic abuse, but priority rises sharply when tools can write, pay, or exfiltrate.

Should every agent use MCP?

No. Use MCP when externalized servers reduce duplication. Local function tools remain better for core product actions you fully control.

How do I know I am reinventing a framework?

If you are implementing generic checkpointing, complex join semantics, or a plugin graph DSL on top of the SDK, you are there.

Are OpenAI handoffs mandatory for multi-agent?

No. Agents-as-tools or a single agent with tools may be simpler. Use handoffs when specialists should own the conversation.

How strict should MCP approvals be?

Default deny for destructive tools. Auto-approve only narrow read tools with low blast radius after review.

Can best practices differ for Google ADK?

Principles match: pure tools, least privilege, stop conditions, evals. API names and deploy gravity differ; apply the same review questions.

What belongs in on-call runbooks?

How to disable an agent flag, rotate keys, raise guardrail sensitivity, kill runaway tool servers, and read traces for handoff chains.

How often should we revisit stay-vs-migrate?

At least each quarter or when a B-list item from the decision cheatsheet becomes true.

Should product managers see this checklist?

Yes for items about job-per-agent, budgets, and exit strategy. Hide pure API wiring details unless they care.

Is structured `output_type` a substitute for guardrails?

No. Schemas enforce shape; guardrails enforce policy. You often want both on high-risk flows.

OpenAI Agents SDK Basics - first agent and tools
Handoffs and Guardrails in the OpenAI Agents SDK - routing and tripwires
Native MCP Support in the OpenAI Agents SDK - MCP transports
Anthropic's Tool Use Primitives for Building Agents Directly - explicit loops
When Native SDK Primitives Are Enough (and When They Aren't) - decision cheatsheet
Comparing OpenAI Agents SDK to Google's Agent Development Kit (ADK) - peer native comparison
What Native Provider Agent Primitives Give You Over a Framework - conceptual framing

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

OpenAI Agents SDK & Native Primitives Best Practices

Search Documentation

OpenAI Agents SDK & Native Primitives Best Practices