Lição 3: Escrevendo prompts para delegação
Objetivos de aprendizado:
- Escrever um prompt de delegação autocontido que não dependa de o subagente ver a conversa entre você e o orquestrador
- Detalhar o escopo, os limites e quais fontes usar da tarefa dentro do próprio prompt de delegação
- Explicar o princípio "um domínio de problema, um agente" e o que quebrá-lo custa a você
Pré-requisitos: Concluir a Lição 2 e entender a arquitetura orquestrador-subagente e o isolamento de contexto | Anterior: Lição 2 << | Próxima: Lição 4 >>
Recapitulação: tudo o que o subagente não consegue ver, você tem de escrever para ele
A Lição 2 cobriu um mecanismo que importa aqui: "Each subagent starts with a fresh, isolated context window. It doesn't see your conversation history, the skills you've already invoked, or the files Claude has already read. Claude composes a delegation message that summarizes the task, and the subagent works from there." (cada subagente começa com uma janela de contexto nova e isolada. Ele não vê seu histórico de conversa, as skills que você já invocou, nem os arquivos que o Claude já leu. O Claude compõe uma mensagem de delegação que resume a tarefa, e o subagente trabalha a partir daí)1 Esta lição torna isso concreto. Significa que todo o contexto que você conversou com o usuário no nível do orquestrador, os trade-offs que você acertou em rodadas anteriores, a restrição solta que o usuário jogou de passagem — o subagente não sabe nada disso. A única coisa que o subagente sabe é qualquer palavra que você escreveu nesta única tarefa de delegação.
Isto não é um lembrete gentil, é uma restrição rígida: o teto de qualidade do prompt de delegação define o teto de qualidade do que o subagente produz. Qualquer coisa que o prompt não detalhar, o subagente vai adivinhar, pular ou inventar uma suposição e seguir em frente. Adivinhou certo, você teve sorte. Adivinhou errado, e aquela subtarefa inteira está basicamente desperdiçada.
Autocontido: o prompt tem de dizer a coisa toda por conta própria
Autocontido: depois de ler um prompt de delegação, o subagente não precisa de nenhum contexto extra para descobrir com precisão o que deve fazer. Há um teste simples para saber se um prompt é autocontido. Tire-o do contexto, remova todo o contexto entre você e o orquestrador e leia-o a frio. Se você ainda tem de adivinhar para preencher os detalhes da tarefa, o prompt falha no teste.
Pegue o exemplo da Lição 1 de pesquisar preços em três provedores de nuvem. Se o orquestrador entrega ao subagente uma tarefa que diz só "consulte os preços da AWS", essa linha única carrega informação suficiente para o próprio orquestrador — porque o contexto do orquestrador ainda mantém o pano de fundo de "por que estamos consultando isto", "contra quem vamos comparar depois" e "em que dimensões estamos comparando". Mas o subagente não consegue ver nada disso. O que ele recebe é uma linha solitária, "consulte os preços da AWS", e fica adivinhando: preços de quais categorias de produto? Só os preços atuais, ou as mudanças ao longo do último ano? Como deve ser o entregável depois de encontrado? Cada suposição é uma aposta que pode dar errado.
Detalhe escopo e restrições: o que fazer, o que não fazer, quais fontes usar
A orientação oficial lista o que uma boa descrição de tarefa de subagente deve conter: "Each subagent needs an objective, an output format, guidance on the tools and sources to use, and clear task boundaries. Without detailed task descriptions, agents duplicate work, leave gaps, or fail to find necessary information." (cada subagente precisa de um objetivo, um formato de saída, orientação sobre as ferramentas e fontes a usar e limites de tarefa claros. Sem descrições de tarefa detalhadas, os agentes duplicam trabalho, deixam lacunas ou falham em encontrar as informações necessárias)2
Abra essa lista. "Objetivo" e "formato de saída" são fáceis de pegar. Os dois que ficam de fora são o último par — orientação de fontes e limites de tarefa. A orientação de fontes diz ao subagente onde procurar a resposta: a página oficial de preços, um site terceiro de comparação de preços, ou ambos, com a página oficial tendo precedência. Os limites de tarefa dizem ao subagente que esta execução cobre apenas esta fatia, não vá além dela: só os preços atuais, sem mudanças históricas de preço; só as linhas principais de produto, não liste cada serviço obscuro. Deixe esses dois de fora e o subagente tende a derivar de uma de duas formas. Ou ele perde informação que você de fato queria, ou busca muito mais do que você queria e queima chamadas de ferramenta e tokens que você poderia ter poupado.
Reescrita como uma descrição de tarefa autocontida com escopo claro, a pesquisa de provedores de nuvem fica mais ou menos assim:
Tirada do contexto por conta própria, essa descrição permite ao subagente julgar com precisão "o que consultar, até onde levar, o que entregar" sem saber nada do que o orquestrador discutiu internamente.
O contraexemplo: instruções vagas deixam os subagentes improvisando
O que de fato dá errado quando você não detalha escopo e limites — a equipe oficial deu um exemplo real da prática: "We started by allowing the lead agent to give simple, short instructions like 'research the semiconductor shortage,' but found these instructions often were vague enough that subagents misinterpreted the task or performed the exact same searches as other agents." (começamos permitindo que o agente líder desse instruções simples e curtas como “pesquise a escassez de semicondutores”, mas descobrimos que essas instruções eram frequentemente vagas o bastante para que os subagentes interpretassem mal a tarefa ou realizassem exatamente as mesmas buscas que outros agentes)2
"pesquise a escassez de semicondutores" parece que entrega uma tarefa, mas não fixa nada — em que intervalo de tempo? Focado no lado da oferta, no lado da demanda, ou no impacto de políticas? Entregue em que forma? Três subagentes recebendo a mesma instrução vaga muito provavelmente vão todos buscar em direção a "as causas da escassez de semicondutores", o ângulo que vem à mente primeiro, e o resultado são três corpos de pesquisa com forte sobreposição, enquanto os ângulos que de fato precisavam de cobertura (digamos, o impacto nas indústrias a jusante, ou como diferentes países reagiram) ficam sem toque. Esta é a raiz, no nível do prompt, do problema de "trabalho duplicado" da Lição 2 — não é que os subagentes não escutem, é que a própria descrição de tarefa nunca traçou os limites.
Um domínio de problema, um agente
Além de escrever um único prompt com clareza, como múltiplos subagentes dividem o trabalho também segue um princípio que você pode destilar da prática oficial — a equipe oficial nunca o nomeou, este nome é nosso: um domínio de problema, um agente — cada subagente deveria ser dono de apenas uma classe de problema claramente delimitada, em vez de ter um único subagente fazendo malabarismo com várias coisas não relacionadas ao mesmo tempo.
O sistema oficial tem um exemplo direto: eles montaram um CitationAgent dedicado, "a CitationAgent, which processes the documents and research report to identify specific locations for citations. This ensures all claims are properly attributed to their sources." (um CitationAgent, que processa os documentos e o relatório de pesquisa para identificar os locais específicos das citações. Isso garante que todas as afirmações sejam devidamente atribuídas às suas fontes)2 Encontrar onde vão as citações é um tipo de trabalho completamente diferente de "pesquisar a estratégia de preços de alguma empresa" — o primeiro é verificar e localizar, o segundo é buscar e julgar. Entregue os dois ao mesmo subagente e ele tem de alternar entre dois modos de pensamento inteiramente diferentes, e sua descrição de tarefa fica longa e emaranhada por tentar servir a dois objetivos, fácil de fazer corpo mole em um em favor do outro. Divida em dois subagentes focados e a descrição de tarefa de cada um permanece simples e claramente delimitada — o que ecoa a régua da Lição 1: se pode ser dividido em subtarefas independentes, vale a pena dividir.
Recapitulação
- O subagente não consegue ver o histórico de conversa do orquestrador,1 o que significa que um prompt de delegação tem de ser autocontido: legível por conta própria, à parte de qualquer pano de fundo conversacional, e ainda assim suficiente para o subagente julgar com precisão o que deve fazer.
- Uma boa descrição de tarefa tem de conter um objetivo, um formato de saída, orientação de fontes e limites de tarefa claros; sem isso, os subagentes duplicam trabalho, deixam lacunas ou falham em encontrar as informações necessárias.2
- O contraexemplo real oficial prova que instruções vagas como "pesquise a escassez de semicondutores" levam os subagentes a interpretar mal a tarefa ou a rodar exatamente as mesmas buscas que outros subagentes2 — escopo e limites não são opcionais, são a chave para evitar trabalho duplicado.
- Um domínio de problema, um agente (esta é a destilação da prática oficial feita por esta lição): cada subagente deveria ser dono de apenas uma classe de problema claramente delimitada, como montar um CitationAgent dedicado para tratar dos locais de citação, dividindo trabalhos de naturezas diferentes entre subagentes diferentes2 para que cada descrição de tarefa permaneça simples e focada.
- Para julgar se um prompt de delegação é bom o bastante, o teste é simples: tire-o do contexto e leia-o uma vez, e veja se o subagente tem de adivinhar para preencher os detalhes da tarefa.
>> Lição 4: Padrões de colaboração: pipeline, revisão, votação