Como Construir um Sistema Multi-Agente: Guia Prático do Padrão Supervisor

Depois de ter assimilado o conceito de "coordenar várias IAs" em O que é um sistema multi-agente?, a próxima pergunta é como construir um de verdade. Este artigo percorre um processo prático de 5 passos para iniciantes, usando o padrão de fato de 2026: o padrão supervisor.

Antes de falar de frameworks, o princípio mais importante: "construa primeiro com um único agente e adicione agentes de forma mínima só depois de bater em um limite". Começar com muitos agentes costuma ser excesso de engenharia. Na segunda metade, você verá código mínimo e legível que segue a documentação oficial do Claude Agent SDK e do OpenAI Agents SDK, além de como dividir os papéis e as falhas que realmente acontecem. A mesma lógica vale se você conectar ferramentas via MCP.

Nota: o código segue a documentação oficial do Claude Agent SDK e do OpenAI Agents SDK (verificada em 4 de outubro de 2026). Esses SDKs mudam rápido, então confirme os nomes dos parâmetros em cada documentação oficial antes de executar. Cada número do artigo traz a sua fonte.

1. Antes de construir: você realmente precisa de multi?

O primeiro filtro não é técnico — é uma decisão de julgamento. Multi-agente é poderoso, mas não ajuda em todo trabalho. Se nenhum dos pontos a seguir se aplica, construa primeiro com um único agente.

Como vimos no artigo anterior, usar multi-agente num processo linear custa caro. Num estudo do Google Research (publicado em janeiro de 2026, comparando 180 configurações), todas as variantes multi-agente testadas tiveram desempenho 39–70% pior que um único agente numa tarefa de raciocínio estritamente sequencial (PlanCraft). O custo também sobe: na explicação sobre o seu próprio agente de pesquisa, a Anthropic relata que agentes usam cerca de 4 vezes mais tokens que um chat, e sistemas multi-agente cerca de 15 vezes. Parta da premissa de que mais agentes não significam mais inteligência.

2. A forma básica: o padrão supervisor

Se estiver em dúvida sobre qual padrão usar, começar pelo padrão supervisor é a escolha segura. Os principais SDKs o documentam como padrão básico. No Claude Agent SDK, o agente principal chama subagentes pela ferramenta Agent; no OpenAI Agents SDK, o equivalente é "agents as tools", em que um agente gerente chama agentes especialistas como ferramentas.

A mecânica é simples. O supervisor recebe a tarefa global, divide-a em subtarefas, delega-as a workers especialistas e agrega os resultados. O supervisor não precisa saber como um worker faz seu trabalho — apenas qual worker chamar e em que formato de saída. A expertise vive nos workers.

Atenção: no OpenAI Agents SDK, um handoff tem um sentido mais estreito que a passagem geral de trabalho do passo 4: um agente de triagem transfere a própria conversa a um especialista, que passa a responder diretamente ao usuário. Nenhum supervisor permanece, então trate-o como um padrão diferente (a seção 6 explica quando usar cada um).

3. Construa em 5 passos

Monte uma configuração mínima de supervisor em cinco passos. A regra prática: comece com 2-3 workers e só acrescente mais à medida que a medição justificar.

4. Código mínimo ①: Claude Agent SDK (Python)

Primeiro, monte um supervisor e dois workers (um pesquisador e um revisor) com o Claude Agent SDK da Anthropic. A preparação é só pip install claude-agent-sdk e a variável de ambiente ANTHROPIC_API_KEY (guia rápido oficial; o SDK não carrega arquivos .env automaticamente). O código segue a página oficial de Subagents. Para o SDK como um todo, veja nosso guia do Claude Agent SDK.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition, ResultMessage

options = ClaudeAgentOptions(
    model="claude-opus-5-5",  # o supervisor (agente principal)
    system_prompt=(
        "Você coordena um relatório de pesquisa. Delegue a pesquisa ao researcher e a "
        "checagem ao reviewer, e escreva você mesmo o texto final. Ao delegar, informe "
        "sempre o objetivo, o formato de saída e o escopo."
    ),
    allowed_tools=["Agent", "WebSearch", "WebFetch"],  # ferramentas que rodam sem pedir permissão
    agents={
        "researcher": AgentDefinition(
            description="Reúne fontes primárias. Use quando precisar de fatos ou números.",
            prompt="Procure fontes primárias para a pergunta e devolva tópicos com a URL de cada fonte. Não preencha lacunas com suposições.",
            tools=["WebSearch", "WebFetch"],  # as únicas ferramentas deste papel
            model="sonnet",
            maxTurns=15,
        ),
        "reviewer": AgentDefinition(
            description="Checa rascunhos. Use sempre antes de finalizar o texto.",
            prompt="Confronte cada afirmação do rascunho com a sua fonte e liste as frases sem respaldo.",
            tools=["WebFetch"],
            model="sonnet",
            maxTurns=10,
        ),
    },
    max_turns=30,         # limite de idas e voltas da execução inteira
    max_budget_usd=5.0,   # limite de gasto (estimativa do SDK)
    env={"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1"},  # workers não criam subagentes próprios
)


async def main():
    try:
        async for message in query(
            prompt="Reúna três estatísticas oficiais sobre o uso de IA generativa no trabalho e escreva um relatório curto",
            options=options,
        ):
            if isinstance(message, ResultMessage):
                print(message.subtype, message.total_cost_usd)
                print(message.result)
    except Exception as error:
        print(f"Parou antes do fim: {error}")  # atingir um limite também cai aqui


asyncio.run(main())

Cinco pontos a observar:

• Os workers ficam em agents como entradas AgentDefinition. O supervisor lê a description de cada worker para decidir quem chamar e quando, então descreva com precisão o que o papel faz e quando usá-lo.
• Ao listar tools, o papel recebe só essas ferramentas. Por isso o revisor não tem ferramentas de escrita. Já allowed_tools lista as ferramentas que rodam sem pedido de permissão; não restringe nada (referência oficial de Python).
• Coloque limites em três lugares. Um maxTurns por papel, um max_turns global e um limite de gasto com max_budget_usd. Quando um limite global é atingido, o subtipo do resultado vira error_max_turns ou error_max_budget_usd e a execução para (documentação do loop do agente).
• Corte o aninhamento. Subagentes podem criar subagentes próprios. Com a variável de ambiente CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH em 1, os workers fazem o trabalho eles mesmos. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (padrão 20) limita quantos rodam ao mesmo tempo.
• Os campos de AgentDefinition são em camelCase. Escrever max_turns em vez de maxTurns gera um TypeError na criação (nota oficial). O supervisor usa o modelo atual claude-opus-5-5 e os workers o alias "sonnet", assim o código continua funcionando quando sai uma versão nova.

A documentação oficial aponta que o Opus 5 delega a subagentes com mais facilidade que os modelos anteriores e recomenda definir limites de profundidade, concorrência e gasto, além das instruções no prompt. Uma instrução só muda a forma como o Claude pede ajuda; só os limites param uma execução com segurança.

5. Código mínimo ②: OpenAI Agents SDK (Python)

No Agents SDK da OpenAI, a mesma forma transforma os agentes especialistas em ferramentas com as_tool() e os passa para as tools do supervisor ("agents as tools" oficial). A preparação é pip install openai-agents e a variável de ambiente OPENAI_API_KEY (guia rápido oficial). Se você omitir model, o SDK usa o modelo padrão; esse padrão muda entre versões, então confira na página de Models.

import asyncio
from agents import Agent, Runner, WebSearchTool

researcher = Agent(
    name="Researcher",
    instructions="Procure fontes primárias para a pergunta e devolva tópicos com a URL de cada fonte. Não preencha lacunas com suposições.",
    tools=[WebSearchTool()],
)
reviewer = Agent(
    name="Reviewer",
    instructions="Confronte cada afirmação do rascunho recebido com a sua fonte e liste as frases sem respaldo.",
)

manager = Agent(
    name="Manager",
    instructions=(
        "Você coordena um relatório de pesquisa. Delegue a pesquisa ao research e a "
        "checagem ao review, e escreva você mesmo o texto final."
    ),
    tools=[
        researcher.as_tool(
            tool_name="research",
            tool_description="Reunir fontes primárias com citações",
            max_turns=10,  # limite de idas e voltas deste papel
        ),
        reviewer.as_tool(
            tool_name="review",
            tool_description="Checar um rascunho",
        ),
    ],
)


async def main():
    result = await Runner.run(
        manager,
        input="Reúna três estatísticas oficiais sobre o uso de IA generativa no trabalho e escreva um relatório curto",
        max_turns=10,  # se passar disso, lança MaxTurnsExceeded
    )
    print(result.final_output)


asyncio.run(main())

O que os dois SDKs têm em comum e onde diferem:

• Os workers não conhecem a conversa do pai. Um agente chamado via as_tool() não herda automaticamente o estado da conversa da execução pai (documentação oficial). O Claude Agent SDK funciona igual: a única coisa que um subagente recebe do pai é o prompt da ferramenta Agent. Escreva no próprio pedido os caminhos de arquivo, as mensagens de erro e as decisões tomadas.
• O limite é Runner.run(..., max_turns=). Se for ultrapassado, lança MaxTurnsExceeded. Com error_handlers={"max_turns": ...} você devolve uma resposta controlada em vez de uma exceção (Running agents).
• Com handoffs você escreveria Agent(..., handoffs=[billing_agent, refund_agent]). O agente que recebe assume a conversa e, por padrão, vê todo o histórico anterior. Se houver informação que ele não deve receber, restrinja com um input_filter.

6. Como dividir os papéis: boas e más divisões

Dividir os papéis é mais difícil que o código. A Anthropic escreve que cada subagente precisa de um objetivo, um formato de saída, orientação sobre as ferramentas e fontes a usar e limites claros da tarefa (mesma explicação). Veja divisões que cumprem essas quatro condições e outras que não.

A mesma explicação traz um guia de quantos agentes usar. A Anthropic incluiu regras de escala no prompt do seu supervisor de pesquisa: uma busca simples de fatos precisa de 1 agente com 3 a 10 chamadas de ferramenta, comparações diretas de 2 a 4 subagentes com 10 a 15 chamadas cada, e pesquisas complexas podem usar mais de 10 subagentes. Esses números são para trabalho de pesquisa, então no seu caso comece pelo lado pequeno e só aumente depois de medir.

Para escolher entre supervisor e handoff, a documentação da OpenAI dá um critério claro. Se você quer que um agente seja dono da resposta final ou combinar os resultados de vários especialistas, use o supervisor (agents as tools). Se o roteamento é o próprio trabalho e o especialista escolhido deve responder diretamente ao usuário (triagem de pedidos de suporte, por exemplo), use um handoff. Dá para combinar os dois.

7. Falhas comuns e soluções

Os tropeços são previsíveis. Abaixo estão falhas que a Anthropic diz terem acontecido de verdade com o seu agente de pesquisa e os pontos sobre os quais a documentação oficial dos dois SDKs alerta.

A lição compartilhada: "os prompts, o design das ferramentas e o harness de eval decidem o sucesso mais do que o framework." A documentação da OpenAI também lista investir em bons prompts, monitorar e iterar, usar agentes especializados e investir em evals. Acima de uma arquitetura chamativa, a disciplina de construir pequeno, medir e adicionar apenas quando compensa é o que sai mais rápido no fim.

Resumo

Construir um sistema multi-agente não é assustador se você começar com o padrão supervisor a partir de uma configuração mínima. Vamos recapitular.

"Construa pequeno, meça e depois acrescente." Mantenha essa disciplina e um sistema multi-agente se torna um parceiro poderoso para trabalhos complexos. Para o conceito, veja O que é um sistema multi-agente?; para construir um único, Como construir um agente de IA.

FAQ