Intensivo Grátis 21–22/11Intensivo gratuito de 2 dias em Vibecoding (21–22/11 às 16:00 MSK) · Turma 3 começa 23/11Inscrever-se grátis →Turma 3 (23/11)
LançamentoAPI / Produto · Pronto p/ usoHabr AI→ original

Duas ferramentas no lugar de 2.500 métodos de API: como um agente de IA evita gastar 1,17 milhão de tokens de contexto

O MCP é um meio de conectar serviços a um agente de IA, mas as descrições de centenas de métodos ocupam o contexto, ou seja, a memória de trabalho do modelo. Na Cloudflare, os 2.500 métodos de API somariam cerca de 1,17 milhão de tokens (unidades de texto). Com o Code Mode, o agente fica com apenas duas ferramentas: search() encontra o método e execute() roda uma cadeia de chamadas por meio de código. Para que o modelo não deixe de buscar, o autor acrescentou SKILLs, instruções curtas com os nomes dos métodos necessários.

Processado por IA de Habr AI; editado por Hamidun News
Duas ferramentas no lugar de 2.500 métodos de API: como um agente de IA evita gastar 1,17 milhão de tokens de contexto
Fonte: Habr AI. Colagem: Hamidun News.
Ouvir artigo
Ficha técnica e números-chave
ParâmetroDados
Fonte originalHabr AI ↗
Editor-chefe
Sem o Code Modeos 2.500 métodos da Cloudflare somam cerca de 1,17 milhão de tokens
Dado-chave #2Uma única chamada a execute() executa uma cadeia de etapas sem retornar ao modelo
O autor não mediu a economiasão necessárias medições nas suas próprias tarefas

Imagine contratar um assistente e, antes de cada tarefa, ler para ele as instruções de todos os 2.500 botões de um controle remoto. O trabalho nem chega a começar: ele se cansa de ouvir.

Mais ou menos assim sofrem os agentes de IA quando se conectam muitos serviços por meio do MCP (Model Context Protocol, padrão pelo qual o agente chama ferramentas externas). A descrição de cada método entra no contexto, ou seja, na memória de trabalho do modelo, e é medida em tokens: assim se chamam os pedaços de texto pelos quais se paga e que limitam o volume da requisição. O desenvolvedor, autor da análise publicada no Habr, enfrentou isso em duas tarefas ao mesmo tempo: na configuração de seu agente pessoal, o Nanabot, e na criação de um servidor MCP para gerenciar produtos da empresa.

A receita dele combina o Code Mode MCP com SKILLs.

Qual é o problema com centenas de ferramentas

No esquema tradicional do MCP, o cliente envia ao modelo as descrições de todas as ferramentas conectadas. A Cloudflare tem mais de 2.500 métodos de API e estima que a descrição completa deles como ferramentas MCP ocuparia cerca de 1,17 milhão de tokens. Essa é uma estimativa da própria Cloudflare, e não uma medição feita pelo autor do artigo.

A empresa propôs o Code Mode MCP. Em vez de milhares de ferramentas, o agente recebe duas. A primeira, search(), encontra os métodos necessários e devolve suas assinaturas (nomes, parâmetros e campos obrigatórios) de acordo com a consulta. A segunda, execute(), roda um código JavaScript que chama esses métodos. Uma única chamada a execute() pode reunir várias operações e devolver o resultado final, sem que seja preciso recorrer ao modelo de linguagem após cada etapa.

O artigo traz um exemplo simples: pede-se ao agente que "abra example.com e faça uma captura de tela". Por meio de search(), ele encontra navigate_page e take_screenshot e, então, com um único script, abre a página e tira a captura. Entre essas duas etapas não há nova requisição ao modelo. Uma ressalva importante: no artigo, a busca em um array de ferramentas aparece como uma das variantes do agregador. A Cloudflare, por exemplo, procura operações na especificação OpenAPI.

O esquema também tem pontos fracos. A economia não é garantida: as buscas repetidas e o carregamento das assinaturas também consomem tokens. O tamanho do ganho depende do tamanho do catálogo, da frequência das buscas e do número de chamadas. Para uma estimativa precisa, são necessárias medições em tarefas concretas. Além disso, o modelo às vezes não encontra o método certo e, outras vezes, nem percebe que deveria buscar algo.

Como as SKILLs fecham a lacuna

A Cloudflare recomenda usar SKILLs junto com o MCP: a SKILL explica ao agente quando e quais recursos aplicar. O autor seguiu o mesmo caminho. Ele escondeu muitos servidores MCP atrás do Code Mode, de modo que o modelo enxerga um único servidor com busca e execução. Na SKILL, ele incluiu uma lista curta dos servidores e métodos necessários, sem as descrições completas.

Eis um exemplo prático: a SKILL bugfix-process. O usuário escreve: "Corrija o bug 731 no repositório two-server, na branch atual, e execute a build two_jar_java17". Então o agente age da seguinte forma:

  • vê no contexto permanente a descrição curta da SKILL e entende que ela se aplica;
  • lê a própria SKILL e identifica a ordem das etapas e os servidores ticket_mcp, samba_mcp, filesystem_mcp, git_mcp, codex_mcp e jenkins_mcp;
  • usa search() para solicitar as assinaturas apenas dos métodos necessários, por exemplo get_ticket ou download_attachment;
  • usa execute() para reunir o ticket, os comentários, os anexos e os logs do Samba na pasta tickets/731/;
  • faz commit somente dessa pasta, para que o material não se misture com a futura correção;
  • inicia o Codex via start_task, aguarda o resultado, verifica o diff e envia a correção ao repositório;
  • executa o Jenkins e define o status do ticket como Resolve ou In Progress, e depois escreve o relatório em result.fixed.md ou result.in-progress.md.

Há mais uma economia aqui. Logs e anexos grandes ficam no disco e não passam pelo contexto do agente principal. O Codex lê esses arquivos pelo caminho indicado e pega apenas o necessário. O agente principal atua como organizador e delega a programação em si.

Três camadas de contexto e limitações

A arquitetura final tem três camadas. O contexto permanente contém as descrições curtas das SKILLs e as duas ferramentas do Code Mode. A SKILL é carregada quando se aproxima da tarefa e guarda o algoritmo e os nomes dos métodos. O Code Mode, sob demanda, obtém as assinaturas completas e executa as chamadas. Antes, a escolha era entre dois maus caminhos: carregar tudo e gastar tokens, ou esconder tudo e torcer para que o modelo adivinhasse. Agora existe um terceiro.

As limitações permanecem. O modelo ainda pode não escolher a SKILL certa, errar na busca do método ou escrever JavaScript incorreto. Nem toda cadeia pode ser reduzida a uma única chamada: às vezes o agente precisa analisar um resultado intermediário e tomar uma nova decisão. O autor não apresenta números de economia para os próprios cenários, apenas a estimativa de que ela é provável.

A conclusão prática para as equipes: se vocês têm muitas ferramentas internas (tickets, CI, git, armazenamento de arquivos), não descrevam todas no prompt de sistema. Descrevam os processos em SKILLs curtas, deem ao agente a busca por assinaturas e a execução de scripts. Antes de implantar, meçam o consumo de tokens em tarefas reais; do contrário, o benefício terá de ser aceito por fé.

História

Perguntas frequentes sobre a notícia

O que se sabe sobre Qual é o problema com centenas de ferramentas?

No esquema tradicional do MCP, o cliente envia ao modelo as descrições de todas as ferramentas conectadas. A Cloudflare tem mais de 2.500 métodos de API e estima que a descrição completa deles como ferramentas MCP ocuparia cerca de 1,17 milhão de tokens. Essa é uma estimativa da própria Cloudflare, e não uma medição feita pelo autor do artigo. A empresa propôs o Code Mode MCP. Em vez de milhares de ferramentas, o agente recebe duas.

Como as SKILLs fecham a lacuna?

A Cloudflare recomenda usar SKILLs junto com o MCP: a SKILL explica ao agente quando e quais recursos aplicar. O autor seguiu o mesmo caminho. Ele escondeu muitos servidores MCP atrás do Code Mode, de modo que o modelo enxerga um único servidor com busca e execução. Na SKILL, ele incluiu uma lista curta dos servidores e métodos necessários, sem as descrições completas. Eis um exemplo prático: a SKILL bugfix-process.

O que se sabe sobre Três camadas de contexto e limitações?

A arquitetura final tem três camadas. O contexto permanente contém as descrições curtas das SKILLs e as duas ferramentas do Code Mode. A SKILL é carregada quando se aproxima da tarefa e guarda o algoritmo e os nomes dos métodos. O Code Mode, sob demanda, obtém as assinaturas completas e executa as chamadas. Antes, a escolha era entre dois maus caminhos: carregar tudo e gastar tokens, ou esconder tudo e torcer para que o modelo adivinhasse. Agora existe um terceiro. As limitações permanecem.

ZK
Zhemal Khamidun — CPO da Alpina Digital, gerente de produto do AlpinaGPT. Cria produtos de IA desde 2019. O Hamidun News é um projeto pessoal que virou um agregador em produção com mais de 6.000 leitores.
✦ Hands-On AI Engineering · Hamidun Academy

Build & Ship Production AI Agents Without Boilerplate Code

Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.

Start 72h Free Trial →Vibe-Coding Intensive
O que você acha?
Carregando comentários…