Revelação Progressiva

Intenção

Mostrar ao modelo só um resumo curto de cada habilidade, ferramenta ou documento disponível, e carregar os detalhes completos quando ele pedir. Serve para agentes com muitas capacidades, em que carregar tudo em toda chamada enche o contexto e confunde a escolha.

Problema

Gabriel mantém um agente de back-office que sabe fazer muitas coisas: conciliar extratos, emitir notas fiscais (NF-e), gerar relatórios de comissão, abrir chamados em transportadoras, atualizar cadastro de fornecedores. Cada capacidade tem instruções detalhadas (passo a passo, exceções, formatos), exemplos e ferramentas próprias.

Com tudo no prompt, o contexto inicial de cada tarefa passa de 40 mil tokens. A maior parte é irrelevante para a tarefa da vez. O agente confunde as regras da conciliação com as da emissão de notas, e cada chamada custa caro antes de fazer qualquer coisa.

Isso aparece no trace como Prompt Inchado: páginas de procedimento que não serão usadas. Também aparece como escolha errada de ferramenta, irmã de Ferramentas Demais.

Um roteador que escolhe o grupo no início ajuda, mas algumas tarefas descobrem no meio do caminho que precisam de outra capacidade. “Concilia o cartão e, se faltar nota, emite a NF-e” começa num assunto e termina noutro.

A pergunta que este padrão responde: como um agente tem acesso a muitas capacidades sem carregar todas no contexto o tempo todo?

Solução

Organize as capacidades em dois níveis:

• Índice: para cada capacidade, um nome e uma ou duas frases sobre quando usar. É tudo que entra no contexto inicial.
• Detalhe: instruções completas, exemplos, scripts e ferramentas, guardados fora do contexto.

O agente recebe o índice e uma ferramenta para carregar o detalhe (load_skill(name)). Quando decide que precisa de uma capacidade, carrega e segue. Detalhes podem ter mais níveis: o arquivo principal aponta para arquivos de referência, carregados só se necessários.

O mesmo vale para ferramentas: a lista inicial traz nomes e descrições curtas, e as definições completas são carregadas sob demanda. Alguns provedores oferecem isso nativamente, com busca de ferramentas.

Exemplo trabalhado

O índice que Gabriel coloca no system prompt cabe numa tela:

Habilidades (carregue com load_skill antes de executar):
- conciliacao-cartao: use para bater recebimentos de cartão com o extrato e dar baixa no título.
- emissao-nf: use para emitir, cancelar ou consultar NF-e.
- comissao: use para calcular e exportar comissão de vendedores.
- logistica: use para abrir chamado em transportadora ou consultar rastreio.

A tarefa chega: “Concilie os recebimentos do cartão de ontem”. O agente chama load_skill("conciliacao-cartao") e só então vê o passo a passo, os códigos de ocorrência da adquirente e a ferramenta baixar_titulo. A habilidade de NF-e nem entra.

A conta, ilustrativa. Doze habilidades com 3.000 tokens cada somam 36 mil tokens em toda volta. O índice das doze ocupa uns 400 tokens. Carregar uma habilidade acrescenta 3.000 uma vez. Num loop de seis voltas, você sai de uns 216 mil tokens de instrução para uns 22 mil. O preço é uma volta a mais, a do load_skill.

A descrição curta é o contrato. Se todas dizem “útil no back-office”, o agente carrega as doze. Se cada uma diz o verbo da tarefa (“bater recebimentos de cartão”), ele acerta.

Estrutura

flowchart TD
  T(["1. Tarefa"]):::io --> A(["2. Agente com o índice"]):::llm
  IDX[("Índice: nome e quando usar")]:::store --> A
  A -->|"preciso de conciliação"| L["3. load_skill"]:::tool
  SK[("Habilidades completas")]:::store --> L
  L --> A
  A --> TL["4. Ferramentas da habilidade"]:::tool
  TL --> A
  A --> OUT(["5. Resultado"]):::io

1. A tarefa chega.
2. O agente começa com o índice curto de todas as capacidades.
3. Quando precisa de uma, carrega as instruções completas.
4. As ferramentas daquela capacidade passam a estar disponíveis.
5. O resultado sai, com o contexto carregando só o que foi usado.

Pseudocódigo

schema SkillIndexEntry { name: string, when_to_use: string }

INDEX = skills.index()                                  # algumas linhas por habilidade
tool load_skill(name) -> { instructions: string, tools: list[Tool] }

function run(task):
    state.system = BASE_PROMPT + render(INDEX)          # 2
    tools = [load_skill]
    while budget.check():
        reply = llm_with_tools(state.system, tools, state)
        if reply.is_final: return reply.text            # 5
        for call in reply.tool_calls:
            if call.name == "load_skill":
                skill = skills.load(call.args.name)     # 3
                state.add(observation(call, skill.instructions))
                tools += skill.tools                    # 4
                trace.span("skill_loaded", call.args.name)
            else:
                state.add(execute(call))

Cenários reais

• Agente de código. Instruções de como rodar testes, padrões do repositório e procedimentos de release ficam em arquivos carregados só quando a tarefa toca aquele assunto.
• Automação de back-office com execução durável. Cada processo (conciliação, emissão de NF-e, cobrança) é uma habilidade com instruções e ferramentas próprias, carregada quando o agente chega àquela etapa.

Aplicabilidade

• O agente tem muitas capacidades, cada uma com instruções longas.
• A maior parte das tarefas usa poucas capacidades.
• A tarefa pode descobrir no caminho que precisa de outra capacidade.
• O contexto inicial está grande demais e caro.

Quando não usar

• Poucas capacidades, com instruções curtas. Coloque tudo no prompt.
• O assunto é sempre conhecido no início. Um Roteador de Ferramentas decide uma vez, sem depender do modelo pedir.
• O que precisa ser carregado é conhecimento factual para responder perguntas. Isso é RAG.

Como implementar

1. Separe cada capacidade num pacote: instruções, exemplos, ferramentas, referências.
2. Escreva para cada uma uma descrição curta, focada em quando usar.
3. Coloque o índice no prompt do agente e a ferramenta de carregar.
4. Faça o carregamento acrescentar instruções e ferramentas ao contexto, sem tirar o que já está lá (para não invalidar o cache).
5. Registre no trace quais capacidades cada tarefa carregou.
6. Avalie: o agente carrega a capacidade certa? Carrega sem necessidade?
7. Revise descrições do índice quando o eval mostrar escolhas erradas.

Armadilhas comuns

• Descrição genérica. “Útil no back-office” não discrimina. O verbo da tarefa discrimina.
• Carregar substituindo o prompt. Se você troca o system prompt, o cache do prefixo some. Acrescente no fim.
• Índice desatualizado. Habilidade nova no disco sem linha no índice é habilidade invisível. Gere o índice a partir dos arquivos.
• Tratar habilidade como RAG. Busca devolve um parágrafo. Procedimento precisa ser seguido inteiro. RAG é para fato; revelação é para modo de operação.

Variações

• Habilidades em arquivos. Pastas com um arquivo principal e referências, lidas pelo agente com ferramentas de leitura. Simples e versionável.
• Busca de ferramentas pelo provedor. As ferramentas são marcadas para carregamento tardio e o modelo busca as que precisa.
• Vários níveis. O índice aponta para habilidades, que apontam para referências, carregadas uma por uma.
• Pré-carregamento por rota. Um roteador carrega a habilidade mais provável no início, e o agente ainda pode pedir outras.

Custo, latência e falhas

Como avaliar

• Escolha correta: em tarefas com a habilidade necessária conhecida, ela foi carregada?
• Carregamentos desnecessários por tarefa.
• Qualidade e custo comparados com o prompt com tudo carregado.

{ "task": "Concilie os recebimentos do cartão de ontem", "expected_skills": ["conciliacao-cartao"], "unexpected_skills": ["emissao-nf"] }

Inclua tarefas que cruzam habilidades de propósito (“concilia e, se faltar, emite a nota”). O agente certo carrega a segunda no meio do caminho, não as duas no primeiro passo.

Em produção

• Span por carregamento, com o nome da habilidade e o tamanho.
• Painel de uso por habilidade: as nunca carregadas podem sair do índice ou ganhar uma descrição melhor.
• Alerta para tarefas que carregam muitas habilidades.

Prós e contras

Relações

• Smells que cura: Prompt Inchado e, em parte, Ferramentas Demais, quando o volume é de instruções e definições.
• Refatoração vizinha: Consolidar Ferramentas vem antes, se houver duplicata. Roteador de Ferramentas escolhe o grupo no início; revelação deixa o próprio agente abrir mais no caminho.
• Não confundir com: RAG, que busca fatos. Aqui o que se revela é um procedimento que o agente deve seguir.

Código

A aba Python monta o índice de habilidades a partir de arquivos e dá ao agente uma ferramenta para carregar o detalhe; a aba TypeScript usa a busca de ferramentas do provedor para listas grandes.

from pathlib import Path

import yaml

SKILLS_DIR = Path("skills")  # skills/conciliacao-cartao/SKILL.md, skills/emissao-nf/SKILL.md, ...


def read_skill(path: Path) -> tuple[dict, str]:
    raw = path.read_text(encoding="utf-8")
    _, front, body = raw.split("---", 2)  # cabeçalho YAML com name e when_to_use
    return yaml.safe_load(front), body.strip()


def skill_index() -> str:  # 2. só nome e quando usar
    lines = []
    for f in sorted(SKILLS_DIR.glob("*/SKILL.md")):
        meta, _ = read_skill(f)
        lines.append(f"- {meta['name']}: {meta['when_to_use']}")
    return "Habilidades disponíveis (carregue com load_skill antes de usar):\n" + "\n".join(lines)


LOAD_SKILL = {
    "name": "load_skill",
    "description": "Carrega as instruções completas de uma habilidade do índice. Use antes de executar a tarefa daquela habilidade.",
    "input_schema": {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]},
}


def load_skill(name: str) -> str:  # 3
    path = SKILLS_DIR / name / "SKILL.md"
    if not path.exists():
        return f"Habilidade '{name}' não existe. Consulte o índice."
    _, body = read_skill(path)
    return body  # as ferramentas da habilidade são acrescentadas à lista pelo loop

SYSTEM = "Você é o agente de back-office.\n\n" + skill_index()

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

// Dezenas de ferramentas: só a de busca fica visível desde o início;
// as outras são carregadas quando o modelo as encontra pela busca.
const tools = [
  { type: "tool_search_tool_bm25_20251119", name: "tool_search_tool_bm25" },
  ...ALL_BACKOFFICE_TOOLS.map((t) => ({ ...t, defer_loading: true })),
];

export async function step(messages: Anthropic.MessageParam[]) {
  return client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 8000,
    system: "Você é o agente de back-office. Procure a ferramenta certa antes de agir.",
    tools: tools as Anthropic.Messages.ToolUnion[],
    messages,
  });
}

Teste seu entendimento