Domínio 1 — Agentic Architecture & Orchestration · Lição 5 de 7

Multi-agente: coordenador, subagentes e contexto isolado

Objetivos de aprendizagem

• Descrever a arquitetura hub-and-spoke: o coordenador centraliza comunicação, roteamento e tratamento de erros entre subagentes.
• Explicar por que subagentes operam com contexto isolado — eles não herdam o histórico do coordenador.
• Configurar subagentes no Claude Agent SDK: AgentDefinition, Task tool e a exigência de "Task" em allowedTools.
• Passar contexto explicitamente: achados completos dos agentes anteriores dentro do prompt do subagente.
• Fazer spawn paralelo: múltiplas chamadas de Task numa única resposta do coordenador.
• Diagnosticar cobertura incompleta causada por decomposição estreita demais do coordenador.

Hub-and-spoke: o coordenador no centro

Na arquitetura multi-agente cobrada pela prova, um coordenador (hub) gerencia subagentes especializados (spokes). Toda a comunicação entre subagentes passa pelo coordenador — subagentes não conversam entre si. Isso dá:

• Observabilidade: um ponto único por onde flui toda informação;
• Tratamento de erros consistente: o coordenador decide retry, alternativa ou seguir com resultados parciais;
• Fluxo de informação controlado: cada subagente recebe apenas o que precisa.

O coordenador é responsável por: decompor a tarefa, delegar (escolhendo dinamicamente quais subagentes invocar conforme a complexidade da consulta — não rodar sempre o pipeline inteiro), agregar resultados e iterar: avaliar a síntese em busca de lacunas, re-delegar buscas direcionadas e re-invocar a síntese até a cobertura ser suficiente.

flowchart TD
    C[Coordenador
decompõe, delega, agrega, itera] -->|Task 1| S1[Subagente
web search]
    C -->|Task 2| S2[Subagente
análise de documentos]
    C -->|Task 3| S3[Subagente
síntese]
    S1 -->|achados| C
    S2 -->|achados| C
    S3 -->|relatório| C
    C -.->|lacunas? re-delegar
consultas direcionadas| S1
  

Contexto isolado: a regra mais cobrada

Cada subagente começa com uma janela de contexto limpa. Ele não herda automaticamente o histórico da conversa do coordenador, não vê os resultados de ferramentas de outros subagentes e não compartilha memória entre invocações. Consequências práticas:

• Tudo que o subagente precisa saber vai no prompt da Task. Se o subagente de síntese precisa dos resultados da busca web e da análise de documentos, o coordenador deve incluir esses achados completos (não um resumo vago) no prompt que envia.
• Use formatos estruturados ao passar achados, separando conteúdo de metadados (URLs de fonte, nomes de documentos, páginas) para preservar atribuição na síntese.
• O benefício: o trabalho verboso de exploração fica isolado no contexto do subagente; só o resultado resumido volta ao coordenador — preservando a janela de contexto principal.

Task tool e allowedTools no Agent SDK

No Claude Agent SDK, o mecanismo de spawn de subagentes é a Task tool. Dois requisitos de configuração caem na prova:

• O coordenador só consegue invocar subagentes se "Task" estiver incluído em allowedTools. Se você restringe as ferramentas do coordenador e esquece a Task, os subagentes definidos nunca são invocados — sem erro explícito, o coordenador simplesmente tenta fazer tudo sozinho.
• Cada tipo de subagente é configurado via AgentDefinition, com description (quando o coordenador deve usá-lo), prompt (system prompt do subagente) e restrição de ferramentas (tools) ao necessário para o papel.

import anyio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    # Sem "Task" aqui, o coordenador NAO consegue invocar subagentes.
    allowed_tools=["Task", "Read", "Grep", "Glob"],
    agents={
        "web-searcher": AgentDefinition(
            description="Busca fontes na web sobre um subtopico especifico. "
                        "Use uma invocacao por subtopico.",
            prompt="Voce pesquisa na web e retorna achados estruturados: "
                   "claim, trecho de evidencia, URL da fonte e data de publicacao.",
            tools=["WebSearch", "WebFetch"],
        ),
        "doc-analyst": AgentDefinition(
            description="Analisa documentos locais e extrai dados citaveis.",
            prompt="Analise os documentos indicados e retorne achados com "
                   "nome do documento e pagina para cada afirmacao.",
            tools=["Read", "Grep", "Glob"],
        ),
        "synthesizer": AgentDefinition(
            description="Sintetiza achados ja coletados em um relatorio citado. "
                        "Os achados completos DEVEM vir no prompt da Task.",
            prompt="Combine os achados fornecidos no prompt em um relatorio "
                   "coeso, preservando a atribuicao de fonte de cada claim.",
            tools=["Read"],
        ),
    },
    system_prompt="Voce e o coordenador de pesquisa. Decomponha o topico em "
                  "subtopicos que cubram TODO o dominio da pergunta, delegue "
                  "subtopicos independentes em paralelo (multiplas Task calls "
                  "numa unica resposta) e passe os achados completos ao "
                  "synthesizer no prompt da Task.",
)

async def main():
    async for message in query(
        prompt="Pesquise o impacto da IA nas industrias criativas.",
        options=options,
    ):
        print(message)

anyio.run(main)

Spawn paralelo e decomposição bem calibrada

• Paralelismo: para subagentes rodarem ao mesmo tempo, o coordenador emite múltiplas chamadas da Task tool numa única resposta. Se ele emitir uma Task por turno (esperando o resultado antes da próxima), a execução vira sequencial e a latência dispara.
• Decomposição estreita demais: risco explícito do task statement 1.2 — o coordenador decompõe "indústrias criativas" em só "arte digital, design gráfico, fotografia" e o relatório final ignora música, literatura e cinema. Os subagentes executam corretamente o que receberam; a causa raiz é a decomposição do coordenador, não os subagentes. Correção: prompt do coordenador exigindo cobertura completa do domínio da pergunta, com partição de escopo que minimize duplicação (subtópicos ou tipos de fonte distintos por agente).
• Metas, não procedimentos: prompts de coordenador devem especificar objetivos de pesquisa e critérios de qualidade, não instruções procedurais passo a passo — para os subagentes manterem adaptabilidade.

Pegadinhas da prova

• Distrator típico: "o subagente acessa o histórico do coordenador automaticamente" — falso; contexto é isolado e deve ser passado explicitamente no prompt da Task.
• Distrator típico: relatório com cobertura incompleta → culpar o subagente de busca ou de síntese, quando os logs mostram decomposição estreita do coordenador. A causa raiz está em quem atribuiu as tarefas.
• Distrator típico: "para paralelizar, dispare uma Task por turno em sequência rápida". Paralelismo real = múltiplas Task calls na mesma resposta do coordenador.
• Distrator típico: subagentes se comunicando diretamente entre si "para reduzir latência". Quebra o hub-and-spoke: perde-se observabilidade, tratamento de erros central e controle do fluxo de informação.
• Distrator típico: esquecer "Task" no allowedTools do coordenador e procurar o bug nos subagentes.
• Distrator típico: rodar sempre o pipeline completo de subagentes para qualquer consulta. O coordenador deve analisar a consulta e invocar dinamicamente só os subagentes necessários.

Resumo em 5 linhas

Documentação oficial

• Claude Agent SDK — Subagents
• Claude Agent SDK overview
• How we built our multi-agent research system

Questões de fixação