Ajustar o contexto de ferramentas de um agente

Este guia aborda o trabalho prático em torno da superfície de ferramentas em dois níveis: ver o que uma execução envia, alterá-la e diagnosticar um agente que recorreu à ferramenta errada. Para saber porque funciona assim, leia Contexto de ferramentas e cache de prompts.

Ver o que uma execução envia de facto

Abra uma conversa e toque no indicador de utilização de contexto no cabeçalho da conversa. Este reconstrói a superfície exata que o próximo despacho enviaria, sem executar nada. Ver mais (ou o comando /context) abre o explorador de contexto completo, onde pode inspecionar cada ferramenta.

Dois segmentos interessam aqui:

• Definições de ferramentas e MCP e ferramentas dinâmicas — o conjunto residente, com o custo real em tokens de cada ferramenta.
• Ferramentas carregadas a pedido — o índice diferido. A cada entrada só é cobrado o nome, porque é tudo o que o pedido transporta; abrir uma mostra ainda a descrição e o esquema completos, para que possa ver o que custaria se a execução a fosse buscar.

Se o segmento diferido estiver vazio, o diferimento está desativado neste servidor. Verifique --tool-deferral na CLI do cc_server.

Alterar que ferramentas são carregadas de antemão

O conjunto residente é política, não configuração — vive em ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) e aplica-se a todas as execuções:

• residentBuiltins — o vocabulário de ficheiros e shell.
• residentDiscovery — search_tools e list_my_tools. Não as remova; são a forma como um agente chega a tudo o resto.
• residentMcpTools — o punhado de ferramentas do Control Center que valem o seu esquema em cada pedido.
• Um bloco por modo, para as ferramentas que um determinado modo usa em quase todos os turnos.

Duas regras ao editá-lo:

Adicione uma ferramenta apenas se a maioria das execuções a utilizar. Cada nome custa o seu esquema em todos os pedidos de todas as execuções, para sempre. Uma ferramenta que é importante quando é usada, mas rara no conjunto, pertence à metade diferida — o agente continuará a encontrá-la.

Use o nome real da ferramenta. Um nome residente que não corresponde a nenhuma ferramenta é inerte: sem erro, sem aviso, a ferramenta fica simplesmente diferida. test/tooling/resident_tool_names_test.dart deteta isto e mantém ainda cada modo abaixo das 40 ferramentas residentes, que é o objetivo do exercício — acima dessa faixa, a seleção de ferramentas degrada-se de forma mensurável.

Os verbos obrigatórios e fixados de um modo são adicionados automaticamente, pelo que nunca precisa de listar o próprio verbo de saída de um modo.

Diagnosticar uma má escolha de ferramenta

Quando um agente usou a ferramenta errada ou afirmou que não conseguia fazer algo, determine qual de três coisas aconteceu.

1. Procurou?

Cada execução regista as ferramentas diferidas que carregou e o que o desencadeou — uma chamada direta pelo nome ou uma consulta ao search_tools. Abra o fluxo de eventos da execução (Definições → Espaço de trabalho → Agentes → o agente → Registos → Visualizar) e procure [harness] loaded N deferred tool(s).

• Nada registado, e o agente disse que a capacidade não existia — nunca procurou. Isso é um problema de prompt, não de recuperação: o índice diferido está no seu prompt de sistema com a instrução de não declarar uma capacidade em falta enquanto uma pesquisa não tiver voltado vazia.
• Uma pesquisa registada, mas nada carregado — uma falha de recuperação genuína. Avance para o passo 2.
• Ferramentas carregadas, mas usada a errada — as ferramentas que encontrou são demasiado parecidas. Avance para o passo 3.

2. Corrigir uma falha de recuperação

O search_tools faz corresponder nomes, descrições e nomes de argumentos. Uma falha significa quase sempre que a descrição não contém as palavras que o agente usou.

Acrescente-as. As descrições são o índice de recuperação, pelo que deve alongá-las em vez de as encurtar — escreva o vocabulário que um operador escreveria de facto («atribuir», «passar», «dar a»), e não apenas o substantivo interno. Encurtar uma descrição para poupar tokens custa-lhe tanto o acerto da pesquisa como a precisão da seleção e poupa quase nada em comparação com o esquema.

Se a ferramenta certa existe mas aparece numa posição baixa, é para isso que serve o argumento limit; a própria descrição da ferramenta diz ao agente para ampliar uma pesquisa que parece próxima mas falha.

3. Corrigir ferramentas parecidas

Se duas ferramentas têm descrições que soariam iguais a alguém que ainda não conhece a diferença, o modelo está a adivinhar. Una-as numa única ferramenta com um argumento discriminador.

O ticket_relation e o ticket_pr_link seguem este padrão: cada um trata da associação e da desassociação através de um argumento discriminador. Uma escolha feita dentro de uma chamada, com o contexto completo do pedido, é mais fiável do que uma escolha feita entre duas descrições parecidas.

Mantenha as ferramentas separadas quando precisam de um controlo de aprovação diferente, de uma auditoria diferente ou de uma renderização diferente — são razões pelas quais uma fusão lhe custaria algo real.

Verificar se a cache de prompts está a funcionar

A taxa de acerto da cache aparece em Observabilidade → Resumo como Taxa de cache. Uma conversa longa e saudável mantém-se alta; se estiver persistentemente baixa, algo está a reescrever o prefixo em todos os turnos.

Causas comuns, por ordem de probabilidade:

• Qualquer coisa não determinística no início do prompt. Um timestamp, um id de pedido ou um conjunto iterado por ordem variável chega para o provocar.
• Uma mudança de modelo ou de esforço a meio da conversa. Ambas alteram o prefixo. Os subagentes são especialmente fáceis de errar aqui: executar os filhos com um esforço mais baixo para poupar dinheiro pode custar mais em partilha de cache perdida do que aquilo que poupa.
• Compactação frequente. A compactação reescreve o histórico por conceção, pelo que o seu custo é real; a solução é compactar raramente e em profundidade, em vez de frequentemente e superficialmente.

Desativar o diferimento com --tool-deferral=off é um teste A/B válido para isolar se uma mudança de comportamento veio da superfície em dois níveis. Reproduz exatamente o pedido anterior ao diferimento, pelo que, se o comportamento persistir com o diferimento desativado, a superfície não é a causa.