Orchestrating AI: An Introduction to the OpenAI Agents SDK

Project Description

The OpenAI Agents SDK is a Python framework designed for building multi-agent workflows. It is provider-agnostic, supporting OpenAI Responses and Chat Completions APIs, as well as over 100 other Large Language Models (LLMs). The SDK emphasizes lightweight design and powerful capabilities for orchestrating interactions between multiple agents.

Key Concepts: - Agents: LLMs configured with specific instructions, tools, guardrails, and handoffs. - Handoffs: A specialized tool call used to transfer control between different agents. - Guardrails: Configurable safety checks for validating input and output. - Tracing: Built-in functionality for tracking, debugging, and optimizing agent runs.

Usage Instructions

1. Set up your Python environment:

python -m venv env
source env/bin/activate

2. Install Agents SDK:

pip install openai-agents

pip install 'openai-agents[voice]'

3. Hello World Example: To run a basic agent:

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)

4. Handoffs Example: To demonstrate agent handoffs based on language:

from agents import Agent, Runner
import asyncio

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="Handoff to the appropriate agent based on the language of the request.",
    handoffs=[spanish_agent, english_agent],
)

async def main():
    result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?")
    print(result.final_output)

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

5. Functions Example: To integrate custom functions as tools for agents:

import asyncio
from agents import Agent, Runner, function_tool

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

agent = Agent(
    name="Hello world",
    instructions="You are a helpful agent.",
    tools=[get_weather],
)

async def main():
    result = await Runner.run(agent, input="What's the weather in Tokyo?")
    print(result.final_output)

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

Development (for contributing to the SDK): 1. Ensure uv is installed. 2. Install dependencies: make sync 3. Lint/test: make tests, make mypy, make lint

Key Features

• Multi-Agent Workflows: Framework for building complex interactions between multiple LLM agents.
• Provider-Agnostic: Supports OpenAI APIs and over 100 other LLMs.
• Agent Configuration: Agents can be configured with instructions, tools, guardrails, and handoffs.
• Handoff Mechanism: Specialized tool calls for seamless control transfer between agents.
• Guardrails: Implement configurable safety checks for input and output validation.
• Built-in Tracing: Automatic tracking and debugging of agent runs, with extensibility for custom spans and external destinations (e.g., Logfire, AgentOps, Braintrust).
• Structured Outputs: Supports defining output_type for agents to produce structured final outputs.
• Flexible Agent Loop: Runs until a final output is produced, handling tool calls and handoffs iteratively, with a max_turns parameter for control.
• Tool Integration: Allows agents to use custom functions as tools.

Target Users

• Developers building multi-agent AI applications.
• Researchers and practitioners working with LLMs and AI workflows.
• Users who need to orchestrate complex tasks involving multiple AI agents.

Project Links

• GitHub Repository: https://github.com/openai/openai-agents-python
• Documentation: openai.github.io/openai-agents-python/

Application Scenarios

• Complex Information Extraction and Processing: Agents can collaboratively extract, process, and summarize information from diverse sources.
• Automated Customer Service: A triage agent can route queries to specialized agents, or agents can handle different stages of customer interaction (e.g., initial greeting, problem diagnosis, solution proposal).
• Code Generation and Debugging: Agents can be specialized for different programming languages or debugging tasks, with handoffs occurring as needed.
• Content Creation Workflows: Agents can collaborate on drafting, editing, and refining creative content, with guardrails ensuring adherence to style guides or safety protocols.
• Data Analysis and Reporting: Agents can be assigned roles for data retrieval, analysis, visualization, and report generation.
• Interactive Tutorials and Learning Environments: Agents can guide users through steps, provide feedback, and adapt their responses based on user input or progress.