Detalhes da API de Ferramentas do Claude Code Revelados

Estrutura da API de Ferramentas do Claude Code

Um usuário do Reddit documentou sua conversa com o Claude Code sobre sua API de ferramentas interna. O assistente de IA revelou detalhes específicos sobre como ele interage com o ambiente.

Categorias e Funções das Ferramentas

Ferramentas do Sistema de Arquivos:

• Read — lê arquivos por caminho absoluto, retorna conteúdo com números de linha (estilo cat -n). Suporta imagens, PDFs, notebooks Jupyter.
• Write — sobrescreve ou cria arquivos. Deve Ler primeiro antes de Escrever em arquivos existentes.
• Edit — realiza substituição cirúrgica de strings. Requer que o old_string seja único no arquivo, caso contrário falha. Deve Ler primeiro.
• Glob — encontra arquivos por padrão (ex: *.py), ordenados por tempo de modificação.
• Grep — busca de conteúdo baseada em ripgrep. Suporta regex, filtros de tipo de arquivo e linhas de contexto.

Ferramentas de Execução:

• Bash — executa comandos shell com tempo limite padrão de 2 minutos (até 10 minutos). O diretório de trabalho persiste entre chamadas, mas o estado do shell não é mantido (sem variáveis de ambiente, aliases, etc.). Tem uma opção run_in_background.

Ferramentas Web:

• WebFetch — busca conteúdo de URL.
• WebSearch — pesquisa na web.

Agentes de IA:

• Agent — cria subagentes (propósito geral, Explore, Plan, etc.) com seu próprio acesso a ferramentas e contexto. Pode executar em segundo plano. Retorna uma única mensagem quando concluído.

Ferramentas Especiais:

• Skill — invoca "skills" nomeados (comandos de barra como /commit) que se expandem em prompts completos.
• ToolSearch — busca esquemas para "ferramentas adiadas" (ferramentas conhecidas por nome, mas que não podem ser chamadas até que seu esquema seja buscado).

Detalhes Principais de Implementação

Estrutura da Chamada de Ferramenta: O Claude Code não usa tokens especiais para acionar ferramentas — é uma API padrão de chamada de função. A resposta inclui blocos estruturados de chamada de ferramenta, e os resultados retornam como mensagens de resultado de ferramenta.

Formato da Chamada de Ferramenta: Os blocos usam sintaxe semelhante a XML com um wrapper antml:function_calls contendo um ou mais elementos antml:invoke com o nome da ferramenta como atributo. Cada parâmetro é um elemento antml:parameter com um atributo name e o valor como conteúdo de texto.

Exemplo de estrutura para uma chamada Bash:

• Tag externa: antml:function_calls
• Tag interna: antml:invoke com atributo name="Bash"
• Tag de parâmetro: antml:parameter com name="command" contendo o texto do comando

Comportamentos Operacionais

• Interações com Linter: Ao editar arquivos, hooks do git ou "hooks" configurados podem ser executados automaticamente após chamadas de ferramenta e modificar arquivos adicionalmente. O resultado da ferramenta indica "arquivo foi modificado por outro processo", exigindo releitura antes de editar novamente.
• Visibilidade da chamada de ferramenta: Toda chamada de ferramenta aparece no terminal para aprovação do usuário (dependendo do modo de permissão). Usuários podem negar qualquer chamada de ferramenta.
• Execução paralela: Múltiplas chamadas de ferramenta podem ser emitidas em uma única resposta e executar simultaneamente, útil para ler vários arquivos de uma vez.
• Gerenciamento de contexto: Conversas longas são comprimidas automaticamente — mensagens anteriores são resumidas para liberar contexto. A persistência da memória ocorre através de uma estrutura de diretório: /home/tpreal/.claude/projects/...