OpenAI Agents SDK

The OpenAI Agents SDK represents a new paradigm in building AI-powered autonomous applications. By providing a suite of primitives—agents, tools, context management, output types, handoffs, streaming, tracing, and guardrails—this framework empowers developers to create systems where a large language model (LLM) not only converses but also acts on real-world data, interacts with APIs, and collaborates with other specialized agents.

For the official announcement and more details, refer to OpenAI’s update and the Agents SDK Guide.

Core Concepts of the Agents SDK

At its heart, the Agents SDK is designed around several key components:

• Agent: An LLM paired with specific instructions, available tools, handoffs, and optional guardrails.
• Tool: A function the agent can call to perform external tasks (e.g., API queries, computations).
• Context: A mutable object passed along to maintain state or shared resources across multiple steps.
• Output Types: Allows agents to produce either free-form text or structured outputs using defined schemas.
• Handoffs: Mechanisms for delegating tasks to specialized sub-agents, ensuring language or domain-specific expertise.
• Streaming & Tracing: Support for incremental output and detailed logging of every agentic step for debugging or analytics.
• Guardrails: Policy checks and validations that prevent unintended behavior and ensure data integrity.

These components work together to create multi-step, conversational workflows where an agent can intelligently plan, execute, and refine its actions.

The Agent Loop in Action

When you invoke an agent, the SDK initiates an agent loop. Here’s what happens under the hood:

1. Context Setup: The agent is provided with the full conversation context, including prior messages and any system instructions.
2. Decision Making: Based on the current context, the LLM either produces a final answer, calls a tool, or hands off the conversation to another agent.
3. Iteration: If a tool is called, the result is reintroduced into the conversation, and the loop continues until a final message or handoff is completed.

This loop ensures that each step is informed by both historical context and real-time data, making the agent’s outputs more reliable and context-aware.

Practical Code Examples

1. Creating a Basic Agent

Below is a simple example that demonstrates how to create and run a basic agent:

from agents import Agent, AgentRunner

agent = Agent(
    name="basic_agent",
    instructions="You are a helpful agent."
)

result = await AgentRunner.run(agent, ["What's the capital of the USA?"])
print(result.agent_output)
# Expected Output: The capital of the United States is Washington, D.C.

2. Defining and Using Tools

Tools extend an agent’s functionality by allowing it to call external functions. Here’s how to define a weather retrieval tool and attach it to an agent:

from agents.tool import function_tool

@function_tool
def get_weather(location: str, unit: str = "C") -> str:
    """
    Fetch the weather for a given location, returning a brief description.
    """
    # Example logic for weather retrieval
    return f"The weather in {location} is 22 degrees {unit}."

# Attaching the tool to an agent
from agents import Agent

agent.tools.append(get_weather)

3. Leveraging Context for State Management

Maintaining state across multiple interactions is key for complex workflows. The following snippet shows how to use a custom context with an agent:

from agents.run_context import AgentContextWrapper
from agents.tool import function_tool

class MyContext:
    def __init__(self, user_id: str):
        self.user_id = user_id
        self.seen_messages = []

@function_tool
def greet_user(context: AgentContextWrapper[MyContext], greeting: str) -> str:
    user_id = context.agent_context.user_id
    return f"Hello {user_id}, you said: {greeting}"

agent = Agent(
    name="my_agent_with_context",
    context_type=MyContext,
    tools=[greet_user],
)

my_ctx = MyContext(user_id="alice")
result = await AgentRunner.run(
    agent,
    input=["Hi agent!"],
    context=my_ctx,
)
print(result.agent_output)
# Expected Output: A greeting that includes the user's id.

4. Structured Output with Pydantic

For applications requiring structured results, you can enforce JSON outputs that conform to a specific schema:

from pydantic import BaseModel
from agents import Agent, AgentRunner

class WeatherAnswer(BaseModel):
    location: str
    temperature_c: float
    summary: str

agent = Agent(
    name="StructuredWeatherAgent",
    instructions="Use the final_output tool with WeatherAnswer schema.",
    output_type=WeatherAnswer,
)

out = await AgentRunner.run(agent, ["What's the temperature in Paris?"])
print(out.agent_output)
# Expected Output: An instance of WeatherAnswer with structured weather data.

5. Multi-Agent Workflow with Handoffs

Agents can delegate tasks to specialized sub-agents. This example shows how to set up handoffs based on language detection:

from agents import Agent, AgentRunner, handoff
from agents.tool import function_tool
from pydantic import BaseModel

class StructuredAnswer(BaseModel):
    decision: str
    reasoning: str

@function_tool
def get_forecast(city: str) -> str:
    return f"The forecast in {city} is sunny."

spanish_agent = Agent(name="spanish_agent", instructions="You only speak Spanish.")
english_agent = Agent(name="english_agent", instructions="You only speak English.")

triage_agent = Agent(
    name="triage_agent",
    instructions="Switch to Spanish if the user speaks Spanish, otherwise use English.",
    tools=[get_forecast],
    handoffs=[handoff(spanish_agent), handoff(english_agent)],
    output_type=StructuredAnswer,
)

output = await AgentRunner.run(triage_agent, ["Hola, ¿qué tiempo hace en Madrid?"])
print(output.agent_output)
# Expected Output: A StructuredAnswer indicating that the Spanish agent handled the request.

Best Practices for Using the Agents SDK

• Document Your Tools: Clearly define function schemas so that the LLM understands when and how to call each tool.
• Strict Schema Enforcement: Utilize structured outputs (e.g., via Pydantic models) to ensure data integrity.
• Robust Guardrails: Implement guardrails to enforce content policies or validate data at each step.
• Trace and Debug: Leverage the built-in tracing capabilities to record each step of the agent’s workflow, which is invaluable for debugging complex interactions.
• Utilize Handoffs: For multi-domain applications, use handoffs to delegate tasks to specialized agents.

Conclusion

The OpenAI Agents SDK provides a comprehensive framework to build autonomous, intelligent agents that can interact with external tools and maintain contextual awareness over multi-step workflows. Whether you’re building a customer service bot, a research assistant, or an enterprise automation solution, the SDK’s modular design and extensive feature set offer a robust foundation for developing cutting-edge AI applications.

As the capabilities of LLMs continue to expand, frameworks like the Agents SDK will be instrumental in bridging the gap between raw AI potential and practical, real-world applications.

Citations:

1. OpenAI. (2025). New Tools for Building Agents. Retrieved from OpenAI
2. OpenAI. (2025). Agents SDK. Retrieved from OpenAI Platform