Build provider-native agents with tools, handoffs, guardrails, and tracing.
The SDK packages agents, tools, handoffs, sessions, and traces.
Learners distinguish SDK agents from direct model calls.
Why this matters: This prevents overusing an agent framework for a single completion.
Problem anchor: a tutoring product needs a KB-searching agent, a quiz-writing specialist, guardrails on output, session continuity, and traces for review. A direct model call is no longer the whole app.
The Agents SDK wraps the model loop with agents, runs, tools, handoffs, sessions, guardrails, and tracing in Python and TypeScript ecosystems.
The tutor agent answers from KB notes. When the learner asks for practice, it hands off or calls a quiz-writer specialist. Tracing records model calls, tool calls, and handoff.
This is a good SDK fit because handoffs and trace inspection are product features.
Tools remain application capabilities.
Learners separate SDK tool plumbing from product safety.
Why this matters: OpenAI-native convenience does not remove security responsibility.
A function tool exposes ordinary code through a schema so the model can request it. Hosted and MCP tools may broaden capabilities, but the app still owns credentials, authorization, idempotency, approval, and auditing.
Guardrails can validate or block inputs and outputs, but they should complement deterministic checks. Do not put secrets or broad tokens into prompts or traces.
| Option | Surface | Use for | Watch | When to choose | Cost | Complexity |
|---|---|---|---|---|---|---|
| Function tool | Expose application code to the agent. | Search, lookup, safe actions. | Permission and idempotency remain yours. | Use for narrow operations. | Medium | Medium |
| Handoff | Transfer or delegate to specialist agent. | Real ownership boundaries. | Ambiguous ownership across turns. | Use when specialist should own task. | Medium | Medium |
| Guardrail | Validate/block input or output. | Safety and schema gates. | Must be tested on adversarial cases. | Use with deterministic tests. | Low | Medium |
A handoff is a workflow boundary.
Learners design handoff boundaries.
Why this matters: Unclear handoffs cause state, tone, and responsibility bugs.
An agent-as-tool lets a manager call a specialist and keep control. A handoff can transfer the active task or conversation to a specialist. The product should decide which ownership model matches user expectations.
Handoffs need clear names, reasons, and return behavior. If a quiz writer takes over, should future questions return to the tutor? The state strategy must answer that.
The tutor answers concepts. When the learner asks “quiz me,” it hands off to quiz_writer. After the quiz, control returns to tutor for explanation.
The trace records the handoff reason and final quiz artifact.
Start with one agent and one safe tool.
Learners connect SDK primitives to code.
Why this matters: Concrete code prevents abstract framework talk.
Start with one harmless lookup tool and one agent. Add specialists, sessions, and guardrails after the trace is clear.
Spaced recall: from choosing frameworks, prototype the risky path next, not a decorative multi-agent team. For OpenAI Agents SDK, that may be tool permission or handoff ownership.
from agents import Agent, Runner, function_tool @function_tool def search_kb(query: str) -> str: """Search approved lesson notes for a learner question.""" return "LangGraph is useful for explicit state, checkpoints, and interrupts." tutor = Agent( name="Agentic AI tutor", instructions="Answer from the KB when possible and ask for clarification when underspecified.", tools=[search_kb], ) # result = await Runner.run(tutor, "When should I use LangGraph?") # print(result.final_output) print(search_kb("LangGraph"))
It prints the KB sentence about LangGraph state, checkpoints, and interrupts.
SDK conveniences need state and telemetry discipline.
Learners plan production operation for SDK agents.
Why this matters: Mixing histories, sessions, and continuation IDs can confuse replay and privacy.
The SDK supports different ways to continue work: explicit histories, SDK sessions, or server-managed continuation strategies. Mixing them in one flow can duplicate context or lose constraints.
Traces may include prompts, user data, model outputs, and tool results. Treat them like production telemetry with retention, redaction, and access control.
Review the run trace and state strategy.
Retrieval prompt: reconstruct Agents SDK by naming Agent, Runner/run, function tools, hosted/MCP tools, handoffs, sessions, guardrails, tracing, and state strategy.
Design an OpenAI Agents SDK tutor with a KB search tool, quiz-writer handoff, output guardrail, session strategy, and trace fields. Next rung: compare with LangGraph explicit control.
You need a one-off answer from GPT-4o — no looping, no tools, no memory. Which approach is most appropriate?
The Agents SDK earns its keep when you need looping, tools, or multi-agent coordination; a single, stateless completion is simpler and cheaper with a direct API call.
Your agent calls an external payment API. Before every call you want to log the arguments and require a human 'approve' signal for amounts over $500. Where does this logic live?
Validation, logging, and approval gates are application-layer responsibilities that wrap the tool call; they must not be delegated to the model, which can be prompted around.
In your own words: what is the key difference between using another agent as a tool versus using a handoff to that agent? Who owns the conversation after each?
With agent-as-tool the caller stays in charge; with a handoff the specialist takes over ownership for the remainder of that conversational thread.
You are coding a small agent. In the OpenAI Agents SDK, what is the correct order of steps to wire up a function tool?
The function must exist and be registered as a tool before it is attached to an Agent; the Runner then executes the agent loop that can invoke that tool.
A teammate suggests storing full conversation traces in the same database table as user profile records to keep queries simple. What is the strongest objection from a production-data perspective?
Trace data can contain PII, secrets passed to tools, and model reasoning — it requires its own access controls, audit logging, and retention rules, separate from general application data.