Detalles de la API de Herramientas de Claude Code Revelados

Estructura de la API de Herramientas de Claude Code

Un usuario de Reddit documentó su conversación con Claude Code sobre su API de herramientas interna. El asistente de IA reveló detalles específicos sobre cómo interactúa con el entorno.

Categorías y Funciones de Herramientas

Herramientas del Sistema de Archivos:

• Read — lee archivos por ruta absoluta, devuelve contenido con números de línea (estilo cat -n). Soporta imágenes, PDFs, cuadernos de Jupyter.
• Write — sobrescribe o crea archivos. Debe Leer primero antes de Escribir en archivos existentes.
• Edit — realiza reemplazos de cadenas quirúrgicos. Requiere que old_string sea único en el archivo, de lo contrario falla. Debe Leer primero.
• Glob — encuentra archivos por patrón (ej., *.py), ordenados por tiempo de modificación.
• Grep — búsqueda de contenido basada en ripgrep. Soporta regex, filtros de tipo de archivo y líneas de contexto.

Herramientas de Ejecución:

• Bash — ejecuta comandos de shell con un tiempo de espera predeterminado de 2 minutos (hasta 10 minutos). El directorio de trabajo persiste entre llamadas, pero el estado del shell no se mantiene (sin variables de entorno, alias, etc.). Tiene una opción run_in_background.

Herramientas Web:

• WebFetch — obtiene contenido de URL.
• WebSearch — busca en la web.

Agentes de IA:

• Agent — genera subagentes (de propósito general, Explore, Plan, etc.) con su propio acceso a herramientas y contexto. Puede ejecutarse en segundo plano. Devuelve un solo mensaje cuando termina.

Herramientas Especiales:

• Skill — invoca "habilidades" nombradas (comandos de barra como /commit) que se expanden en prompts completos.
• ToolSearch — obtiene esquemas para "herramientas diferidas" (herramientas conocidas por nombre pero que no se pueden llamar hasta que se obtiene su esquema).

Detalles Clave de Implementación

Estructura de Llamadas a Herramientas: Claude Code no usa tokens especiales para activar herramientas — es una API estándar de llamadas a funciones. La respuesta incluye bloques estructurados de llamadas a herramientas, y los resultados regresan como mensajes de resultado de herramientas.

Formato de Llamada a Herramientas: Los bloques usan sintaxis similar a XML con un envoltorio antml:function_calls que contiene uno o más elementos antml:invoke con el nombre de la herramienta como atributo. Cada parámetro es un elemento antml:parameter con un atributo name y el valor como contenido de texto.

Estructura de ejemplo para una llamada Bash:

• Etiqueta externa: antml:function_calls
• Etiqueta interna: antml:invoke con atributo name="Bash"
• Etiqueta de parámetro: antml:parameter con name="command" conteniendo el texto del comando

Comportamientos Operativos

• Interacciones con Linter: Al editar archivos, los hooks de git o "hooks" configurados pueden ejecutarse automáticamente después de las llamadas a herramientas y modificar archivos adicionalmente. El resultado de la herramienta indica "el archivo fue modificado por otro proceso", requiriendo relectura antes de editar nuevamente.
• Visibilidad de llamadas a herramientas: Cada llamada a herramienta aparece en la terminal para aprobación del usuario (dependiendo del modo de permiso). Los usuarios pueden denegar cualquier llamada a herramienta.
• Ejecución paralela: Múltiples llamadas a herramientas pueden emitirse en una sola respuesta y ejecutarse concurrentemente, útil para leer varios archivos a la vez.
• Gestión de contexto: Las conversaciones largas se comprimen automáticamente — los mensajes anteriores se resumen para liberar contexto. La persistencia de memoria ocurre a través de una estructura de directorios: /home/tpreal/.claude/projects/...