OpenAI Agents SDK: Multi-Agentes em Python — 2026

# Com pip
pip install openai-agents

# Com uv (recomendado)
uv pip install openai-agents

# Com extras para voz e sessões Redis
pip install "openai-agents[voice,redis]"

export OPENAI_API_KEY="sua-chave-aqui"

from agents import Agent, Runner


# Criar um agente simples
agente = Agent(
    name="Assistente Python",
    instructions="""
    Você é um assistente especializado em Python.
    Responda perguntas sobre a linguagem de forma clara e objetiva.
    Inclua exemplos de código quando possível.
    """,
)


async def main():
    resultado = await Runner.run(
        agente,
        input="Como usar list comprehension em Python?"
    )
    print(resultado.final_output)


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

from agents import Agent, Runner, function_tool
import httpx
from datetime import datetime


@function_tool
def buscar_clima(cidade: str) -> str:
    """Busca a previsão do tempo para uma cidade."""
    # Exemplo simplificado — substitua por uma API real
    climas = {
        "São Paulo": "25°C, parcialmente nublado",
        "Rio de Janeiro": "32°C, ensolarado",
        "Curitiba": "18°C, chuva leve",
        "Belo Horizonte": "27°C, céu limpo",
    }
    return climas.get(cidade, f"Clima não disponível para {cidade}")


@function_tool
def data_atual() -> str:
    """Retorna a data e hora atuais."""
    agora = datetime.now()
    return agora.strftime("%d/%m/%Y às %H:%M")


@function_tool
def calcular(expressao: str) -> str:
    """Calcula uma expressão matemática simples."""
    try:
        # Apenas operações seguras
        permitidos = set("0123456789+-*/.() ")
        if not all(c in permitidos for c in expressao):
            return "Expressão inválida"
        resultado = eval(expressao)  # seguro com validação acima
        return f"Resultado: {resultado}"
    except Exception as e:
        return f"Erro no cálculo: {e}"


# Agente com ferramentas
assistente = Agent(
    name="Assistente Completo",
    instructions="""
    Você é um assistente útil que pode verificar o clima,
    informar a data atual e fazer cálculos.
    Use as ferramentas disponíveis quando necessário.
    Responda sempre em português brasileiro.
    """,
    tools=[buscar_clima, data_atual, calcular],
)


async def main():
    resultado = await Runner.run(
        assistente,
        input="Qual o clima em São Paulo hoje? E quanto é 1250 * 0.85?"
    )
    print(resultado.final_output)


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

from agents import Agent, Runner


# Agente especialista em Python
especialista_python = Agent(
    name="Especialista Python",
    instructions="""
    Você é um especialista em Python com foco em:
    - Sintaxe e boas práticas
    - Bibliotecas populares
    - Padrões de projeto
    Responda com exemplos de código práticos.
    """,
)

# Agente especialista em dados
especialista_dados = Agent(
    name="Especialista em Dados",
    instructions="""
    Você é um especialista em ciência de dados com Python.
    Foque em:
    - Pandas, Polars e NumPy
    - Visualização com Matplotlib
    - Análise exploratória
    Inclua exemplos com DataFrames quando possível.
    """,
)

# Agente especialista em DevOps
especialista_devops = Agent(
    name="Especialista DevOps",
    instructions="""
    Você é um especialista em DevOps com Python.
    Foque em:
    - Docker e containers
    - CI/CD e automação
    - Deploy e infraestrutura
    - Monitoramento e logging
    """,
)

# Agente coordenador (triage)
coordenador = Agent(
    name="Coordenador",
    instructions="""
    Você é um coordenador que direciona perguntas para o
    especialista mais adequado:
    - Perguntas sobre código Python → Especialista Python
    - Perguntas sobre dados, análise, DataFrames → Especialista em Dados
    - Perguntas sobre deploy, Docker, CI/CD → Especialista DevOps
    Analise a pergunta e faça o handoff para o agente correto.
    """,
    handoffs=[especialista_python, especialista_dados, especialista_devops],
)


async def main():
    perguntas = [
        "Como usar decoradores em Python?",
        "Como analisar um CSV grande com Polars?",
        "Como fazer deploy de uma API FastAPI com Docker?",
    ]

    for pergunta in perguntas:
        print(f"\n{'='*60}")
        print(f"Pergunta: {pergunta}")
        print(f"{'='*60}")

        resultado = await Runner.run(coordenador, input=pergunta)
        print(f"\nResposta:\n{resultado.final_output}")


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

from agents import Agent, Runner, InputGuardrail, GuardrailFunctionOutput
from pydantic import BaseModel


class ValidacaoEntrada(BaseModel):
    """Resultado da validação de entrada."""
    is_valid: bool
    reasoning: str


# Agente validador de entrada
agente_validador = Agent(
    name="Validador",
    instructions="""
    Analise se a mensagem do usuário é uma pergunta legítima
    sobre programação Python. Rejeite:
    - Conteúdo ofensivo
    - Pedidos para gerar código malicioso
    - Perguntas que não são sobre programação
    """,
    output_type=ValidacaoEntrada,
)


async def validar_entrada(ctx, agent, input_data):
    """Guardrail que valida a entrada do usuário."""
    resultado = await Runner.run(
        agente_validador,
        input=input_data,
        context=ctx,
    )
    output = resultado.final_output_as(ValidacaoEntrada)
    return GuardrailFunctionOutput(
        output_info=output,
        tripwire_triggered=not output.is_valid,
    )


# Agente principal com guardrail
agente_seguro = Agent(
    name="Assistente Seguro",
    instructions="Responda perguntas sobre Python de forma útil e segura.",
    input_guardrails=[
        InputGuardrail(guardrail_function=validar_entrada),
    ],
)


async def main():
    try:
        resultado = await Runner.run(
            agente_seguro,
            input="Como usar dicionários em Python?"
        )
        print(resultado.final_output)
    except Exception as e:
        print(f"Entrada bloqueada pelo guardrail: {e}")


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

from agents import Agent, Runner


# Agente tradutor usado como ferramenta
agente_tradutor = Agent(
    name="Tradutor",
    instructions="""
    Traduza o texto recebido do português para o inglês.
    Retorne apenas a tradução, sem explicações.
    """,
)

# Agente revisor usado como ferramenta
agente_revisor = Agent(
    name="Revisor de Código",
    instructions="""
    Revise o código Python recebido e sugira melhorias.
    Foque em: legibilidade, performance e boas práticas.
    Retorne o código melhorado com comentários.
    """,
)

# Agente principal que orquestra os outros
agente_principal = Agent(
    name="Assistente Técnico",
    instructions="""
    Você é um assistente técnico que pode:
    1. Traduzir textos usando o agente tradutor
    2. Revisar código usando o agente revisor
    Use-os como ferramentas quando necessário.
    """,
    tools=[
        agente_tradutor.as_tool(
            tool_name="traduzir",
            tool_description="Traduz texto de português para inglês"
        ),
        agente_revisor.as_tool(
            tool_name="revisar_codigo",
            tool_description="Revisa e melhora código Python"
        ),
    ],
)


async def main():
    resultado = await Runner.run(
        agente_principal,
        input="""
        Revise este código Python:

        def pegar_dados(url):
            import requests
            r = requests.get(url)
            dados = r.json()
            resultado = []
            for item in dados:
                if item['ativo'] == True:
                    resultado.append(item['nome'])
            return resultado
        """
    )
    print(resultado.final_output)


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

from agents import Agent, Runner, trace


async def main():
    agente = Agent(
        name="Assistente",
        instructions="Responda perguntas sobre Python.",
    )

    # O trace agrupa todas as operações do agente
    with trace("minha-sessao"):
        resultado = await Runner.run(
            agente,
            input="Explique generators em Python"
        )
        print(resultado.final_output)

    # Acessar informações do trace
    for item in resultado.raw_responses:
        print(f"Modelo: {item.model}")
        print(f"Tokens usados: {item.usage}")


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

from agents import Agent, Runner, function_tool
import subprocess
import tempfile
import os


@function_tool
def executar_python(codigo: str) -> str:
    """Executa um trecho de código Python e retorna a saída."""
    with tempfile.NamedTemporaryFile(
        mode='w', suffix='.py', delete=False
    ) as f:
        f.write(codigo)
        f.flush()
        try:
            result = subprocess.run(
                ['python3', f.name],
                capture_output=True,
                text=True,
                timeout=10,
            )
            output = result.stdout
            if result.stderr:
                output += f"\nErros:\n{result.stderr}"
            return output or "Código executado sem saída"
        except subprocess.TimeoutExpired:
            return "Erro: timeout — o código demorou mais de 10s"
        finally:
            os.unlink(f.name)


@function_tool
def verificar_tipo(codigo: str) -> str:
    """Verifica tipos do código usando mypy."""
    with tempfile.NamedTemporaryFile(
        mode='w', suffix='.py', delete=False
    ) as f:
        f.write(codigo)
        f.flush()
        try:
            result = subprocess.run(
                ['mypy', f.name, '--no-error-summary'],
                capture_output=True,
                text=True,
                timeout=15,
            )
            return result.stdout or "Nenhum erro de tipo encontrado"
        except FileNotFoundError:
            return "mypy não está instalado"
        finally:
            os.unlink(f.name)


assistente_codigo = Agent(
    name="Assistente de Código Python",
    instructions="""
    Você é um assistente especializado em Python que pode:
    1. Executar código Python para validar resultados
    2. Verificar tipos com mypy
    3. Explicar conceitos e sugerir melhorias

    Sempre valide o código antes de apresentar ao usuário.
    Responda em português brasileiro.
    Use type hints e siga as boas práticas modernas do Python.
    """,
    tools=[executar_python, verificar_tipo],
)


async def main():
    resultado = await Runner.run(
        assistente_codigo,
        input="""
        Crie uma função que recebe uma lista de dicionários
        representando produtos (nome, preco, quantidade) e
        retorna os 3 produtos mais caros que estão em estoque.
        Use type hints e dataclasses.
        """
    )
    print(resultado.final_output)


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