OpenAI Agents SDK: Agents, Tools, Handoffs, Guardrails

Small primitives, serious workflows

OpenAI's Agents SDK organizes agent apps around agents with instructions and tools, handoffs for delegated ownership, guardrails and human review for boundaries, results/state for resumable runs, and tracing/evaluation for inspection.

It is useful when you want agent orchestration without building every loop and guardrail from scratch. It is not a license to stop understanding the loop. If the raw loop is opaque, the framework only hides the bug more elegantly.

Guardrails are boundary checks

Input guardrails check early user input before expensive or risky work starts. Output guardrails check final answers. Tool and executor checks protect side effects. Human review pauses runs before sensitive actions. The placement matters: not every guardrail runs at every step.

That means you still need to design where the risk lives. If the risk is inside every tool call, use tool-level checks and approval gates, not only a final output check.

Current docs beat remembered snippets

SDK surfaces move faster than architecture. Before teaching install commands, class names, or guardrail signatures in a provider-specific quest, check the current official docs. This lesson gives the architecture and a current Python shape; a dedicated SDK quest should re-verify immediately before publish.

Code

Current Python Agents SDK shape·python

import asyncio
from agents import Agent, Runner, function_tool

@function_tool
def get_order_status(order_id: str) -> str:
    """Look up one order by public order id."""
    return "shipped"

agent = Agent(
    name="Order assistant",
    instructions="Help users with order status. Use tools for order facts.",
    model="gpt-5.5",
    tools=[get_order_status],
)

async def main() -> None:
    result = await Runner.run(agent, "Where is ORD-1042?")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

Risk placement checklist·text

Input risk?        input guardrail before the run does expensive work
Tool side effect?  executor permission + human approval gate
Final answer risk? output guardrail or reviewer pass
Debugging risk?    tracing + replayable run state
Regression risk?   eval dataset from real failures

OpenAI Agents SDK: Agents, Tools, Handoffs, Guardrails

Small primitives, serious workflows

Guardrails are boundary checks

Current docs beat remembered snippets

Code

External links

Exercise

Progress

Comments 0