dful.
Dful Dark
Tema
Árbol de conocimiento
En esta página

Uso de herramientas

Cómo pide un modelo que se ejecute una tool, quién realiza la operación y qué resultado vuelve al siguiente paso.
Actualizado 28 ago 2026

Una tool es una función o capacidad que el modelo puede pedir que se ejecute. El modelo genera la llamada; el harness o la aplicación realiza la operación; el resultado vuelve al modelo.

Cómo se ejecuta una tool call El modelo solicita una tool con argumentos. El harness valida y ejecuta la operación y devuelve el resultado al modelo. Harness / runtime Petición del modelo Tool + argumentos Validar Argumentos + permiso Ejecutar la operación Fuera del modelo Fichero, shell o API El entorno objetivo Resultado Información para el turno siguiente devolver resultado Cómo se ejecuta una tool call El modelo solicita una tool con argumentos. El harness valida y ejecuta la operación y devuelve el resultado al modelo. Petición del modelo Tool + argumentos Harness / runtime Validar Argumentos + permiso Ejecutar la operación Fuera del modelo Fichero, shell o API El entorno objetivo Resultado Información para el turno siguiente devolver resultado
Figura 1. El modelo solicita una operación, el harness la valida y ejecuta, y el resultado vuelve al siguiente turno.

Definición

Una tool suele tener nombre, descripción y un schema de parámetros. El nombre identifica la operación. La descripción explica para qué sirve. El schema indica qué argumentos puede generar el modelo y permite validarlos antes de ejecutar.

{
  "name": "read_file",
  "description": "Read a range of lines from a text file",
  "parameters": {
    "type": "object",
    "properties": {
      "path": { "type": "string" },
      "start_line": { "type": "integer" }
    },
    "required": ["path"]
  }
}

Una descripción ambigua dificulta que el modelo elija bien. Si la tool borra datos, envía un mensaje o necesita una precondición, esa información debería quedar clara en la interfaz.

Tool call y ejecución

Supongamos que el modelo necesita inspeccionar src/app.ts. Genera una call a read_file con ese path. El runtime valida los argumentos, lee el fichero y devuelve las líneas solicitadas. Con ese resultado, el modelo decide si necesita otra lectura, un cambio o una respuesta final.

El modelo no ha abierto el fichero directamente. Ha producido output estructurado que otro programa ha convertido en una acción real.

Antes de ejecutar, el harness puede comprobar que los argumentos cumplen el schema y que la operación está permitida. Una call sintácticamente válida todavía puede apuntar a una ruta fuera de scope o pedir una acción que necesita aprobación.

Resultados

El resultado debe dar al modelo la información necesaria para continuar. Puede ser texto de shell o JSON con campos estables; no hace falta transformar todo a un único formato.

El tamaño importa porque ese resultado puede entrar en el contexto de la siguiente inferencia. Una tool de lectura con rangos de líneas es más manejable que otra que devuelve siempre el fichero completo. Para un log grande, el runtime puede conservar el original y devolver solo las coincidencias o un fragmento relevante.

Los errores también deben ser claros. Si el fichero no existe, devolver ese fallo permite que el modelo corrija el path. Ocultarlo detrás de una respuesta parecida a un éxito solo empeora el siguiente paso.

Efectos secundarios y reintentos

Repetir read_file suele ser seguro. Repetir send_message después de un timeout puede enviar el mismo mensaje dos veces, y repetir delete_file puede encontrar un estado distinto al de la primera llamada.

Por eso las tools que modifican el entorno suelen necesitar más cuidado: permisos, confirmación o una forma de comprobar si el efecto ya ocurrió. El harness aplica esas decisiones; la definición de la tool debe permitir entender qué puede cambiar.

APIs de modelos explica cómo aparecen las definiciones y tool calls en el protocolo. Bucle de agente explica cómo el resultado alimenta la siguiente decisión.

Referencias