Glosario
76 términos de «Llamada a herramientas en agentes: conseguir que los agentes hagan cosas de verdad». Pasa el cursor sobre la primera aparición en la lección para ver la definición.
| Término | Definición | Fuente |
|---|---|---|
| herramienta | En el contexto de un agente, una herramienta es una capacidad concreta que el modelo puede solicitar durante la conversación; el programa host la registra y la ejecuta, convirtiendo al modelo de algo que solo habla en algo que puede actuar. | Define tools — Claude API |
| programa host | El programa host es el código que realmente recibe la petición de llamada a herramienta del modelo, ejecuta la operación y devuelve el resultado al modelo — por ejemplo, Claude Code, o un script de agente que escribas tú. | How tool use works — Claude API |
| search_files | Un nombre de herramienta de ejemplo usado a lo largo del curso, representando la clase de definiciones concretas de herramienta que «buscan archivos del proyecto según alguna condición». | Define tools — Claude API |
| name | Un campo obligatorio en una definición de herramienta; es el identificador que el modelo escribe cuando elige una herramienta, y debe coincidir exactamente con el nombre dado en el momento de la llamada. | Define tools — Claude API |
| description | Un campo obligatorio en una definición de herramienta; declara en texto plano qué hace la herramienta, cuándo usarla y cómo se comporta, y es la única base legible que tiene el modelo al elegir una herramienta. | Define tools — Claude API |
| input_schema | Un campo obligatorio en una definición de herramienta; es un JSON Schema que especifica la forma que deben tomar los parámetros cuando se llama a la herramienta. | Define tools — Claude API |
| client tools | Herramientas que la aplicación host es responsable de ejecutar ella misma; el modelo solo genera la petición de llamada, mientras que el código de ejecución real corre del lado del host. | Tool use with Claude — Overview |
| server tools | Herramientas que los servidores de Anthropic ejecutan en tu nombre, a diferencia de las client tools cuya lógica de ejecución debe implementar la aplicación host. | Tool use with Claude — Overview |
| datos estructurados | La petición de llamada a herramienta del modelo vuelve como un fragmento de datos estructurados (no una instrucción en lenguaje natural), llevando el nombre de la herramienta y los parámetros para que el programa host los analice y ejecute. | How tool use works — Claude API |
| required | Un campo en JSON Schema que enumera los nombres de parámetros que una llamada a herramienta debe proporcionar; una llamada sin esos parámetros se trata como entrada inválida. | Define tools — Claude API |
| Claude Code | El ejemplo concreto del curso del concepto de «programa host» — en sí mismo un producto de agente que solicita llamadas a muchas herramientas (leer archivos, buscar código, ejecutar comandos, etc.). | Tools reference — Claude Code Docs |
| tools | Un campo llevado en la petición enviada al modelo; es un manifiesto de herramientas que enumera cuáles puede solicitar el modelo en esta conversación y qué parámetros necesita cada una. | Define tools — Claude API |
| stop_reason | Un campo en la respuesta del modelo que explica por qué el modelo dejó de hablar esta vez — los valores incluyen tool_use, end_turn y otros — y es solo una señal, no un registro de ejecución. | Tool use with Claude — Overview |
| tool_result | Un tipo de bloque de contenido en el mensaje devuelto al modelo; lleva el resultado terminado de una ejecución de herramienta y coincide con su bloque tool_use correspondiente a través de tool_use_id. | Handle tool calls — Claude API |
| tool_use_id | Un campo en un bloque tool_result que debe coincidir exactamente con el id de su bloque tool_use correspondiente; el modelo lo usa para emparejar cada resultado con su petición. | Handle tool calls — Claude API |
| is_error | Un campo opcional en un bloque tool_result que marca si esta ejecución de herramienta en sí falló; establecido en true, le dice al modelo que esta llamada tuvo un problema. | Handle tool calls — Claude API |
| finish_reason | El nombre de campo que corresponde a stop_reason en APIs compatibles con OpenAI; el valor tool_calls significa que el modelo está solicitando una llamada a herramienta. | Tool Use — LM Studio Docs (API compatible con OpenAI) |
| messages | El campo de array en la petición que lleva el historial de conversación; la respuesta de cada turno debe añadirse literalmente, incluyendo la respuesta tool_use del modelo y el tool_result siguiente. | How tool use works — Claude API |
| end_turn | Un valor de stop_reason que significa que el modelo ha terminado de hablar para este turno, no necesita más llamadas a herramientas, y su contenido puede entregarse al usuario. | Tool use with Claude — Overview |
| bloque tool_use | El tipo de bloque de contenido en el array content de respuesta del modelo que representa una petición de llamada a herramienta; está completo solo cuando lleva los tres campos id, name e input. | Handle tool calls — Claude API |
| ida y vuelta | El ciclo completo de una llamada a herramienta: el modelo emite una petición, el host la ejecuta, el resultado se envía de vuelta, y el modelo produce su siguiente respuesta. | How tool use works — Claude API |
| bucle | La forma del lado del host de manejar llamadas a herramientas de múltiples turnos: mientras stop_reason siga siendo tool_use, sigue ejecutando herramientas, enviando resultados de vuelta y solicitando de nuevo, hasta que se convierta en end_turn. | How tool use works — Claude API |
| dependencia de datos | Dentro de un lote de llamadas a herramientas paralelas, cuando el parámetro de una llamada debería en teoría igualar el valor de retorno de otra llamada — un valor que aún no existe en el momento en que se genera el lote. | Parallel tool use — Claude API |
| disable_parallel_tool_use | Una configuración en el objeto tool_choice de la petición; establecida en true, el modelo llama como máximo una herramienta por respuesta, usado para ajustar el comportamiento cuando las dependencias de llamadas paralelas aún no están resueltas. | Parallel tool use — Claude API |
| radio de impacto | El rango de daño que una llamada a herramienta puede causar cuando sale mal; es el criterio central para clasificar las cinco categorías de herramientas. | Configure the sandboxed Bash tool - Claude Code Docs |
| read_file | El nombre de ejemplo del curso para la categoría de herramienta de lectura; su parámetro típico es una ruta de archivo, y devuelve el contenido del archivo. | Tools reference — Claude Code Docs |
| write_file | El nombre de ejemplo del curso para la categoría de herramienta de escritura; sus parámetros típicos son una ruta y contenido, y una vez que se ejecuta sobrescribe el archivo original y usualmente no puede deshacerse. | Tools reference — Claude Code Docs |
| bash | El nombre de ejemplo del curso para la categoría de herramienta de ejecución; su parámetro es una cadena de comando abierta que puede ejecutar cualquier comando de shell. | Configure the sandboxed Bash tool - Claude Code Docs |
| search_code | El nombre de ejemplo del curso para la categoría de herramienta de búsqueda; sus parámetros típicos incluyen pattern y max_results, y devuelve una lista de ubicaciones de coincidencias en lugar de contenidos de archivos completos. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| send_slack_message | El nombre de ejemplo del curso para la categoría de herramienta de llamada a API externa; sus parámetros típicos son un canal y texto, y llamarla cruza la red hacia un servicio que no controlas. | The lethal trifecta for AI agents - Simon Willison's Weblog |
| command | El campo de parámetro central de una herramienta de categoría de ejecución (como bash); es esencialmente un script de shell abierto cuya capacidad no está delimitada por estructura de esquema. | Configure the sandboxed Bash tool - Claude Code Docs |
| max_results | Un parámetro común en herramientas de categoría de búsqueda; limita cuántas coincidencias vuelven en una llamada, evitando una sobrecarga de resultados que haga estallar el contexto. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| asimetría entre herramientas de lectura y herramientas de escritura | Las herramientas de lectura y escritura tienen formas de llamada similares, pero una lectura equivocada puede simplemente leerse de nuevo mientras que una escritura equivocada a menudo no puede deshacerse — sus consecuencias de riesgo no son equivalentes. | Tools reference — Claude Code Docs |
| retry_after | Un campo que una herramienta de API externa puede devolver en fallo, diciéndole al modelo cuánto tiempo esperar antes de reintentar — un ejemplo concreto de «la información de fallo debería llevar pistas accionables». | Tools - Model Context Protocol |
| total_matches | Un campo en el resultado devuelto de la herramienta search_code dando el número total de coincidencias, permitiendo al modelo juzgar si los resultados están completos o si la búsqueda debería estrecharse. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| code_search_grep | El nombre de herramienta de búsqueda reescrito en el ejemplo de comparación del curso; su descripción declara claramente que busca por contenido y nombra code_search_glob como la herramienta a usar para encontrar archivos por nombre. | Writing effective tools for AI agents—using AI agents | Anthropic Engineering |
| code_search_glob | La herramienta de búsqueda de nombres de archivo emparejada con code_search_grep; el curso la usa para mostrar que nombrar la herramienta alternativa en una descripción reduce marcadamente las probabilidades del modelo de elegir la herramienta equivocada. | Writing effective tools for AI agents—using AI agents | Anthropic Engineering |
| enum | Una palabra clave de JSON Schema que estrecha el valor de un parámetro a uno de un conjunto enumerado de opciones; es una restricción real que rechaza entrada inválida, no solo una nota. | Creating your first schema - JSON Schema |
| additionalProperties: false | Una configuración de input_schema de nivel superior que requiere que el objeto de entrada lleve solo claves declaradas en properties, cerrando la brecha donde el modelo inventa campos extra que se deslizan al código aguas abajo. | Strict tool use — Claude API |
| modo strict | Con strict: true establecido en una definición de herramienta, la plataforma restringe el muestreo del modelo para que la entrada generada coincida estrictamente con input_schema, y los parámetros inválidos nunca se generan en primer lugar. | Strict tool use — Claude API |
| namespacing | La práctica de prefijar nombres de herramientas con el servicio (como github_, slack_), para que a medida que las herramientas crecen el modelo pueda primero descartar opciones irrelevantes por prefijo. | How to implement tool use - Claude Platform Docs |
| github_list_prs | El ejemplo del curso de un nombre de herramienta con espacio de nombres; el prefijo github_ marca la herramienta como perteneciente al servicio GitHub, ayudando al modelo a distinguirla de operaciones con el mismo nombre en otros servicios. | How to implement tool use - Claude Platform Docs |
| slack_send_message | Otro de los ejemplos del curso de nombres de herramientas con espacio de nombres; el prefijo slack_ la marca como perteneciente al servicio Slack, distinguiéndola de otras herramientas de envío de mensajes. | How to implement tool use - Claude Platform Docs |
| title | Un campo descriptivo en JSON Schema usado para dar a un parámetro un título legible; como description, solo explica y no impone ninguna restricción de ejecución. | Creating your first schema - JSON Schema |
| MCP | Un protocolo que define cómo interactúan clientes y servicios de herramientas; el curso cita su requisito explícito de que los mensajes de error sean expuestos al modelo para que pueda autocorregirse. | Tools - Model Context Protocol |
| 55K tokens | Una cifra de ejemplo del equipo de ingeniería de Anthropic: las definiciones de 58 herramientas pueden ocupar aproximadamente 55K tokens de contexto, ilustrando el impacto real del recuento de herramientas en la sobrecarga de contexto. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| 134K tokens | Un ejemplo más extremo que el curso cita, mostrando que a medida que el recuento de herramientas sigue creciendo, el contexto consumido solo por definiciones de herramientas puede inflarse a una escala muy significativa. | Introducing advanced tool use on the Claude Developer Platform | Anthropic Engineering |
| file_type | Un campo de parámetro de ejemplo que el curso usa para mostrar que una descripción no es una restricción; con solo una descripción el modelo puede rellenarlo arbitrariamente, y solo enum realmente lo estrecha. | Creating your first schema - JSON Schema |
| granularidad | Qué finamente se dividen las responsabilidades de una herramienta; el curso enfatiza que la granularidad no es ni mejor gruesa ni mejor fina — divide por función primero, luego controla probabilidades de elección equivocada con espacios de nombres y descripciones. | Writing effective tools for AI agents—using AI agents | Anthropic Engineering |
| inyección de prompt | Un ataque donde se esconden instrucciones en contenido que el agente eventualmente leerá (un issue, una página web), para que el agente confunda ese texto con una nueva instrucción que debe obedecer. | The lethal trifecta for AI agents - Simon Willison's Weblog |
| allow | Uno de los tres niveles de regla de permisos; se aplica a operaciones de solo lectura, sin efectos secundarios, que pueden repetirse sin dejar rastro, y es auto-aprobado sin confirmación humana. | Configure permissions - Claude Code Docs |
| ask | Uno de los tres niveles de regla de permisos; se aplica a operaciones con efectos secundarios que son reversibles y cuyo radio de impacto permanece dentro del repositorio local, y requiere confirmación humana antes de ejecutarse. | Configure permissions - Claude Code Docs |
| deny | Uno de los tres niveles de regla de permisos; se aplica a operaciones irreversibles o cuyo radio de impacto alcanza más allá de local, rechazando ejecución, y se evalúa antes de ask y allow. | Configure permissions - Claude Code Docs |
| Read(./.env) | Un ejemplo de regla de permisos concreto del curso, poniendo la operación de leer el archivo .env directamente en la lista deny para mantener contenido secreto fuera del contexto de conversación. | Configure permissions - Claude Code Docs |
| Bash(git push:*) | Un ejemplo de regla de permisos del curso; la forma Tool(especificador) mapea directamente al nombre de herramienta exacto y alcance de llamada que el host expone al modelo. | Configure permissions - Claude Code Docs |
| agencia excesiva | La categoría de riesgo de OWASP para una acción dañina siendo desencadenada por una salida de modelo inesperada, ambigua o manipulada que nunca debería haber ocurrido. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| Funcionalidad excesiva | Una causa raíz de agencia excesiva: una sola herramienta lleva muchos sombreros (digamos, puede tanto leer la bandeja de entrada como enviar correo), así que una mala llamada tiene su radio de impacto magnificado. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| Permisos excesivos | Una causa raíz de agencia excesiva: la herramienta misma hace una cosa, pero el acceso que se le concede va más allá de lo que la tarea realmente necesita. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| Autonomía excesiva | Una causa raíz de agencia excesiva: un agente ejecuta muchos pasos seguidos sin comprobación humana en el medio, así que para cuando se nota un problema una acción irreversible puede ya haberse ejecutado. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| trifecta letal | La combinación de riesgo formada cuando acceso a datos privados, exposición a contenido no confiable y capacidad de comunicarse externamente están todos presentes a la vez, dando a la inyección de prompt una ruta para sacar datos. | The lethal trifecta for AI agents - Simon Willison's Weblog |
| humano en el bucle | Una de las mitigaciones de OWASP para agencia excesiva: acciones de alto impacto deben ser aprobadas por una persona antes de tomarse. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| sandbox | Un mecanismo de aislamiento a nivel de SO que impone aislamiento de sistema de archivos y red independientemente del juicio del modelo, para que el daño permanezca contenido incluso si la inyección de prompt tiene éxito. | Configure the sandboxed Bash tool - Claude Code Docs |
| TOOLS | El objeto único en el ejemplo del curso donde los campos de esquema de cada herramienta y su manejador de ejecución real viven en una tabla, previniendo que los dos lados se separen. | Define tools — Claude API |
| toolSchemas | La lista de parámetros tools derivada de la tabla TOOLS y enviada al modelo; contiene solo name/description/input_schema, no el manejador. | Define tools — Claude API |
| toolHandlers | La tabla de búsqueda en tiempo de ejecución derivada de la tabla TOOLS, mapeando cada nombre de herramienta a la función que realmente la ejecuta. | How tool use works — Claude API |
| github_repo_info | La tercera herramienta de ejemplo que el curso implementa; consulta información básica sobre un repositorio público de GitHub y es la única herramienta que envía datos fuera del proyecto. | How to implement tool use - Claude Platform Docs |
| SAFE_NAME | La expresión regular en el código del curso usada para validar el formato de los parámetros owner/repo, previniendo que una cadena arbitraria sea enviada a la red externa. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| MAX_TURNS | El límite de iteraciones establecido en el bucle de ejecución del curso, previniendo que el modelo solicite interminablemente llamadas a herramientas para que el bucle nunca termine. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| PROJECT_ROOT | La constante en el código del curso para el directorio raíz del proyecto; read_file y search_files ambas la usan para una comprobación de límite de ruta para prevenir acceso a archivos fuera del proyecto. | Configure the sandboxed Bash tool - Claude Code Docs |
| recentCalls | El array en el código del curso que registra las firmas de las últimas pocas llamadas a herramientas, usado para detectar el patrón de «la misma herramienta con los mismos argumentos llamada tres veces seguidas». | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| GITHUB_TOKEN | Una credencial opcional leída de una variable de entorno, usada para elevar el límite de tasa al llamar a la API de GitHub; la llamada también funciona anónimamente sin ella. | Configure permissions - Claude Code Docs |
| válvula de seguridad | El término colectivo del curso para el conjunto de guardias añadidos al bucle de ejecución — MAX_TURNS, detección de llamadas repetidas, y las comprobaciones internas de ruta y formato de las herramientas — cada una parando un escenario de desboque diferente. | LLM06:2025 Excessive Agency - OWASP Gen AI Security Project |
| function walk(dir) | La función de recorrido de directorio que el código del curso implementa por sí mismo, usada dentro de searchFiles para listar archivos recursivamente en lugar de lanzar a grep. | Configure the sandboxed Bash tool - Claude Code Docs |
| JSON Schema | La especificación usada para definir el input_schema de una herramienta; sus title/description declaran intención y no añaden restricciones, mientras que palabras clave como enum y required realmente validan valores. | Creating your first schema - JSON Schema |
| restringiendo el muestreo | La técnica detrás del modo strict: la plataforma restringe el muestreo de tokens del modelo a salidas válidas según esquema, para que las entradas de herramienta generadas siempre coincidan con el JSON Schema. | Strict tool use — Claude API |
| tool_choice | El objeto de petición que controla cómo el modelo selecciona herramientas; establecer disable_parallel_tool_use: true en él (cuando type es auto) hace que el modelo llame como máximo una herramienta por respuesta. | Parallel tool use — Claude API |