O que é Extrair Subagente?
Extrair Subagente (Extract Subagent) é uma refatoração de IA para sistemas com LLM, do grupo Movendo controle. Dar a uma tarefa grande um agente próprio, com contexto limpo e ferramentas só dela.
Conteúdo da trilha
Capítulos
Transcrição
Abertura
O agente de conteúdo de uma fintech está escrevendo sobre Pix. Ele lê trinta páginas, escreve o post, revisa o próprio texto contra o guia da marca e publica.
No fim da tarefa, o contexto dele mistura três coisas.
Trechos de blogs de concorrentes.
Depois o raciocínio de quem escreveu, palavra por palavra. Usei esse argumento porque o jurídico pediu.
E a ferramenta de publicar.
Então o revisor herda o argumento de quem escreveu e deixa passar o que devia barrar. E uma página com uma instrução escondida fica a um passo da publicação. Você conheceu o mega agent na aula passada. Hoje você vai desmontá-lo, um subagente de cada vez.
A ideia
Dê a uma subtarefa grande e bem delimitada um agente próprio. Com contexto limpo, prompt próprio e só as ferramentas de que ela precisa. O agente principal entrega uma instrução e recebe de volta só o resultado, num formato combinado.
Antes e depois
Antes, um contexto para tudo. As páginas lidas, a revisão do próprio texto e a ferramenta de publicar, tudo no mesmo lugar.
Depois, o briefing chega ao agente principal. Ele planeja, escreve e decide. Ele não lê páginas da web.
O subagente de pesquisa lê tudo, no contexto dele, e devolve uma lista curta de fatos, cada um com a fonte.
O subagente de revisão recebe só o rascunho e o guia da marca. Sem o raciocínio de quem escreveu.
E publicar deixou de ser ferramenta do modelo. Virou uma etapa depois da aprovação.
Um caso real
O briefing: oitocentas palavras sobre Pix, para microempreendedor individual, no tom da marca, e nunca prometer rendimento. O agente principal chama a pesquisa, com o tema e a dica de preferir fontes oficiais. O subagente gasta doze passos, lê as trinta páginas e devolve isto.
Fatos, cada um com a fonte. Como: um MEI pode receber Pix numa conta pessoal vinculada, com a página do Banco Central como fonte.
E perguntas em aberto. Qual é o teto mensal atual? Ninguém achou com certeza, então ele diz isso.
O agente principal escreve a partir disso, sem nenhuma página da web à vista. O subagente de revisão recebe o rascunho e o guia e devolve um problema. Diz que o parágrafo quatro promete rendimento ao leitor. Publicar só acontece depois que a pessoa do marketing aprova. O conteúdo da web nunca ficou ao lado da ferramenta com efeito colateral.
Por que funciona
Um contexto é a memória de trabalho do modelo. Quando ele guarda trinta páginas, o raciocínio de quem escreveu e as regras de revisão, tudo ao mesmo tempo, tudo disputa atenção. Dividir devolve três propriedades.
Foco. Cada subagente tem um prompt de um papel só, e poucas ferramentas.
Limpeza. O trabalho bruto, páginas, logs e arquivos, morre dentro do subagente. O agente principal recebe uma página de resultado, em vez de cem.
E independência. O revisor não herda o raciocínio de quem escreveu, então julga o texto como ele é.
E o formato de retorno é o contrato entre os dois. Sem ele, o agente principal recebe texto livre e precisa adivinhar o que voltou. Fatos com fonte dá para revisar. Um parágrafo chamado resumo da pesquisa, não. E cada subagente recebe o seu orçamento, descontado do total da tarefa.
Um desafio
Uma pergunta para você. O contrato do subagente de pesquisa era um parágrafo livre. E o agente principal começou a completar fatos sem fonte. Qual é o próximo passo?
Mudar o contrato para um schema, com fatos, fontes e perguntas em aberto. E recusar um retorno que não preencha. Sem campos, o agente principal preenche as lacunas.
Um orçamento maior para a pesquisa só faz um parágrafo mais rico, que continua texto livre. E mandar as trinta páginas para o agente principal conferir desfaz tudo. Ele volta a ficar ao lado de páginas cruas da web.
Passo a passo seguro
Passo zero, medir. Rode o eval do agente atual e anote qualidade, custo por tarefa, tokens por turno no fim da tarefa e os incidentes conhecidos. Uma publicação ruim, uma revisão que deixou passar.
Ache a fronteira. Procure no trace um trecho com muitos turnos, muita leitura, e um resultado que cabe em poucas linhas. Esse é o candidato.
Defina o contrato de saída como um schema. O que o subagente devolve, em que formato, com fonte ou evidência.
Escreva o prompt do subagente com um papel só, e a lista mínima de ferramentas. Nunca a ferramenta de publicar, nem as do irmão. E dê a ele um orçamento próprio.
No agente principal, troque as ferramentas antigas por uma ferramenta que chama o subagente.
Registre o subagente como um span filho no trace, para ver o que ele leu sem trazer isso para o contexto principal.
E meça de novo. Qualidade igual ou melhor, menos tokens por turno no agente principal. O custo total pode subir um pouco, com uma chamada a mais de orquestração. Confira se o ganho de qualidade e de isolamento compensa.
Riscos
Agora, os riscos. Contexto que falta. O briefing dizia: não cite o concorrente X. O subagente de pesquisa nunca recebeu essa restrição e devolveu um fato do blog do X. O agente principal usou. De quem é a falha? Do agente principal. Não existe memória compartilhada. Tudo o que o subagente precisa vai na instrução.
Um resultado magro demais. Um resumo de três linhas pode perder o detalhe de que o agente principal precisava. Ajuste o schema a partir dos casos que falharam.
Multiplicação de agentes. Quatro subagentes para pesquisar, escrever o título, escrever o corpo e escolher um emoji é decorative multi-agent. Cada extração precisa de um motivo. Contexto que não pode misturar, ferramentas que não podem conviver, ou julgamento independente. E formatar uma data não conta. Isso é uma linha de código.
E recursão. Se o subagente de pesquisa pode abrir outro pesquisador, cada um com quinze passos novos e sem limite de profundidade, a árvore explode. Limite a profundidade e passe o mesmo orçamento para baixo.
E mais uma armadilha. A ferramenta de publicar continua na lista do agente principal, para casos urgentes. O subagente de pesquisa continua sem ela, então parece mais seguro. É mais seguro que antes. Mas o agente principal ainda pode publicar um rascunho cru, sem aprovação. E um prompt dizendo não publique sem revisão é justamente o que a gente está tentando deixar para trás. Ferramenta disponível vai ser usada, cedo ou tarde.
Prática
Vamos praticar. Um agente de incidentes lê logs, métricas e o runbook, e decide se reinicia um serviço. O que você extrairia, e o que deveria voltar?
Extraia a investigação. Um subagente de diagnóstico lê os logs e as métricas, que são grandes e não confiáveis, com ferramentas só de leitura. E devolve um relatório estruturado.
A causa provável. As evidências, cada uma com fonte e trecho. A confiança, baixa, média ou alta. E uma ação sugerida. Reiniciar, voltar versão, escalar ou nada.
O agente principal decide com base nesse relatório e no runbook. E o reinício em si fica fora dos dois agentes, atrás da aprovação de quem está de plantão, quando a confiança não é alta. Log cru nunca fica ao lado da ferramenta de reiniciar.
Fechamento
Então, a ideia para levar. Extraia um subagente onde o trabalho é pesado, não confiável, ou precisa de olhos novos. Dê a ele um papel, poucas ferramentas, orçamento próprio e tudo o que ele precisa na instrução. E faça ele devolver um contrato, não um parágrafo.
Na próxima aula, vamos olhar o padrão completo por trás dessa refatoração: subagent delegation. Até lá.
Extrair Subagente
Extract Subagent
Extrair Subagente (Extract Subagent) é uma refatoração de IA para sistemas com LLM, do grupo Movendo controle. Dar a uma tarefa grande um agente próprio, com contexto limpo e ferramentas só dela.
- Elemento
- 10/35
- Nível
- Avançado
- Leitura
- 5 min
- Atualizado
Problema
Um agente faz trabalho de natureza diferente no mesmo contexto: lê muito, produz, revisa e age. O contexto incha e as funções se contaminam. São os smells Mega-Agente, Contexto Podre e Rascunho Compartilhado.
O agente de conteúdo da fintech pesquisa Pix, lê 30 páginas, escreve o post, revisa o próprio texto contra o guia da marca e publica. No fim da tarefa o contexto mistura trechos de blog de concorrente, o raciocínio de quem escreveu (“usei este argumento porque o jurídico pediu”) e a ferramenta publish_post. O revisor herda o argumento do redator e deixa passar o que deveria barrar. Uma página com instrução escondida fica a um passo da publicação.
O destino desta extração é Delegação a Subagente com Isolamento de Contexto.
Solução
Dê a uma subtarefa grande e bem delimitada o seu próprio agente, com contexto limpo, prompt próprio e só as ferramentas de que ela precisa. O agente principal entrega uma instrução e recebe de volta só o resultado, num formato combinado.
Antes e depois
MAIN_TOOLS = [
- web_search, fetch_page, # pesquisa no contexto principal
read_brand_guide, write_draft, edit_draft,
- publish_post,
+ research, # subagente: devolve fatos com fonte
+ review, # subagente: devolve problemas encontrados
]
+
+def research(question: str) -> ResearchNotes:
+ return run_agent(RESEARCH_PROMPT, tools=[web_search, fetch_page],
+ task=question, budget=Budget(steps=15), output=ResearchNotes)
+
+def review(draft: str) -> ReviewReport:
+ return run_agent(REVIEW_PROMPT, tools=[read_brand_guide, check_plagiarism],
+ task=draft, budget=Budget(steps=6), output=ReviewReport)
+
+# publish_post saiu do agente: virou um passo de código depois da aprovaçãoAntes: um contexto para tudo.
flowchart TD
B(["1. Briefing"]):::io --> A(["2. Agente único"]):::llm
A --> W["3. 30 páginas lidas"]:::untrusted
W --> A
A --> R["4. Revisão do próprio texto"]:::tool
R --> A
A --> P["5. Publicar"]:::tool
Depois: subagentes com contexto próprio, e só o resultado volta.
flowchart TD
B(["1. Briefing"]):::io --> A(["2. Agente principal"]):::llm
A --> S1(["3. Subagente de pesquisa"]):::llm
S1 --> W["Páginas lidas"]:::untrusted
S1 -->|"fatos com fonte"| A
A --> S2(["4. Subagente de revisão"]):::llm
S2 -->|"lista de problemas"| A
A --> H((("5. Aprovação"))):::human
H --> P["Publicar"]:::tool
- O briefing chega ao agente principal.
- O principal planeja, escreve e decide. Ele não lê páginas da web.
- O subagente de pesquisa lê tudo num contexto próprio e devolve uma lista curta de fatos com fonte.
- O subagente de revisão recebe só o rascunho e o guia da marca, sem o raciocínio de quem escreveu.
- Publicar deixou de ser ferramenta do modelo e virou um passo depois da aprovação.
Exemplo trabalhado
Briefing: “post de 800 palavras sobre Pix para MEI, tom da marca, sem prometer rendimento”.
No antes, o agente busca, lê, anota, escreve e revisa no mesmo histórico. Perto da página 20, o começo do briefing compete com HTML de blog. “Lost in the Middle” (Liu et al., 2023) descreve essa perda de atenção. A ferramenta publish_post continua disponível enquanto o contexto está cheio de texto não confiável.
No depois, o principal chama research("Pix para MEI, fontes oficiais, 2026"). O subagente gasta 12 passos, lê as 30 páginas e devolve, por exemplo:
{
"facts": [
{ "claim": "MEI pode receber Pix na conta de pessoa física vinculada", "source": "bcb.gov.br/..." }
],
"open_questions": ["limite mensal vigente"]
}O principal escreve o rascunho a partir disso, sem o HTML. O subagente de revisão recebe o rascunho e o guia, e devolve { "problems": ["promete rendimento no parágrafo 4"] }. Publicar só roda depois da pessoa de marketing aprovar. O conteúdo da web nunca sentou ao lado da ferramenta de efeito.
Por que funciona
Um contexto é a memória de trabalho do modelo. Quando ele guarda 30 páginas lidas, o raciocínio de quem escreveu e as regras de revisão ao mesmo tempo, tudo compete pela atenção, e o conteúdo não confiável fica perto das ferramentas de efeito.
Separar devolve três propriedades. Foco: cada subagente tem um prompt de uma função e poucas ferramentas. Limpeza: o trabalho bruto (páginas, logs, arquivos) morre dentro do subagente, e o principal recebe uma página de resultado em vez de cem. Independência: o revisor não herda o raciocínio do redator, então julga o texto como ele está.
O formato do retorno é o contrato entre os dois. Sem ele, o principal recebe texto livre e precisa adivinhar o que veio. ResearchNotes com fatos e fontes é revisável; um parágrafo de “resumo da pesquisa” não é.
Cada subagente leva um orçamento próprio, descontado do total da tarefa. Sem isso, a extração vira Subagentes em Cascata. Veja Adicionar Orçamento ao Loop.
Passo a passo seguro
- Meça. Rode o eval do agente atual e guarde qualidade, custo por tarefa, tokens por volta no fim da tarefa e incidentes conhecidos (publicação indevida, revisão que não pega).
- Ache a fronteira. Procure no trace um trecho com muitas voltas, muita leitura e um resultado que cabe em poucas linhas. Esse é o candidato. Extrair um passo de uma linha (formatar data) não paga um subagente.
- Defina o contrato de saída como schema: o que o subagente devolve e em que formato. Inclua fontes ou evidências.
- Escreva o prompt do subagente com uma função só e a lista mínima de ferramentas. Sem
publish_post. Sem as ferramentas do irmão. - Dê orçamento próprio, descontado do orçamento total da tarefa.
- Troque, no principal, as ferramentas antigas por uma ferramenta que chama o subagente.
- Registre o subagente como span filho no trace, para ver o que ele leu sem levar isso ao contexto principal.
- Meça de novo. Qualidade igual ou melhor, tokens por volta menores no principal. O custo total pode subir um pouco (uma chamada a mais de orquestração); confira se o ganho de qualidade e de isolamento vale.
Erro comum: extrair demais
Um agente com quatro subagentes para “pesquisar”, “escrever título”, “escrever corpo” e “escolher emoji” é Multi-Agente Decorativo. Cada extração precisa de um motivo: contexto que não deve misturar, ferramentas que não devem coexistir, ou independência de julgamento. Título e corpo no mesmo redator costumam ser o mesmo trabalho.
Riscos
- Contexto que faltou. O subagente não sabe algo que só o principal sabia (uma restrição do usuário: “não citar concorrente X”). Passe na instrução tudo que ele precisa; não conte com memória compartilhada.
- Resultado pobre demais. Um resumo de três linhas pode perder o detalhe de que o principal precisava. Ajuste o schema com base nos casos que falharam.
- Multiplicação de agentes. Extrair demais leva ao Multi-Agente Decorativo. Cada subagente precisa de um motivo: contexto, ferramentas ou independência.
- Recursão. Se o subagente também pode criar subagentes, limite a profundidade e compartilhe o orçamento.
Desafio
Um agente de incidentes lê logs, métricas e o runbook, e depois decide se reinicia um serviço. Qual parte você extrairia, e o que ela deve devolver?
Ver solução
Extraia a investigação. Um subagente de diagnóstico lê logs e métricas (conteúdo grande e não confiável) com ferramentas só de leitura e devolve um relatório estruturado:
schema Diagnosis {
likely_cause: string
evidence: list[{ source: string, excerpt: string }]
confidence: "low" | "medium" | "high"
suggested_action: "restart" | "rollback" | "escalate" | "none"
}O agente principal decide com base no Diagnosis e no runbook. A ação de reiniciar fica fora dos dois agentes, atrás de aprovação do plantonista quando a confiança não é alta. Logs brutos não sentam ao lado de restart_service.
Teste seu entendimento
Checagem da aula
Responda as 6 perguntas para concluir a aula. Só assistir não conclui: a checagem é o que conta para a trilha e para o certificado.
Perguntas rápidas
Que problema Extrair Subagente resolve?
Trata Contexto Podre, Mega-Agente e Rascunho Compartilhado.
Aonde Extrair Subagente leva?
Ao padrão de projeto Delegação a Subagentes e Isolamento de Contexto.
Para ir além
Relações
- Smells que trata 3
- Padrões de destino 2
- Aparece nos cenários 4
- Aparece nas trilhas 1