Ciclo de vida de ejecución de herramientas

ZeroClaw tools son capacidades que el modelo puede invocar durante un turno. El catálogo de herramientas indica qué se puede llamar; el ciclo de vida de ejecución indica cómo una llamada se vuelve segura, observable, cancelable y visible para el proveedor.

Use esta página cuando un cambio afecte a herramientas integradas, la activación de herramientas MCP, el bucle del agente, la política de aprobación, los eventos de transmisión de llamadas a herramientas, los recibos, los eventos de observador, el historial de resultados de herramientas, la cancelación o el límite entre la entrada del canal y la acción del lado del agente.

Ruta de ejecución

Paso	Propietario	Revisar contrato
Definición de herramienta	`zeroclaw-api::tool::Tool`	Una herramienta tiene un nombre estable, descripción, esquema JSON, `execute` asíncrono y atribución.
Montaje de herramientas	Fábrica de herramientas en tiempo de ejecución y registro con ámbito	El agente recibe solo las herramientas admitidas por los bundles, la configuración de MCP, el perfil de riesgo y el estrechamiento por ejecución.
Resolución del contexto	`ResolvedAgentExecution`	El turno comienza con un único paquete resuelto: acceso al modelo, registro, gestor de aprobaciones, observador, knobs de tiempo de ejecución, controlador de activación de MCP y generador de recibos.
Solicitud del proveedor	`agent::turn::tool_specs` y llamada del proveedor	Los proveedores de herramientas nativas reciben especificaciones estructuradas; los proveedores de protocolo de texto reciben instrucciones de prompt a menos que el análisis estricto las oculte.
Análisis de tool-calls	`agent::turn::parse_response` y funciones auxiliares del analizador	Las llamadas nativas y de herramientas de texto se normalizan en llamadas analizadas con identificadores de proveedor cuando están disponibles.
Preparación	`agent::turn::call_prep`	Los hooks, los valores predeterminados de entrega, la aprobación, los controles de duplicados que requieren prompt y los controles ordinarios de llamadas duplicadas se ejecutan antes del despacho.
Ejecución	`agent::tool_execution`	Las llamadas se ejecutan secuencialmente o en paralelo según la política, la cancelación y las restricciones de activación.
Grabación de resultados	`post_exec`, `results_collect`, and `history_append`	Los resultados se ordenan, se registran, se observan, opcionalmente se recepcionan, se acotan y se añaden de nuevo al historial del proveedor.
Control de bucle	`run_tool_call_loop`	El modelo ve los resultados de las herramientas y puede continuar hasta que devuelva el texto final, se cancele o alcance el límite de iteraciones.

El runtime separa estos pasos para que una revisión pueda preguntar qué límite cambió. Agregar una herramienta no es lo mismo que ampliar la política de aprobación, cambiar las especificaciones de herramientas del proveedor, alterar los payloads del observador o persistir un resultado.

Definiciones y registro de herramientas

Cada herramienta implementa el trait Tool:

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Tool: Send + Sync + Attributable {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;
    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult>;
}
}

ToolResult es pequeño: success, output y error. Las implementaciones de herramientas no deben inventar cada una su propia ruta de registro o aprobación. El dispatcher se encarga de los eventos comunes de inicio/resultado, recibos, registros de observador, mensajes de progreso y conversión del historial.

Las especificaciones de herramientas se reconstruyen para las solicitudes del proveedor. El ToolSpec actual comparte esquemas grandes mediante Arc para que el formato en la red siga siendo el mismo, al tiempo que evita clonaciones profundas en cada iteración.

Contexto de ejecución resuelto

Los puntos de entrada no deben ensamblar un turno re-derivando la política en línea. El motor de turnos recibe un paquete ResolvedAgentExecution para dependencias estables por agente: enlace del modelo, registro de herramientas efectivo, manejadores de observador y aprobación, parámetros de ejecución resueltos, el conjunto de activación diferida de MCP, la devolución de llamada de cambio de modelo y el generador de recibos opcional.

El estado por mensaje permanece fuera de ese paquete: historial, receptores de streaming, canales de eventos, mensajes de control, token de cancelación, estado de inyección de memoria y el sobre de entrada.

Cuando una PR añade una nueva entrada de ejecución, preferir pasarla a través de este contexto resuelto o del estado explícito por turno de ToolLoop. Evita globals ocultos o volver a buscar la configuración dentro de una ruta de herramienta.

Disponibilidad y activación de MCP

El modelo solo puede llamar a herramientas que sean efectivas para el turno actual:

las herramientas estáticas provienen del registro con ámbito;
excluded_tools elimina los nombres antes de la exposición al prompt/especificación y antes de la ejecución;
Los proveedores de native-tool reciben especificaciones estructuradas para herramientas eficaces;
los proveedores de text-protocol reciben instrucciones de herramientas solo cuando se permite la invocación de herramientas de texto;
el análisis estricto puede ocultar por completo el protocolo de la herramienta de texto;
tool_filter_groups decide qué esquemas de herramientas MCP son visibles para el turno actual. Los grupos mode = "always" pueden preactivar wrappers MCP diferidos elegibles, mientras que los grupos dynamic exponen herramientas solo cuando el mensaje actual del usuario coincide con sus palabras clave;
MCP diferido puede exponer un stub de tool_search en lugar de cada wrapper de MCP.

La activación diferida de MCP es con estado dentro del turno. tool_search resuelve los stubs de MCP coincidentes en el ActivatedToolSet compartido; las llamadas posteriores pueden ejecutar esos envoltorios activados. Los grupos de filtrado no conceden capacidad por sí mismos: el registro acotado, la política de MCP y la lista de denegación siguen decidiendo qué envoltorios pueden existir.

No ejecutes tool_search en paralelo con las herramientas que activa. El despachador fuerza que cualquier lote que contenga tool_search se ejecute secuencialmente para que la búsqueda no compita con la activación. Las rutas de delegado/subagente deben encadenar el conjunto activado que se les concedió; de lo contrario, un turno delegado puede anunciar o intentar una herramienta que su ejecutor no puede resolver.

Aprobación y preparación

La preparación ocurre antes de que el ejecutor ejecute una herramienta:

before_tool_call los hooks pueden cancelar o reescribir el nombre/argumentos.
Los valores predeterminados de entrega del canal pueden inyectarse para herramientas conscientes del canal.
El runtime borra cualquier marcador “approved” en los argumentos.
La puerta de aprobación evalúa la herramienta frente a ApprovalManager.
Las llamadas aprobadas recuperan el marcador aprobado en tiempo de ejecución.
Las protecciones contra llamadas duplicadas eliminan las llamadas idénticas repetidas a menos que la herramienta esté exenta.

La aprobación tiene diferentes puntos de entrada:

Los administradores de CLI solicitan al operador y admiten yes, no y always.
Los administradores de canales no interactivos deniegan automáticamente las herramientas que requieren confirmación, a menos que el canal proporcione un canal de aprobación en línea.
ACP/web backchannels pueden llevar la solicitud de aprobación a un operador real aunque el turno en sí no sea interactivo.
DenyWithEdit / las respuestas de reemplazo se sanitizan y se convierten en resultados sintéticos de herramientas; la herramienta original no se ejecuta.

Approval es un control previo a la ejecución. No es un recibo, y no es prueba de que una herramienta se haya ejecutado. Las entradas de auditoría registran la decisión y el canal o canal secundario que tomó la decisión.

Las llamadas de shell que requieren solicitud tienen una salvaguarda de bucle adicional: si el agente repite la misma llamada de shell que requiere solicitud antes de la aprobación, el bucle se aborta en lugar de seguir solicitando una y otra vez.

Despacho, cancelación y ordenación

El ejecutor emite un TurnEvent::ToolCall pendiente inmediatamente antes de ejecutar la herramienta, para que los clientes de streaming puedan mostrar una tarjeta en ejecución en tiempo real. Cuando la herramienta termina, emite el TurnEvent::ToolResult correspondiente usando el mismo id de correlación.

La ejecución paralela solo se permite cuando:

el parámetro de ejecución habilita herramientas en paralelo;
el lote tiene más de una llamada ejecutable;
ninguna llamada en el lote requiere aprobación;
el lote no contiene tool_search.

De lo contrario, las llamadas se ejecutan secuencialmente. El despacho secuencial comprueba la cancelación antes de cada llamada y deja de despachar el resto cuando se cancela. El despacho en paralelo puede finalizar algunos hermanos mientras otros se interrumpen; las llamadas completadas conservan su resultado terminal real, y solo las llamadas no finalizadas obtienen un resultado interrumpido.

El vector de resultados ordenado conserva un espacio por cada llamada original al modelo. La preparación rellena los espacios para las llamadas canceladas, denegadas, sustituidas o deduplicadas; la ejecución rellena los espacios restantes. Esto preserva el orden del historial del proveedor incluso cuando algunas llamadas nunca se ejecutan o cuando las llamadas en paralelo terminan fuera de orden.

Resultados, recibos e historial

Las ejecuciones correctas de herramientas normalizan la salida vacía a (no output). Cuando [agent.tool_receipts] enabled = true, las ejecuciones correctas pueden recibir un recibo del ámbito de recibos activo antes de que el resultado se agregue al historial. Las rutas de tiempo de ejecución del canal y las rutas de turno directo tienen distintas duraciones de ámbito; la página Tool receipts contiene el formato exacto de HMAC y los detalles de la duración de las claves.

Los recibos son evidencia del resultado. No son decisiones de aprobación, ni registros de auditoría duraderos, ni una cadena, y no se generan para llamadas denegadas, reemplazadas, bloqueadas, fallidas o interrumpidas.

Después de la ejecución:

los eventos ToolCallStart del observador llevan el nombre de la herramienta, el id de llamada de herramienta del proveedor cuando está disponible, los argumentos, el canal, el alias del agente y el id del turno;
Los eventos ToolCall de terminal observer añaden duración, indicador de éxito y resultado depurado, mientras repiten los campos de correlación necesarios para backends orientados a spans;
las secuencias de progreso muestran líneas de inicio/completación con texto de error anonimizado;
after_tool_call hooks se ejecutan para las llamadas ejecutadas;
los resultados están limitados por max_tool_result_chars antes de que se agreguen al historial visible para el modelo;
loop-detection usa el contenido del resultado excepto para las herramientas ignoradas configuradas;
la siguiente solicitud del proveedor ve el turno de llamada a herramienta del asistente más los resultados de herramienta en orden.

Los resultados de las herramientas no son memoria a largo plazo a menos que se produzca una escritura en la memoria. Pueden ser contexto del turno actual, historial de sesión persistido, un evento de interfaz transmitido, un registro de observación/log, o un resultado con acuse de recibo. Nombra la superficie con precisión en PRs y revisiones.

Lo que esta página no posee

Los adaptadores de canal y los gateways se encargan del transporte entrante, la autenticación, el emparejamiento, la decodificación de webhooks y la entrega de respuestas. La ejecución de herramientas comienza después de que un turno ha llegado al bucle del agente y un modelo ha emitido una llamada a una herramienta.

El ciclo de vida de la configuración se encarga de cómo se cargan, guardan, sobrescriben y recargan los ajustes relacionados con la herramienta. Esta página solo cubre los valores resueltos después de que entran en el turno.

La documentación de seguridad y autonomía define el vocabulario de la política. Esta página muestra dónde se aplica esa política a una llamada concreta a una herramienta.

Memory y el ciclo de vida de la carga útil son responsables de la durabilidad y los límites de privacidad para el historial, los archivos, los medios y la memoria. Esta página cubre la ruta del resultado de la herramienta que alimenta esas superficies.

Ciclo de vida del trabajo en segundo plano posee el contrato de mayor duración cuando una herramienta inicia trabajo delegado o de subagente. El hecho de que una herramienta devuelva un ID de tarea no hace que su ejecución sea reanudable tras un reinicio.

Lista de verificación para revisores

Para cambios en la ejecución de herramientas, responde estas antes de la aprobación del revisor:

¿Qué límite cambió: definición de herramienta, ensamblado del registro, aprobación, ejecución, recibos, eventos del observador, historial o transmisión de la interfaz de usuario?
¿La herramienta sigue siendo atribuible y registrada a través de la ruta normal de la fábrica?
¿El modelo solo ve las herramientas admitidas para este agente/ejecución/iteración?
¿excluded_tools, el estrechamiento por ejecución, tool_filter_groups y la activación diferida de MCP siguen estando de acuerdo?
¿Una llamada que requiere prompt se ejecuta secuencialmente y solicita la superficie de aprobación correcta?
¿La ejecución no interactiva deniega o usa un backchannel real en lugar de aprobar silenciosamente?
¿Se conservan las protecciones contra llamadas duplicadas y solicitudes repetidas?
¿La cancelación cierra solo las tarjetas/resultados de herramientas no terminados?
¿Se eliminan y acotan las superficies de observación/log/progreso donde pueden aparecer cargas útiles del usuario o secretas?
¿Se describen los recibos como evidencia de ejecución exitosa, no de aprobación, persistencia o prueba de conocimiento cero?
¿Incluye el PR validación a nivel de límite para la superficie visible al usuario que cambia: CLI, canal, ACP/WS, gateway, cron o delegate/subagent?

Punteros de origen

Documentación canónica:

Puntos de entrada clave del código:

Trait de herramienta y forma del resultado: crates/zeroclaw-api/src/tool.rs
Eventos de la herramienta Observer: crates/zeroclaw-api/src/observability_traits.rs
Contexto de ejecución del turno: crates/zeroclaw-runtime/src/agent/turn/execution.rs
Hoja de ejecución del motor y bucle: crates/zeroclaw-runtime/src/agent/turn/mod.rs
Preparación de llamadas a herramientas y aprobación: crates/zeroclaw-runtime/src/agent/turn/call_prep.rs y crates/zeroclaw-runtime/src/agent/turn/approval_gate.rs
Desvío de herramientas: crates/zeroclaw-runtime/src/agent/tool_execution.rs
Recibos de herramientas: crates/zeroclaw-runtime/src/agent/tool_receipts.rs
Recopilación de resultados/añadir al historial: crates/zeroclaw-runtime/src/agent/turn/results_collect.rs y crates/zeroclaw-runtime/src/agent/turn/history_append.rs
Gestor de aprobaciones: crates/zeroclaw-runtime/src/approval/mod.rs
Ensamblado de herramientas con ámbito y activación diferida de MCP: crates/zeroclaw-runtime/src/tools/scoped.rs

Keyboard shortcuts

ZeroClaw Docs