Tutorial do OpenAI Agents SDK: criando sistemas de IA que agem

Pré-requisitos para trabalhar com o OpenAI Agents SDK

Antes de mergulhar no OpenAI Agents SDK, é importante entender alguns conceitos fundamentais e configurar corretamente seu ambiente. Esta seção cobre tudo o que você precisa saber antes de escrever seu primeiro agente.

Conhecimentos necessários

Para aproveitar ao máximo este tutorial, é ideal que você tenha familiaridade com:

• Programação intermediária em Python: compreensão de funções, classes, padrões async/await e type hints
• Uso básico da API da OpenAI: enviar requisições para modelos da OpenAI e tratar respostas
• Modelos de linguagem (LLMs): entendimento conceitual de como LLMs funcionam e suas capacidades/limitações
• Pydantic: noções de uso do Pydantic para validação de dados serão úteis, já que o Agents SDK o utiliza amplamente
• Programação assíncrona: familiaridade com padrões async/await em Python, pois o Agents SDK é baseado em execução assíncrona

Se você precisa reforçar algum desses tópicos, a DataCamp oferece ótimos recursos:

• Working with the OpenAI API — aprenda os fundamentos de como interagir com os modelos da OpenAI.
• OpenAI Fundamentals Track — uma trilha de aprendizado completa sobre as tecnologias OpenAI.
• Visão geral do GPT-4.5 — conheça as funcionalidades mais recentes dos modelos GPT.
• Function calling com GPT-4.5 — base essencial para entender o uso de ferramentas em agentes.
• Usando a API do GPT-4.5 — guia prático para trabalhar com modelos avançados.

Conceitos-chave para agentes

Antes de começar a codar, vamos esclarecer alguns conceitos centrais do Agents SDK:

1. Agents: sistemas de IA que usam ferramentas e tomam decisões para cumprir tarefas
2. Tools: funções que os agentes chamam para executar ações como buscar na web ou acessar bancos de dados
3. Handoffs: mecanismos para transferir o controle entre agentes especializados
4. Guardrails: medidas de segurança que validam entradas e saídas para garantir comportamento adequado

Entender esses conceitos e suas relações ajuda você a construir aplicações de agentes mais eficazes. Saiba mais no nosso guia sobre entendendo agentes de IA. 

Configuração do ambiente do OpenAI Agents

Vamos preparar o ambiente de desenvolvimento com tudo o que é necessário para trabalhar com o OpenAI Agents SDK:

Instalando os pacotes necessários

Primeiro, crie e ative um ambiente virtual:

# Create and activate a virtual environment (run in your terminal)
python -m venv agents-env
source agents-env/bin/activate  # On Windows: agents-env\Scripts\activate

Em seguida, instale o OpenAI Agents SDK e o python-dotenv:

pip install openai-agents python-dotenv

Usando python-dotenv para gerenciar a chave de API

Ao trabalhar com chaves de API, é uma boa prática mantê-las fora do seu código. O pacote python-dotenv oferece uma forma segura de gerenciar variáveis de ambiente:

1. Crie um arquivo chamado .env na pasta do projeto
2. Adicione sua chave de API da OpenAI nesse arquivo:

OPENAI_API_KEY=your-api-key-here

3. Carregue e use as variáveis de ambiente no seu código:

import os
from dotenv import load_dotenv
from agents import Agent, Runner

# Load environment variables from .env file
load_dotenv()

# Access your API key
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
   raise ValueError("OPENAI_API_KEY not found in .env file")

Essa abordagem mantém informações sensíveis fora do código — algo especialmente importante se você vai compartilhar ou publicar seu trabalho.

Trabalhando com funções assíncronas

O OpenAI Agents SDK faz uso extensivo de programação assíncrona. Veja como trabalhar com funções async em diferentes ambientes:

Em scripts Python (arquivos .py)

Em scripts Python comuns, você precisa usar asyncio.run() para executar funções assíncronas:

import asyncio
from agents import Agent, Runner

async def main():
   agent = Agent(
       name="Test Agent",
       instructions="You are a helpful assistant that provides concise responses."
   )
   result = await Runner.run(agent, "Hello! Are you working correctly?")
   print(result.final_output)

if __name__ == "__main__":
   asyncio.run(main())  # Run the async function

Em notebooks Jupyter

Notebooks Jupyter já possuem um event loop em execução, então você NÃO deve usar asyncio.run(). Em vez disso, aguarde as funções async diretamente:

from agents import Agent, Runner

# No need for asyncio.run() in notebooks
agent = Agent(
   name="Test Agent",
   instructions="You are a helpful assistant that provides concise responses."
)
result = await Runner.run(agent, "Hello! Are you working correctly?")
print(result.final_output)

Se você tentar usar asyncio.run() em um notebook, vai se deparar com erros como:

RuntimeError: asyncio.run() cannot be called from a running event loop

Esse é um dos ajustes mais comuns ao copiar código entre scripts e notebooks. Ao longo deste tutorial, vou usar principalmente a sintaxe compatível com notebooks, já que a maioria dos leitores utilizará o Jupyter.

Testando sua instalação

Vamos confirmar se tudo está configurado corretamente:

from agents import Agent, Runner
from dotenv import load_dotenv

load_dotenv()

# For Jupyter notebooks:
agent = Agent(
   name="Test Agent",
   instructions="You are a helpful assistant that provides concise responses."
)
result = await Runner.run(agent, "Hello! Are you working correctly?")
print(result.final_output)

# For Python scripts, you'd use:
# async def test_installation():
#     agent = Agent(
#         name="Test Agent",
#         instructions="You are a helpful assistant that provides concise responses."
#     )
#     result = await Runner.run(agent, "Hello! Are you working correctly?")
#     print(result.final_output)
#
# if __name__ == "__main__":
#     asyncio.run(test_installation())

# Hello! Yes, I'm here and ready to help. How can I assist you today?

Com essa configuração concluída, você já pode começar a criar aplicações com o OpenAI Agents SDK.

Primeiros passos com o OpenAI Agents SDK

No coração do OpenAI Agents SDK está a classe Agent, sua principal interface para criar sistemas de IA que entendem e executam instruções. Vamos ver como criar e configurar agentes para diferentes cenários.

Um agente neste SDK representa um sistema de IA capaz de seguir instruções e, opcionalmente, usar ferramentas para concluir tarefas. Criar um agente básico exige apenas alguns parâmetros essenciais:

from agents import Agent

basic_agent = Agent(
   name="My First Agent",
   instructions="You are a helpful assistant that provides factual information.",
   model="gpt-4o"  # Optional: defaults to "gpt-4o" if not specified
)

Os três componentes principais de um agente são:

1. Nome: um identificador do seu agente que ajuda em logs e depuração
2. Instruções: o “system prompt” que define o comportamento e o propósito do agente
3. Modelo: o modelo de linguagem subjacente que alimenta o agente (padrão GPT-4o)

Embora essa configuração básica já funcione, a classe Agent oferece opções adicionais de configuração do modelo para dar mais controle sobre o comportamento do LLM:

from agents import ModelSettings


advanced_agent = Agent(
   name="Advanced Assistant",
   instructions="""You are a professional, concise assistant who always provides
   accurate information. When you don't know something, clearly state that.
   Focus on giving actionable insights when answering questions.""",
   model="gpt-4o",
   model_settings=ModelSettings(
       temperature=0.3,  # Lower for more deterministic outputs (0.0-2.0)
       max_tokens=1024,  # Maximum length of response
   ),
   tools=[]  # We'll cover tools in a later section
)

Instruções e configuração

O parâmetro instructions é talvez o aspecto mais importante do design do agente. Ele funciona como um “system prompt” que orienta o comportamento, o tom e as capacidades do agente. Escrever boas instruções é parte ciência, parte arte:

Boas práticas para escrever instruções

1. Seja específico: defina claramente o papel, a personalidade e as limitações do agente
2. Defina limites: explicite temas ou ações que o agente deve evitar
3. Descreva padrões de interação: explique como o agente deve lidar com diferentes tipos de entrada
4. Delimite o conhecimento: deixe claro o que o agente deve saber e quando deve assumir incerteza

O Agent também inclui um parâmetro description, uma descrição legível por humanos, usada quando o agente é empregado dentro de ferramentas/handoffs.

Opções de configuração

Além das instruções, você pode ajustar o comportamento do agente com vários parâmetros de configuração:

• temperature: controla a aleatoriedade das respostas (0,0–2,0)
• Valores menores (0,1–0,4) geram respostas mais determinísticas e focadas
• Valores maiores (0,7–1,0) geram saídas mais criativas e variadas
• max_tokens: limita o comprimento das respostas do agente
• Útil para garantir concisão ou controlar custos
• O padrão varia por modelo, mas geralmente é alto o suficiente para a maioria dos casos
• model: seleciona o LLM subjacente
• “gpt-4o” oferece o melhor desempenho para a maioria dos casos
• “gpt-4o-mini” equilibra bem desempenho e custo
• “gpt-3.5-turbo” é indicado para tarefas menos complexas, priorizando velocidade e custo

Essas opções formam uma base poderosa para personalizar o comportamento do agente conforme a aplicação. Recomendamos experimentar diferentes ajustes para entender seu impacto e encontrar a configuração ideal para o seu caso.

Exemplo com OpenAI Agents SDK: construindo um assistente de clima especializado

Agora, vamos unir esses conceitos criando um exemplo prático: um assistente especializado em informações meteorológicas. Ele demonstra como criar um agente com expertise, capacidades e limitações bem definidas:

from agents import Agent, Runner
from dotenv import load_dotenv

# Load environment variables (API key)
load_dotenv()

# Define detailed instructions for our weather assistant
weather_instructions = """
You are a weather information assistant who helps users understand weather patterns and phenomena.

YOUR EXPERTISE:
- Explaining weather concepts and terminology
- Describing how different weather systems work
- Answering questions about climate and seasonal patterns
- Explaining the science behind weather events

LIMITATIONS:
- You cannot provide real-time weather forecasts for specific locations
- You don't have access to current weather data
- You should not make predictions about future weather events

STYLE:
- Use clear, accessible language that non-meteorologists can understand
- Include interesting weather facts when relevant
- Be enthusiastic about meteorology and climate science
"""

# Create our specialized weather assistant
weather_assistant = Agent(
   name="WeatherWise",
   instructions=weather_instructions,
   model="gpt-3.5-turbo",
   model_settings=ModelSettings(
       temperature=0.5,  # Balanced temperature for natural but focused responses
       max_tokens=256,  # Maximum length of response
   )
)

Executando seu primeiro agente

Depois de criar um agente, você pode executá-lo com a classe Runner, que lida com a execução de tarefas e o fluxo da conversa:

# For Jupyter notebooks:
result = await Runner.run(
   weather_assistant, "Can you tell me about the relationship between climate change and extreme weather events?"
)

print(result.final_output)

—--------

Absolutely! Climate change is closely linked to the increase in frequency and intensity of extreme weather events. As the Earth's climate warms due to the buildup of greenhouse gases in the atmosphere, it disrupts the balance of our planet's climate systems.

Here's how climate change influences extreme weather events:
1. **Heatwaves**: Rising global temperatures lead to more frequent and severe heatwaves. These events can have serious impacts on human health, agriculture, and ecosystems.

2. **Intense Storms**: Warmer oceans provide more energy to fuel hurricanes, typhoons, and other tropical storms, leading to stronger and more destructive events.

3. **Heavy Rainfall**: A warmer atmosphere can hold more moisture, resulting in heavier rainfall during storms. This can lead to flooding and landslides.

4. **Droughts**: Climate change can exacerbate drought conditions in certain regions, impacting water resources, agriculture, and ecosystems.

5. **Wildfires**: Higher temperatures and drier conditions increase the likelihood of wildfires, which can be more frequent and intense.

It's important to note that while climate change doesn't directly cause specific weather events, it can increase the likelihood and severity of extreme weather occurrences. Scientists continue to study these connections to better understand and prepare for the impacts of

Em scripts Python, você precisará usar a abordagem com asyncio:

# For Python scripts:
import asyncio

async def run_agent_example():
   result = await Runner.run(weather_assistant, "Can you tell me about the relationship between climate change and extreme weather events?")
   print(result.final_output)

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

Nesta seção, vimos o básico de como criar e executar agentes com o OpenAI Agents SDK. Na próxima, vamos potencializar esses agentes adicionando ferramentas — o que amplia bastante suas capacidades.

Trabalhando com ferramentas

O poder real do OpenAI Agents SDK aparece quando você equipa seus agentes com ferramentas. Elas permitem interagir com sistemas externos, acessar dados e executar ações além da simples geração de texto. O SDK suporta três tipos principais: hosted tools, function tools e agentes como ferramentas.

Hosted tools

Hosted tools rodam nos servidores da OpenAI, junto aos modelos de linguagem. Elas oferecem capacidades nativas sem exigir que você implemente funcionalidades complexas.

WebSearchTool: construindo um assistente de pesquisa

A WebSearchTool dá ao seu agente a habilidade de pesquisar na web por informações atualizadas. É especialmente útil para tarefas que exigem conhecimento recente, além dos dados de treino do modelo.

from agents import Agent, Runner, WebSearchTool
from dotenv import load_dotenv

load_dotenv()

# Create a research assistant with web search capability
research_assistant = Agent(
   name="Research Assistant",
   instructions="""You are a research assistant that helps users find and summarize information.
   When asked about a topic:
   1. Search the web for relevant, up-to-date information
   2. Synthesize the information into a clear, concise summary
   3. Structure your response with headings and bullet points when appropriate
   4. Always cite your sources at the end of your response
  
   If the information might be time-sensitive or rapidly changing, mention when the search was performed.
   """,
   tools=[WebSearchTool()]
)

async def research_topic(topic):
   result = await Runner.run(research_assistant, f"Please research and summarize: {topic}. Only return the found links with very minimal text.")
   return result.final_output

# Usage example (in Jupyter notebook)
summary = await research_topic("Latest developments in personal productivity apps.")
print(summary[:512])

—----------------

Here are some recent developments in personal productivity apps:

- **AI Integration in Productivity Tools**: Startups like Anthropic are developing AI agents capable of performing routine tasks across different applications, aiming to streamline workflows and reduce the need for multiple apps. ([ft.com](https://www.ft.com/content/a0e54dd5-b270-42cc-8c4c-18a0b8b3e6cc?utm_source=openai))

- **Read AI's Expansion**: Read AI, a productivity startup, secured $50 million in funding, valuing the company at $450 m

Neste exemplo, criamos um assistente de pesquisa que busca na web e sintetiza as informações em um resumo coerente. A WebSearchTool não precisa de parâmetros para funcionar, mas você pode personalizá-la:

# Customized search tool with location context
location_aware_search = WebSearchTool(
   user_location="San Francisco, CA",  # Provides geographic context for local search queries
   search_context_size=3  # Number of search results to consider in the response
)

O parâmetro user_location é útil para consultas que se beneficiam de contexto geográfico, como serviços locais ou informações regionais. O search_context_size controla quantos resultados o modelo considera ao formular a resposta.

Function tools

Function tools permitem estender seu agente com qualquer função Python. Aqui está a flexibilidade real do Agents SDK, viabilizando integração com qualquer API, banco de dados ou serviço local.

Ferramenta de previsão do tempo

Vamos criar um exemplo prático que integra uma API de clima de terceiros:

import os
import requests
from datetime import datetime
from typing import Optional, List
from dataclasses import dataclass

from agents import Agent, Runner, function_tool
from dotenv import load_dotenv

load_dotenv()


@dataclass
class WeatherInfo:
   temperature: float
   feels_like: float
   humidity: int
   description: str
   wind_speed: float
   pressure: int
   location_name: str
   rain_1h: Optional[float] = None
   visibility: Optional[int] = None


@function_tool
def get_weather(lat: float, lon: float) -> str:
   """Get the current weather for a specified location using OpenWeatherMap API.

   Args:
       lat: Latitude of the location (-90 to 90)
       lon: Longitude of the location (-180 to 180)
   """
   # Get API key from environment variables
   WEATHER_API_KEY = os.getenv("OPENWEATHERMAP_API_KEY")

   # Build URL with parameters
   url = f"https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={WEATHER_API_KEY}&units=metric"

   try:
       response = requests.get(url)
       response.raise_for_status()
       data = response.json()

       # Extract weather data from the response
       weather_info = WeatherInfo(
           temperature=data["main"]["temp"],
           feels_like=data["main"]["feels_like"],
           humidity=data["main"]["humidity"],
           description=data["weather"][0]["description"],
           wind_speed=data["wind"]["speed"],
           pressure=data["main"]["pressure"],
           location_name=data["name"],
           visibility=data.get("visibility"),
           rain_1h=data.get("rain", {}).get("1h"),
       )

       # Build the response string
       weather_report = f"""
       Weather in {weather_info.location_name}:
       - Temperature: {weather_info.temperature}°C (feels like {weather_info.feels_like}°C)
       - Conditions: {weather_info.description}
       - Humidity: {weather_info.humidity}%
       - Wind speed: {weather_info.wind_speed} m/s
       - Pressure: {weather_info.pressure} hPa
       """
       return weather_report

   except requests.exceptions.RequestException as e:
       return f"Error fetching weather data: {str(e)}"

Essa function tool de clima faz a ponte entre a API OpenWeatherMap e nosso agente. Ela busca dados meteorológicos em tempo real por coordenadas geográficas e formata um relatório legível.

O código define uma classe de dados WeatherInfo para estruturar as informações com campos tipados (temperatura, umidade etc.), deixando tudo organizado e fácil de manter. O decorador @function_tool transforma a função Python em uma ferramenta que o agente pode usar, criando automaticamente um esquema a partir da assinatura e da docstring.

Quando chamada, a função obtém com segurança a chave de API das variáveis de ambiente, faz a requisição HTTP ao OpenWeatherMap e processa a resposta JSON. 

Ela trata campos opcionais, como chuva, com segurança e formata tudo em um relatório claro, incluindo tratamento de erros caso a requisição falhe. Assim, nosso agente fornece informações atuais de clima em um formato consistente e humano, sem precisar conhecer detalhes da API.

# Create a weather assistant
weather_assistant = Agent(
   name="Weather Assistant",
   instructions="""You are a weather assistant that can provide current weather information.
  
   When asked about weather, use the get_weather tool to fetch accurate data.
   If the user doesn't specify a country code and there might be ambiguity,
   ask for clarification (e.g., Paris, France vs. Paris, Texas).
  
   Provide friendly commentary along with the weather data, such as clothing suggestions
   or activity recommendations based on the conditions.
   """,
   tools=[get_weather]
)

Para executar o assistente de clima:

async def main():
   runner = Runner()
  
   simple_request = await runner.run(weather_assistant, "What are your capabilities?")
  
   request_with_location = await runner.run(weather_assistant, "What's the weather like in Tashkent right now?")
  
   print(simple_request.final_output)
   print("-"*70)
   print(request_with_location.final_output)

await main()

Output:

I can provide you with the current weather conditions for any location around the world. Just give me the location details, and I'll fetch the weather data for you. I can also offer tips on activities or clothing based on the weather. If you have a specific city in mind, let me know, and I'll get to work!
----------------------------------------------------------------------
The weather in Tashkent is currently lovely with a clear sky. It's around 19.8°C, but it might feel slightly cooler at 18.6°C. The humidity is quite low at 26%, making it a pleasant day to be outdoors. A gentle breeze is blowing at 3.09 m/s, and the air pressure is steady at 1023 hPa.

It's a great time for a picnic in the park or a leisurely walk. Light clothing should be perfect for this weather. Enjoy your day in Tashkent!

A resposta prova que o agente usou a ferramenta de clima com sucesso. Ele isolou o nome da cidade do prompt, usou seu próprio conhecimento para obter as coordenadas e as passou como lat e lon para a ferramenta.

Agentes como ferramentas

O Agents SDK permite usar os próprios agentes como ferramentas, criando uma estrutura hierárquica em que especialistas trabalham sob a coordenação de um orquestrador. Esse padrão é poderoso para fluxos de trabalho complexos.

from agents import Agent, Runner
from dotenv import load_dotenv

load_dotenv()

# Specialist agents
note_taking_agent = Agent(
   name="Note Manager",
   instructions="You help users take and organize notes efficiently.",
   # In a real application, this agent would have note-taking tools
)

task_management_agent = Agent(
   name="Task Manager",
   instructions="You help users manage tasks, deadlines, and priorities.",
   # In a real application, this agent would have task management tools
)

# Coordinator agent that uses specialists as tools
productivity_assistant = Agent(
   name="Productivity Assistant",
   instructions="""You are a productivity assistant that helps users organize their work and personal life.
  
   For note-taking questions or requests, use the note_taking tool.
   For task and deadline management, use the task_management tool.
  
   Help the user decide which tool is appropriate based on their request,
   and coordinate between different aspects of productivity.
   """,
   tools=[
       note_taking_agent.as_tool(
           tool_name="note_taking",
           tool_description="For taking, organizing, and retrieving notes and information"
       ),
       task_management_agent.as_tool(
           tool_name="task_management",
           tool_description="For managing tasks, setting deadlines, and tracking priorities"
       )
   ]
)

Neste exemplo:

1. Criamos dois agentes especialistas, cada um com um domínio de atuação.
2. Depois, criamos um agente coordenador que pode delegar a esses especialistas.
3. Convertimos cada especialista em ferramenta com o método .as_tool(), especificando:

• Um tool_name para o coordenador referenciar a ferramenta.
• Uma tool_description que ajuda o coordenador a decidir quando usar a ferramenta.

Esse padrão permite criar sistemas complexos mantendo a separação de responsabilidades. Cada agente especialista pode ter seu próprio conjunto de ferramentas e expertise, enquanto o coordenador gerencia a interação com o usuário e delega ao especialista adequado.

Para usar o assistente de produtividade:

async def main():
   runner = Runner()
  
   result = await runner.run(productivity_assistant, "I need to keep track of my project deadlines")
   print(result.final_output)

await main()

As ferramentas transformam agentes de simples assistentes conversacionais em sistemas capazes de tomar ações concretas no mundo. Embora tenhamos coberto o básico, isso é só o começo do que é possível. Para usos mais avançados, incluindo tratamento de erros em function tools, consulte a documentação oficial.

Agora que entendemos como equipar nossos agentes com ferramentas, o próximo desafio é lidar com suas saídas. A seguir, vamos ver técnicas para processar respostas — de textos básicos a dados estruturados complexos — garantindo o formato exato que sua aplicação precisa.

Entendendo as saídas dos agentes OpenAI

Ao trabalhar com agentes, receber informações estruturadas em vez de texto livre pode tornar suas aplicações mais confiáveis. O OpenAI Agents SDK oferece um modo simples e nativo de obter saídas estruturadas diretamente dos agentes.

Saídas estruturadas com modelos Pydantic

O SDK permite definir exatamente a estrutura de dados que você quer que o agente retorne, informando o parâmetro output_type ao criar o agente:

from pydantic import BaseModel
from typing import List, Optional
from agents import Agent, Runner
from dotenv import load_dotenv

load_dotenv()
True
First, we define our data models using Pydantic:
# Define person data model
class Person(BaseModel):
   name: str
   role: Optional[str]
   contact: Optional[str]


# Define meeting data model
class Meeting(BaseModel):
   date: str
   time: str
   location: Optional[str]
   duration: Optional[str]


# Define task data model
class Task(BaseModel):
   description: str
   assignee: Optional[str]
   deadline: Optional[str]
   priority: Optional[str]


# Define the complete email data model
class EmailData(BaseModel):
   subject: str
   sender: Person
   recipients: List[Person]
   main_points: List[str]
   meetings: List[Meeting]
   tasks: List[Task]
   next_steps: Optional[str]

Esses modelos definem a estrutura dos dados que queremos extrair. Cada classe representa um tipo específico de informação a ser extraída de um e-mail.

Agora, criamos um agente que vai gerar dados no nosso formato estruturado configurando output_type:

# Create an email extraction agent with structured output
email_extractor = Agent(
   name="Email Extractor",
   instructions="""You are an assistant that extracts structured information from emails.
  
   When given an email, carefully identify:
   - Subject and main points
   - People mentioned (names, roles, contact info)
   - Meetings (dates, times, locations)
   - Tasks or action items (with assignees and deadlines)
   - Next steps or follow-ups
  
   Extract this information as structured data. If something is unclear or not mentioned,
   leave those fields empty rather than making assumptions.
   """,
   output_type=EmailData,  # This tells the agent to return data in EmailData format
)

Quando você especifica output_type, o agente passa a produzir dados estruturados em vez de texto livre. Isso elimina a necessidade de parse manual de JSON ou uso de regex.

Vamos usar o extrator com um e-mail de exemplo:

sample_email = """
From: Alex Johnson <alex.j@techcorp.com>
To: Team Development <team-dev@techcorp.com>
CC: Sarah Wong <sarah.w@techcorp.com>, Miguel Fernandez <miguel.f@techcorp.com>
Subject: Project Phoenix Update and Next Steps

Hi team,

I wanted to follow up on yesterday's discussion about Project Phoenix and outline our next steps.

Key points from our discussion:
- The beta testing phase has shown promising results with 85% positive feedback
- We're still facing some performance issues on mobile devices
- The client has requested additional features for the dashboard

Let's schedule a follow-up meeting this Friday, June 15th at 2:00 PM in Conference Room B. The meeting should last about 1.5 hours, and we'll need to prepare the updated project timeline.

Action items:
1. Sarah to address the mobile performance issues by June 20th (High priority)
2. Miguel to create mock-ups for the new dashboard features by next Monday
3. Everyone to review the beta testing feedback document and add comments by EOD tomorrow

If you have any questions before Friday's meeting, feel free to reach out.

Best regards,
Alex Johnson
Senior Project Manager
(555) 123-4567
"""

Com o SDK cuidando da conversão, processar o e-mail fica bem mais simples:

async def process_email(email_text):
   runner = Runner()
   result = await runner.run(
       email_extractor,
       f"Please extract information from this email:\n\n{email_text}"
   )

   # The result is already a structured EmailData object
   return result


# Process the sample email
result = await process_email(sample_email)

# Display the extracted information
result = result.final_output

print(f"Subject: {result.subject}")
print(f"From: {result.sender.name} ({result.sender.role})")
print("\nMain points:")
for point in result.main_points:
   print(f"- {point}")

print("\nMeetings:")
for meeting in result.meetings:
   print(f"- {meeting.date} at {meeting.time}, Location: {meeting.location}")

print("\nTasks:")
for task in result.tasks:
   print(f"- {task.description}")
   print(
       f"  Assignee: {task.assignee}, Deadline: {task.deadline}, Priority: {task.priority}"
   )
—----------

Subject: Project Phoenix Update and Next Steps
From: Alex Johnson (Senior Project Manager)

Main points:
- 85% positive feedback from beta testing
- Performance issues on mobile devices
- Client requested additional dashboard features

Meetings:
- June 15th at 2:00 PM, Location: Conference Room B

Tasks:
- Address mobile performance issues
 Assignee: Sarah, Deadline: June 20th, Priority: High
- Create mock-ups for new dashboard features
 Assignee: Miguel, Deadline: Next Monday, Priority: None
- Review beta testing feedback document and add comments
 Assignee: Everyone, Deadline: EOD tomorrow, Priority: None

Esse código fica muito mais limpo porque:

1. Não precisamos extrair e fazer parse de JSON manualmente.
2. O SDK converte a saída do agente para nosso modelo Pydantic.
3. Podemos acessar diretamente as propriedades dos dados estruturados (como result.final_output.subject).
4. A validação de tipos acontece automaticamente, garantindo aderência ao modelo.

Trabalhando com diferentes tipos de saída

O parâmetro output_type funciona com qualquer tipo que possa ser encapsulado em um TypeAdapter do Pydantic:

# For simple lists
agent_with_list_output = Agent(
   name="List Generator",
   instructions="Generate lists of items based on the user's request.",
   output_type=list[str],  # Returns a list of strings
)

# For dictionaries
agent_with_dict_output = Agent(
   name="Dictionary Generator",
   instructions="Create key-value pairs based on the input.",
   output_type=dict[
       str, int
   ],  # Returns a dictionary with string keys and integer values
)

# For simple primitive types
agent_with_bool_output = Agent(
   name="Decision Maker",
   instructions="Answer yes/no questions with True or False.",
   output_type=bool,  # Returns a boolean
)

Benefícios das saídas estruturadas

Usar o parâmetro output_type traz várias vantagens:

1. Integração direta: as saídas do agente já chegam como objetos Python.
2. Segurança de tipos: o SDK garante que as saídas seguem sua estrutura.
3. Código mais simples: dispensa parsing manual de JSON e tratamento extra de erros.
4. Melhor desempenho: a conversão é feita de forma eficiente pelo SDK.
5. Suporte da IDE: autocompletar para propriedades da saída estruturada.

Ao definir modelos de dados claros e usar output_type, seus agentes produzem exatamente as estruturas que sua aplicação precisa — integrando com fluidez e reduzindo a complexidade do código.

Na próxima seção, vamos explorar handoffs entre agentes, permitindo criar agentes especializados que trabalham juntos em tarefas complexas. Esses handoffs podem usar saídas estruturadas para transferir informações de forma consistente e com segurança de tipos.

Handoffs: delegando entre agentes

Em aplicações complexas, tarefas diferentes exigem áreas de expertise distintas. O OpenAI Agents SDK suporta “handoffs”, que permitem que um agente delegue o controle a outro agente especializado. Esse recurso é valioso em sistemas que lidam com solicitações diversas, como em atendimento ao cliente — onde agentes diferentes tratam cobranças, suporte técnico ou gestão de contas.

Criando handoffs básicos

De forma simples, handoffs conectam múltiplos agentes para que transfiram o controle quando apropriado. Vamos criar um sistema de atendimento com um agente de triagem que encaminha para especialistas:

from agents import Agent, handoff, Runner
from dotenv import load_dotenv

load_dotenv()

# Create specialist agents
billing_agent = Agent(
   name="Billing Agent",
   instructions="""You are a billing specialist who helps customers with payment issues.
   Focus on resolving billing inquiries, subscription changes, and refund requests.
   If asked about technical problems or account settings, explain that you specialize
   in billing and payment matters only.""",
)

technical_agent = Agent(
   name="Technical Agent",
   instructions="""You are a technical support specialist who helps with product issues.
   Assist users with troubleshooting, error messages, and how-to questions.
   Focus on resolving technical problems only.""",
)

# Create a triage agent that can hand off to specialists
triage_agent = Agent(
   name="Customer Service",
   instructions="""You are the initial customer service contact who helps direct
   customers to the right specialist.
  
   If the customer has billing or payment questions, hand off to the Billing Agent.
   If the customer has technical problems or how-to questions, hand off to the Technical Agent.
   For general inquiries or questions about products, you can answer directly.
  
   Always be polite and helpful, and ensure a smooth transition when handing off to specialists.""",
   handoffs=[billing_agent, technical_agent],  # Direct handoff to specialist agents
)

Neste exemplo, criamos um sistema com três agentes:

• Dois agentes especialistas com foco definido
• Um agente de triagem que delega para os especialistas

Repare que basta incluir os agentes especialistas no parâmetro handoffs do agente de triagem. O SDK cria automaticamente as ferramentas de handoff adequadas.

Vamos ver o sistema em ação:

async def handle_customer_request(request):
   runner = Runner()
   result = await runner.run(triage_agent, request)
   return result


# Example customer inquiries
billing_inquiry = (
   "I was charged twice for my subscription last month. Can I get a refund?"
)
technical_inquiry = (
   "The app keeps crashing when I try to upload photos. How can I fix this? Give me the shortest solution possible."
)
general_inquiry = "What are your business hours?"

# Process the different types of inquiries
billing_response = await handle_customer_request(billing_inquiry)
print(f"Billing inquiry response:\n{billing_response.final_output}\n")

technical_response = await handle_customer_request(technical_inquiry)
print(f"Technical inquiry response:\n{technical_response.final_output}\n")

general_response = await handle_customer_request(general_inquiry)
print(f"General inquiry response:\n{general_response.final_output}")

Quando o agente de triagem recebe uma pergunta de cobrança, ele reconhece que o Billing Agent é mais indicado e faz o handoff. Perguntas técnicas são encaminhadas ao agente técnico. Já questões gerais são respondidas diretamente. Veja a saída:

Billing inquiry response:
I can help with that. Could you please provide the transaction details or the date of the charges? This will help me locate the duplicate charge and process a refund for you.

Technical inquiry response:
Try these steps:

1. Restart the app.
2. Update to the latest app version.
3. Clear the app cache.
4. Restart your device.

If it persists, reinstall the app.

General inquiry response:
Our business hours are Monday to Friday, 9 AM to 5 PM. If you need assistance outside these hours, feel free to reach out and we'll get back to you as soon as possible. Is there anything else I can help you with?

Personalizando handoffs

Para mais controle, você pode usar a função handoff() em vez de passar agentes diretamente no parâmetro handoffs:

from agents import Agent, handoff, RunContextWrapper
from datetime import datetime

# Create an agent that handles account-related questions
account_agent = Agent(
   name="Account Management",
   instructions="""You help customers with account-related issues such as
   password resets, account settings, and profile updates.""",
)


# Custom handoff callback function
async def log_account_handoff(ctx: RunContextWrapper[None]):
   print(
       f"[LOG] Account handoff triggered at {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}"
   )
   # In a real app, you might log to a database or alert a human supervisor


# Create a triage agent with customized handoffs
enhanced_triage_agent = Agent(
   name="Enhanced Customer Service",
   instructions="""You are the initial customer service contact who directs
   customers to the right specialist.
  
   If the customer has billing or payment questions, hand off to the Billing Agent.
   If the customer has technical problems, hand off to the Technical Agent.
   If the customer needs to change account settings, hand off to the Account Management agent.
   For general inquiries, you can answer directly.""",
   handoffs=[
       billing_agent,  # Basic handoff
       handoff(  # Customized handoff
           agent=account_agent,
           on_handoff=log_account_handoff,  # Callback function
           tool_name_override="escalate_to_account_team",  # Custom tool name
           tool_description_override="Transfer the customer to the account management team for help with account settings, password resets, etc.",
       ),
       technical_agent,  # Basic handoff
   ],
)

result = await Runner.run(
   enhanced_triage_agent, "I need to change my password."
)

Saída:

[LOG] Account handoff triggered at 2025-03-16 17:45:48

A função handoff() permite:

• Especificar um callback personalizado com on_handoff
• Substituir o nome padrão da ferramenta (normalmente “transfer_to_[agent_name]”)
• Fornecer uma descrição personalizada para a ferramenta
• Configurar o tratamento da entrada (ver abaixo)

Passando dados durante handoffs

Às vezes, você quer que o primeiro agente forneça contexto adicional ao transferir para outro. O Agents SDK suporta isso por meio do parâmetro input_type:

from pydantic import BaseModel
from typing import Optional
from agents import Agent, handoff, RunContextWrapper


# Define the data structure to pass during handoff
class EscalationData(BaseModel):
   reason: str
   priority: Optional[str]
   customer_tier: Optional[str]


# Handoff callback that processes the escalation data
async def process_escalation(ctx: RunContextWrapper, input_data: EscalationData):
   print(f"[ESCALATION] Reason: {input_data.reason}")
   print(f"[ESCALATION] Priority: {input_data.priority}")
   print(f"[ESCALATION] Customer tier: {input_data.customer_tier}")

   # You might use this data to prioritize responses, alert human agents, etc.


# Create an escalation agent
escalation_agent = Agent(
   name="Escalation Agent",
   instructions="""You handle complex or sensitive customer issues that require
   special attention. Always address the customer's concerns with extra care and detail.""",
)

# Create a service agent that can escalate with context
service_agent = Agent(
   name="Service Agent",
   instructions="""You are a customer service agent who handles general inquiries.
  
   For complex issues, escalate to the Escalation Agent and provide:
   - The reason for escalation
   - Priority level (Low, Normal, High, Urgent)
   - Customer tier if mentioned (Standard, Premium, VIP)""",
   handoffs=[
       handoff(
           agent=escalation_agent,
           on_handoff=process_escalation,
           input_type=EscalationData,
       )
   ],
)

Com essa configuração, quando o service agent decidir fazer handoff para o escalation agent, ele fornecerá dados estruturados sobre o motivo da escalada. O sistema valida esses dados com o modelo EscalationData antes de passá-los ao callback process_escalation.

Quando usar handoffs vs. agente-como-ferramenta

O Agents SDK oferece duas formas de colaboração entre agentes: handoffs e usar agentes como ferramentas (como vimos na seção anterior). Quando usar cada uma:

Use handoffs quando:

• Você quer transferir completamente o controle para outro agente
• A conversa precisa continuar com um especialista
• Você está construindo um fluxo em que agentes diferentes cuidam de etapas distintas

Use agentes-como-ferramentas quando:

• O agente principal precisa consultar um especialista, mas manter o controle
• Você quer incorporar a resposta do especialista como parte de uma resposta maior
• Você está construindo um sistema hierárquico em que um coordenador delega subtarefas

As duas abordagens podem ser combinadas em sistemas sofisticados, com um agente principal que às vezes consulta especialistas (usando-os como ferramentas) e, em outras situações, transfere completamente o controle.

Handoffs são um mecanismo poderoso para construir sistemas de agentes complexos em que a responsabilidade transita entre especialistas. Ao desenhar sua arquitetura, considere qual abordagem se ajusta melhor ao seu caso para criar a melhor experiência.

Conclusão e próximos passos

Exploramos os componentes essenciais do OpenAI Agents SDK: da criação de agentes básicos à implementação de function tools e ao gerenciamento de handoffs entre especialistas. Vimos como saídas estruturadas com modelos Pydantic tornam as aplicações mais confiáveis e fáceis de manter, e como projetar sistemas de agentes capazes de lidar com tarefas complexas por meio de delegação e especialização.

Ainda assim, isso é só a superfície do que esse framework poderoso oferece. Para levar seus sistemas de agentes a outro nível, vale explorar tópicos como respostas em streaming para atualizações em tempo real, tracing e observabilidade para depuração, orquestração multiagente para workflows complexos, gestão de contexto para manter o estado da conversa e guardrails para garantir comportamento seguro e apropriado.

À medida que agentes de IA se tornam centrais nas aplicações modernas, as habilidades que você desenvolveu neste tutorial formam uma base sólida para criar sistemas de IA sofisticados. Continue sua jornada com recursos como o guia da DataCamp para aprender IA, e lembre-se de que projetar agentes eficazes é tanto arte quanto ciência — exige iteração, testes e um entendimento profundo das necessidades do usuário e das capacidades da IA.