Como Usar o SDK de Agentes da OpenAI?

O OpenAI Agents SDK é uma biblioteca Python projetada para simplificar o desenvolvimento de agentes de IA alimentados pelos modelos de linguagem da OpenAI. Ele fornece aos desenvolvedores ferramentas para criar agentes específicos para tarefas, integrar funcionalidades externas, gerenciar a delegação de tarefas entre agentes, impor validação de entrada/saída e monitorar fluxos de execução. Este guia oferece um passo a passo técnico detalhado sobre como instalar, configurar e utilizar o SDK de forma eficaz, assegurando um mínimo de 2000 palavras com foco em precisão e aplicação prática.

Introdução

O OpenAI Agents SDK fornece uma estrutura organizada para construir sistemas multiagentes, onde cada agente é projetado para realizar tarefas específicas. Esses agentes podem interagir com usuários, executar ações por meio de ferramentas integradas e colaborar passando tarefas para outros agentes. Os componentes principais do SDK incluem:

• Agentes: Instâncias de modelos de linguagem configuradas com instruções e funções específicas.
• Ferramentas: Funções ou serviços (por exemplo, busca na web, código Python personalizado) que ampliam as capacidades do agente.
• Delegação: Mecanismos que permitem que os agentes deleguem tarefas para outros agentes de forma suave.
• Limites: Camadas de validação para garantir que entradas e saídas atendam a critérios definidos.
• Rastreamento: Registros de execução para depuração e análise de desempenho.

Este guia é projetado para desenvolvedores com conhecimento básico de Python e interações com API, fornecendo explicações detalhadas, exemplos de código e melhores práticas para criar um recurso robusto e abrangente.

Instalação e Configuração

A configuração adequada é fundamental para utilizar o OpenAI Agents SDK de forma eficaz. Esta seção cobre pré-requisitos, configuração do ambiente, instalação e verificação.

Pré-requisitos

Antes de prosseguir, certifique-se do seguinte:

• Python 3.8+: Verifique sua versão do Python com python --version. Instale a partir de python.org, se necessário.

• Chave da API da OpenAI: Obtenha sua chave em platform.openai.com nas configurações da sua conta. Essa chave autentica as solicitações aos servidores da OpenAI.

Passo 1: Configurar um Ambiente Virtual

Um ambiente virtual isola as dependências do projeto, prevenindo conflitos com outros projetos Python. Para criar e ativar um:

• Linux/macOS:

python -m venv agents_env
source agents_env/bin/activate

• Windows:

python -m venv agents_env
agents_env\Scripts\activate

Uma vez ativado, seu prompt de terminal deve refletir o ambiente (por exemplo, (agents_env)). Este passo é uma melhor prática para desenvolvimento em Python, garantindo um espaço de trabalho limpo.

Passo 2: Instalar o SDK

Com o ambiente virtual ativo, instale o SDK usando pip:

pip install openai-agents

Esse comando busca a versão mais recente do SDK e suas dependências no PyPI. Para confirmar a instalação, execute:

pip show openai-agents-python

Isso exibe os metadados, incluindo o número da versão, confirmando que o pacote está instalado.

Passo 3: Configurar a Chave da API

O SDK requer uma chave da API da OpenAI para funcionar. Defina-a como uma variável de ambiente para evitar incorporá-la em seu código, o que aumenta a segurança:

• Linux/macOS:

export OPENAI_API_KEY='sua-chave-api'

• Windows:

set OPENAI_API_KEY='sua-chave-api'

Para tornar isso persistente entre sessões, adicione o comando ao seu arquivo de configuração do shell (por exemplo, .bashrc ou .zshrc em sistemas Unix). Alternativamente, você pode defini-lo programaticamente em Python, embora isso seja menos seguro:

import os
os.environ["OPENAI_API_KEY"] = "sua-chave-api"

Passo 4: Verificar a Instalação

Teste a configuração com um agente mínimo para garantir que tudo funcione:

from agents import Agent, Runner

agent = Agent(name="TestAgent", instructions="Return 'Configuração bem-sucedida'")
result = Runner.run_sync(agent, "Executar teste")
print(result.final_output)  # Saída esperada: "Configuração bem-sucedida"

Se isso imprimir "Configuração bem-sucedida", sua instalação está funcional. Problemas comuns incluem:

• Chave da API Inválida: Verifique a chave e certifique-se de que não há espaços extras ou erros de digitação.
• Erros de Rede: Verifique sua conexão com a internet e o status dos servidores da OpenAI.

Criando Agentes

Agentes são os blocos de construção fundamentais do SDK, cada um definido por um papel e comportamento únicos.

Inicialização do Agente

A classe Agent é usada para instanciar agentes. Os parâmetros principais incluem:

• name: Um identificador de string (por exemplo, "MathAgent").
• instructions: Uma string especificando o propósito do agente (por exemplo, "Resolver problemas matemáticos").
• model: O modelo da OpenAI a ser usado (padrão: gpt-4).
• temperature: Um float entre 0 e 1 controlando a aleatoriedade da saída (padrão: 0.7).

Exemplo: Agente Básico

Aqui está um agente simples para aritmética:

from agents import Agent, Runner

agent = Agent(
    name="MathAgent",
    instructions="Resolva expressões aritméticas."
)
result = Runner.run_sync(agent, "Calcule 10 * 2")
print(result.final_output)  # Saída: "20"

O método Runner.run_sync executa o agente de forma síncrona, retornando um objeto de resultado com o atributo final_output.

Configuração Avançada

Personalize os agentes para necessidades específicas ajustando parâmetros:

agent = Agent(
    name="CreativeWriter",
    instructions="Escreva uma história curta com base no prompt.",
    model="gpt-4",
    temperature=0.9
)
result = Runner.run_sync(agent, "Um robô em uma galáxia distante")
print(result.final_output)  # Saída: Uma história criativa

• Modelo: gpt-4 oferece raciocínio superior, enquanto gpt-3.5-turbo é mais rápido e barato para tarefas mais simples.
• Temperatura: Valores mais baixos (por exemplo, 0.2) geram saídas previsíveis; valores mais altos (por exemplo, 0.9) aumentam a criatividade.

Exemplo de Múltiplos Agentes

Crie agentes distintos para diferentes tarefas:

support_agent = Agent(
    name="SupportBot",
    instructions="Responda perguntas de suporte técnico."
)
code_agent = Agent(
    name="CodeHelper",
    instructions="Gere trechos de código Python."
)

support_result = Runner.run_sync(support_agent, "Como instalo o Python?")
code_result = Runner.run_sync(code_agent, "Escreva uma função para adicionar dois números")
print(support_result.final_output)  # Saída: Instruções de instalação
print(code_result.final_output)     # Saída: "def add(a, b): return a + b"

Isso demonstra a flexibilidade do SDK em lidar com papéis diversos.

Integrando Ferramentas

Ferramentas aprimoram os agentes, permitindo que realizem ações externas. O SDK suporta ferramentas hospedadas, ferramentas de função personalizadas e ferramentas baseadas em agentes.

Usando Ferramentas Hospedadas

Ferramentas hospedadas, como web_search, são pré-construídas e prontas para uso:

from agents import Agent, Runner, web_search

agent = Agent(
    name="ResearchAgent",
    instructions="Responda perguntas usando busca na web.",
    tools=[web_search]
)
result = Runner.run_sync(agent, "Qual é a capital da França?")
print(result.final_output)  # Saída: "A capital da França é Paris."

O agente invoca automaticamente web_search para buscar dados em tempo real.

Criando Ferramentas de Função Personalizadas

Defina ferramentas personalizadas com o decorador @function_tool. As ferramentas devem aceitar e retornar strings.

Exemplo: Ferramenta de Recuperação de Dados

from agents import Agent, Runner, function_tool

@function_tool
def fetch_data(id: str) -> str:
    """Retornar dados para o ID dado."""
    # Simulação de busca em banco de dados
    return f"Dados para o ID {id}: ativo"

agent = Agent(
    name="DataAgent",
    instructions="Recupere dados usando a ferramenta.",
    tools=[fetch_data]
)
result = Runner.run_sync(agent, "Busque dados para o ID 123")
print(result.final_output)  # Saída: "Dados para o ID 123: ativo"

Integrando APIs Externas

Ferramentas podem conectar-se a serviços externos. Aqui está um exemplo de ferramenta de clima:

import requests
from agents import function_tool, Agent, Runner

@function_tool
def get_weather(city: str) -> str:
    """Obter o clima atual para uma cidade."""
    api_key = "sua-chave-api-de-clima"  # Substitua por uma chave real
    url = f"http://api.weatherapi.com/v1/current.json?key={api_key}&q={city}"
    response = requests.get(url)
    if response.status_code == 200:
        data = response.json()
        return f"O clima em {city} é {data['current']['condition']['text']}."
    return "Dados do clima indisponíveis."

agent = Agent(
    name="WeatherAgent",
    instructions="Forneça atualizações do clima usando a ferramenta.",
    tools=[get_weather]
)
result = Runner.run_sync(agent, "Como está o clima em Tóquio?")
print(result.final_output)  # Saída: "O clima em Tóquio é ensolarado." (exemplo)

Inscreva-se para obter uma chave API gratuita em weatherapi.com para testar isso.

Combinando Múltiplas Ferramentas

Agentes podem usar múltiplas ferramentas simultaneamente:

@function_tool
def log_entry(text: str) -> str:
    """Registrar uma mensagem."""
    return f"Registrado: {text}"

agent = Agent(
    name="MultiToolAgent",
    instructions="Use ferramentas para buscar e registrar.",
    tools=[web_search, log_entry]
)
result = Runner.run_sync(agent, "Pesquise tendências de IA e registre a consulta")
print(result.final_output)  # Saída inclui resultados da pesquisa e confirmação de registro

Delegações de Agentes

As delegações permitem que os agentes deleguem tarefas, possibilitando fluxos de trabalho complexos.

Configurando Delegações

Defina um agente primário com acesso a agentes secundários por meio do parâmetro handoffs:

from agents import Agent, Runner

english_agent = Agent(
    name="EnglishHelper",
    instructions="Responda apenas em inglês."
)
spanish_agent = Agent(
    name="SpanishHelper",
    instructions="Responda apenas em espanhol."
)
triage_agent = Agent(
    name="LanguageRouter",
    instructions="Detectar o idioma e delegar ao agente apropriado.",
    handoffs=[english_agent, spanish_agent]
)

result = Runner.run_sync(triage_agent, "Hola, ¿qué tal?")
print(result.final_output)  # Saída: "¡Bien, gracias!" (ou semelhante)

O triage_agent analisa a entrada e delega ao agente específico correspondente ao idioma.

Lógica de Delegação

A decisão de delegação depende das instruções do agente primário. Por exemplo:

• "Se a entrada contiver palavras em espanhol, delegue ao SpanishHelper."
• "Para entradas em inglês, use EnglishHelper."

Teste com uma entrada em inglês:

result = Runner.run_sync(triage_agent, "How are you?")
print(result.final_output)  # Saída: "I'm good, thanks!"

Delegações Aninhadas

Para fluxos de trabalho mais profundos, os agentes podem delegar a outros agentes com delegações:

analysis_agent = Agent(
    name="AnalysisBot",
    instructions="Analise dados e delegue para relatórios."
)
report_agent = Agent(
    name="ReportBot",
    instructions="Gere um relatório a partir da análise."
)
main_agent = Agent(
    name="WorkflowManager",
    instructions="Comece com a análise.",
    handoffs=[analysis_agent, report_agent]
)

result = Runner.run_sync(main_agent, "Analise dados de vendas")
print(result.final_output)  # Saída: Um relatório gerado

Implementando Limites

Limites impõem restrições sobre entradas e saídas usando modelos Pydantic.

Definindo um Limite

Crie um modelo para validar a estrutura de saída:

from pydantic import BaseModel
from agents import Agent, Runner

class QuestionCheck(BaseModel):
    is_question: bool
    reason: str

guard_agent = Agent(
    name="QuestionGuard",
    instructions="Determine se a entrada é uma pergunta.",
    output_type=QuestionCheck
)

result = Runner.run_sync(guard_agent, "Qual é a capital da França?")
print(result.final_output)  # Saída: {"is_question": true, "reason": "Termina com um ponto de interrogação"}

Integração de Fluxo de Trabalho

Use limites para filtrar entradas:

task_agent = Agent(
    name="TaskProcessor",
    instructions="Processar apenas perguntas.",
    handoffs=[guard_agent]
)
result = Runner.run_sync(task_agent, "Conte-me uma história")
print(result.final_output)  # A saída indica que não é uma pergunta

Rastreamento e Depuração

O rastreamento registra detalhes da execução do agente, acessível através do Painel da OpenAI.

Habilitando o Rastreamento

O rastreamento é automático. Cada execução gera um rastreio com:

• Dados de entrada/saída
• Chamadas de ferramentas
• Eventos de delegação
• Erros

Exemplo de Depuração

Se um agente falhar, revise o rastreio para identificar:

• Parâmetros de ferramenta incorretos
• Roteamento de delegação incorreto
• Erros de API

Melhores Práticas

Otimização de Desempenho

• Escolha do Modelo: Use gpt-3.5-turbo para velocidade, gpt-4 para raciocínio complexo.
• Temperatura: 0.2 para precisão, 0.9 para criatividade.
• Execução Assíncrona: Use Runner.run_async para tarefas paralelas.

Tratamento de Erros

• Ferramentas: Retorne mensagens de erro claras (por exemplo, "ID inválido").
• Delegações: Inclua um agente de fallback para falhas.

Design de Fluxo de Trabalho

• Modularidade: Divida tarefas entre os agentes.
• Clareza: Escreva instruções não ambíguas.
• Validação: Aplique limites em etapas-chave.

Conclusão

O OpenAI Agents SDK capacita os desenvolvedores a construir sistemas de IA sofisticados com agentes especializados, ferramentas integradas e fluxos de trabalho colaborativos. Este guia fornece uma base técnica para aproveitar todo o seu potencial, repleto de exemplos e melhores práticas.

E então, qual é o próximo passo? Comece a experimentar! Brinque com diferentes instruções, ferramentas e fluxos de trabalho. E se você encontrar um problema, ferramentas como o Apidog podem ajudar com testes de API, baixe gratuitamente.