---
title: "OpenAI Agents SDK: Multi-Agentes em Python — 2026"
url: "https://python.dev.br/blog/openai-agents-sdk-python-multi-agentes/"
markdown_url: "https://python.dev.br/blog/openai-agents-sdk-python-multi-agentes.MD"
description: "Aprenda a criar sistemas multi-agentes com o OpenAI Agents SDK em Python. Exemplos práticos com handoffs, tools e guardrails passo a passo."
date: "2026-04-21"
author: "Equipe python.dev.br"
---

# OpenAI Agents SDK: Multi-Agentes em Python — 2026

Aprenda a criar sistemas multi-agentes com o OpenAI Agents SDK em Python. Exemplos práticos com handoffs, tools e guardrails passo a passo.


O **OpenAI Agents SDK** é um framework Python leve e poderoso para construir sistemas **multi-agentes** — onde múltiplos agentes de IA colaboram, delegam tarefas entre si e usam ferramentas externas para resolver problemas complexos. Lançado como sucessor do experimental Swarm, o SDK rapidamente se tornou uma das bibliotecas mais populares para desenvolvimento de aplicações baseadas em agentes.

Neste artigo, vamos explorar como instalar, configurar e criar seus primeiros agentes com exemplos práticos e completos em Python.

## O que são agentes de IA?

Um **agente de IA** é um programa que recebe instruções em linguagem natural, decide quais ações tomar, executa ferramentas e retorna resultados. Diferente de um chatbot simples que apenas responde perguntas, um agente pode:

- Chamar APIs externas
- Consultar bancos de dados
- Executar código
- Delegar tarefas para outros agentes
- Tomar decisões com base em contexto

O OpenAI Agents SDK abstrai toda essa complexidade em primitivas simples: **Agent**, **Tool**, **Handoff** e **Guardrail**.

## Instalação e configuração

Para começar, instale o SDK usando [pip](/glossario/pip/) ou [uv](/blog/uv-gerenciador-pacotes-python/):

```bash
# 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]"
```

Configure sua chave de API como [variável de ambiente](/glossario/variavel/):

```bash
export OPENAI_API_KEY="sua-chave-aqui"
```

## Criando seu primeiro agente

O conceito básico é simples: um `Agent` recebe instruções e pode usar ferramentas:

```python
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())
```

O SDK usa [async/await](/blog/python-async-await/) nativamente, o que permite alta performance em aplicações que fazem múltiplas chamadas simultâneas.

## Adicionando ferramentas (Tools)

O poder real dos agentes vem das **ferramentas** — funções Python que o agente pode chamar quando precisa de dados ou ações externas:

```python
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())
```

O decorador `@function_tool` transforma qualquer [função](/glossario/funcao/) Python em uma ferramenta que o agente pode usar. O SDK extrai automaticamente o nome, a docstring e os [type hints](/glossario/type-hints/) para informar o modelo.

## Sistema multi-agentes com handoffs

O recurso mais poderoso do SDK é o **handoff** — a capacidade de um agente delegar tarefas para outro agente especializado:

```python
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())
```

O coordenador analisa cada pergunta e faz o **handoff** automático para o agente mais adequado. Isso é poderoso para criar sistemas que escalam em complexidade sem perder qualidade nas respostas.

## Guardrails: segurança e validação

Os **guardrails** permitem validar entradas e saídas dos agentes, garantindo que respostas inadequadas sejam filtradas:

```python
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())
```

Note o uso de [Pydantic](/blog/pydantic-validacao-dados-python/) para definir o esquema de saída estruturada — um padrão que funciona perfeitamente com o SDK.

## Agentes como ferramentas

Além de handoffs, você pode usar um agente como **ferramenta** de outro agente. A diferença é que o controle volta para o agente principal após a execução:

```python
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())
```

## Tracing e observabilidade

O SDK inclui **tracing integrado** para monitorar e debugar seus agentes:

```python
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())
```

O tracing permite visualizar o fluxo completo de execução, identificar gargalos e debugar problemas em sistemas complexos. Isso é essencial para manter a qualidade quando você tem múltiplos agentes interagindo.

## Exemplo prático: assistente de código

Vamos juntar tudo em um exemplo completo — um assistente que analisa código Python, sugere melhorias e explica conceitos:

```python
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())
```

## Comparação com outras abordagens

| Ferramenta | Foco | Complexidade | Provider Lock-in |
|-----------|------|-------------|-----------------|
| OpenAI Agents SDK | Multi-agentes | Baixa | Não (100+ LLMs) |
| LangChain | Chains e RAG | Alta | Não |
| CrewAI | Equipes de agentes | Média | Não |
| Autogen | Conversas multi-agentes | Média | Parcial |

O Agents SDK se destaca pela simplicidade. Se você já trabalha com [APIs de LLMs](/blog/python-e-llms-apis-inteligencia-artificial/) e quer adicionar capacidade agentic ao seu projeto, é a opção com menor curva de aprendizado.

## Boas práticas

Para construir sistemas multi-agentes robustos:

1. **Instruções claras**: cada agente deve ter um papel bem definido
2. **Ferramentas específicas**: crie ferramentas pequenas e focadas
3. **Guardrails sempre**: valide entradas e saídas, especialmente em produção
4. **[Logging](/blog/logging-em-python/)**: use tracing para monitorar todo o fluxo
5. **[Testes](/blog/testes-unitarios-python/)**: escreva testes para cada ferramenta individualmente
6. **[Tratamento de erros](/blog/tratamento-de-erros-python/)**: agentes podem falhar — prepare fallbacks
7. **Type hints**: use [tipagem](/blog/tipagem-estatica-python-mypy/) em todas as ferramentas para documentação automática

## Perguntas frequentes

### Preciso usar a API da OpenAI?

Não necessariamente. O SDK é **provider-agnostic** e suporta mais de 100 LLMs diferentes, incluindo modelos locais e de outros provedores.

### Qual a diferença entre handoff e agent-as-tool?

No **handoff**, o controle passa completamente para o outro agente. No **agent-as-tool**, o agente é usado como uma ferramenta e o controle retorna ao agente principal após a execução.

### É possível manter estado entre conversas?

Sim. O SDK suporta **sessions** que persistem o histórico de conversas. Com o extra Redis, você pode manter sessões entre reinicializações da aplicação.

### Funciona com Python 3.10+?

Sim, o SDK requer Python 3.10 ou superior. Recomendamos usar o Python 3.14 para aproveitar o [JIT compiler](/blog/python-3-14-jit-compiler-desempenho/) e melhor performance geral.

## Conclusão

O OpenAI Agents SDK simplifica drasticamente a construção de sistemas multi-agentes em Python. Com primitivas claras como Agent, Tool, Handoff e Guardrail, você pode criar desde assistentes simples até pipelines complexos de IA.

Para começar, instale o SDK, crie seu primeiro agente com ferramentas e evolua para sistemas multi-agentes conforme a necessidade. E se você quer entender melhor o ecossistema de IA em Python, confira nosso artigo sobre [Python e LLMs](/blog/python-e-llms-apis-inteligencia-artificial/) e o guia de [design patterns em Python](/blog/design-patterns-python/).

Para backends de agentes em produção com baixa latência e alta concorrência, considere também <a href="https://golang.com.br/" target="_blank" rel="noopener" onclick="umami.track('portfolio-site-click', { destination: 'golang.com.br' })">Go</a>, que é amplamente usado para orquestração de microserviços e APIs de IA em larga escala.