Carregando ferramentas conforme necessário usando a pesquisa de ferramentas

A pesquisa de ferramentas mantém seu contexto pequeno, permitindo CLI do Copilot carregar ferramentas externas somente quando uma tarefa precisar delas.

Neste artigo

Introduction

Conectar servidores MCP e outras ferramentas externas CLI do Copilot é eficiente, mas cada ferramenta que você adiciona tem um custo: sua definição ocupa espaço na janela de contexto do modelo e um longo menu de ferramentas torna mais difícil para o agente escolher o certo. O carregamento de ferramentas sob demanda (ou "pesquisa de ferramentas") impede que a janela de contexto seja desordenada por definições de ferramentas que o agente não usa. O agente começa apenas com suas ferramentas internas e uma maneira de pesquisar o restante e, em seguida, carrega ferramentas extras somente quando são necessárias para concluir uma tarefa.

A pesquisa de ferramentas aborda dois problemas associados a um número crescente de ferramentas:

  • Contexto desperdiçado. Algumas dezenas de definições de ferramentas podem consumir entre 10 mil e 20 mil tokens antes mesmo de o agente realizar qualquer tarefa.
  • Precisão de seleção de ferramentas degradada. Quando várias dezenas de ferramentas estiverem visíveis ao mesmo tempo, será mais provável que o modelo use a ferramenta errada.

O que acontece durante uma sessão

Sempre que você insere um prompt, a CLI verifica o inventário de ferramentas atual e decide se deseja usar a pesquisa de ferramentas. Com menos de cerca de 30 ferramentas, a economia obtida com a busca de ferramentas não compensa, então CLI do Copilot simplesmente ignora a busca de ferramentas e carrega tudo.

Inicialmente, quando a pesquisa de ferramentas é usada, somente as ferramentas internas da CLI são carregadas. Todo o resto — ferramentas MCP e outras ferramentas externas — fica bloqueado. O agente pode ver que essas ferramentas existem e mais ou menos para que servem, mas suas definições completas ainda não foram carregadas.

Quando o agente chega a uma etapa que exige uma ferramenta que ele não tem carregada, ele faz uma busca rápida entre as ferramentas disponíveis e traz as correspondências mais relevantes para o contexto. Essas ferramentas permanecem disponíveis pelo restante da conversa, de modo que a consulta só acontece na primeira vez que cada ferramenta é necessária.

Essa primeira consulta custa uma interação extra com o modelo, mas esse custo é compensado muitas vezes ao manter o contexto enxuto em cada turno seguinte.

Ferramentas que são sempre carregadas

Algumas ferramentas ignoram a pesquisa de ferramentas e estão prontas imediatamente:

A pesquisa de ferramentas é habilitada por padrão e é ativada automaticamente sempre que você estiver em um modelo com suporte e tiver ferramentas conectadas suficientes para fazer valer a pena. Para desabilitar a pesquisa de ferramentas e voltar a carregar todas as ferramentas, defina toolSearch: false em suas configurações pessoais. Consulte Diretório de configuração do GitHub Copilot CLI.

Modelos com suporte

FamíliaVersões suportadas
Claude (Antropo)Prévia do Mythos, Fable, Sonnet 4.0+, Opus 4.0+ (não Haiku)
GPT (OpenAI)GPT-5.4 e posteriores

Em qualquer outro modelo, todas as ferramentas são carregadas antecipadamente.

Manter as ferramentas de um servidor MCP sempre carregadas

Às vezes, talvez você queira que as ferramentas de um determinado servidor MCP estejam sempre na frente do agente, por exemplo, um servidor cujas ferramentas são usadas constantemente ou uma em que a etapa de pesquisa extra não vale a pena. Cada servidor MCP tem uma deferTools configuração que controla isso:

  • "auto" (o padrão)—as ferramentas do servidor se comportam como quaisquer outras e podem ser postergadas depois que você ultrapassar o limite.
  • "never"— as ferramentas do servidor são sempre incluídas na lista de ferramentas do agente, mesmo quando a pesquisa de ferramentas está ativa para todo o resto.

A maneira mais fácil de defini-lo é usando o /mcp edit comando barra. No formulário para editar o servidor MCP, alterne As Ferramentas de Adiamento para Nunca. Você também pode defini-lo diretamente em ~/.copilot/mcp-config.json:

{
    "mcpServers": {
        "my-server": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@example/mcp-server"],
            "deferTools": "never",
            "tools": ["*"]
        }
    }
}

Configurando o adiamento do uso de ferramentas em agentes personalizados

Quando um agente personalizado lista suas ferramentas pelo nome, essas ferramentas são sempre carregadas para que o agente possa usá-las imediatamente. Geralmente é o que você deseja, mas se um agente declarar um grande conjunto de ferramentas e tocar apenas algumas delas em uma determinada execução, você poderá devolver essa lista à pesquisa de ferramentas para que as ferramentas sejam descobertas conforme necessário, em vez de todas carregadas de uma só vez.

Para um agente Markdown (.github/agents/*.md), adicione deferred-tool-loading: true ao frontmatter:

---
name: my-agent
description: Works with a large catalog of tools
tools:
    - some_mcp_tool
    - another_mcp_tool
    # ...many more
deferred-tool-loading: true
---

Agent instructions here.

Tenha em mente o seguinte sobre a configuração deferred-tool-loading:

  • Ele só tem um efeito quando a pesquisa de ferramentas está ativa (ou seja, em um modelo com suporte com ferramentas suficientes para ultrapassar o limite).
  • Isso só importa para agentes que dão nome às suas ferramentas. Os agentes que usam o caractere curinga * já usam a busca de ferramentas.

A busca de ferramentas compara o que o agente está tentando fazer com o nome de cada ferramenta, sua descrição e seus nomes e descrições de parâmetros. Uma redação clara e específica faz com que uma ferramenta apareça para as solicitações certas:

  • Dê nomes às ferramentas de acordo com o que fazem para que sejam mais fáceis de encontrar.
  • Escreva descrições com as palavras que as pessoas realmente procurariam em vez de vagas.