Herramientas: Descripción general

Las herramientas son las manos del agente. Una herramienta es una capacidad que el modelo puede invocar durante la conversación, ejecutar un comando de shell, obtener una URL HTTP, abrir un navegador, escribir un archivo, leer un sensor. Cada llamada a una herramienta está sujeta a la política de seguridad. Las ejecuciones satisfactorias pueden incluir un recibo de herramienta cuando los recibos están habilitados.

Las herramientas no deben confundirse con los subcomandos de la CLI de zeroclaw. Los comandos de la CLI son para los operadores; las herramientas son para el agente.

Un agente obtiene sus herramientas a través de los paquetes de habilidades, conocimiento y MCP que referencia; consulta Agents para ver cómo se adjuntan los paquetes a un agente. Para el recorrido a nivel de turno desde la llamada a la herramienta del proveedor hasta la aprobación, la distribución, la recepción, el evento del observador y la entrada del historial, consulta Tool execution lifecycle.

Antes de añadir una herramienta integrada o reemplazar una con una integración externa, usa el Inventario de herramientas integradas para elegir el hogar duradero más pequeño.

Herramientas integradas

Una compilación mínima incluye:

Siempre se registra junto con los integrados:

Registrado condicionalmente:

Protocolos de extensión

Además de las herramientas integradas, ZeroClaw admite la superficie de extensión MCP (Protocolo de Contexto del Modelo). Conecta cualquier servidor MCP (el sistema de archivos de Claude Code, Playwright, el tuyo propio) y el agente detectará sus herramientas al inicio.

Para la integración del lado del IDE donde un editor ejecuta ZeroClaw como subproceso, consulta ACP: Agent Client Protocol se encuentra bajo channels porque es una superficie de gestión de sesiones entrante, no una herramienta que el agente invoca.

Creación de una herramienta

Implementa el rasgo Tool en zeroclaw-api:

#![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;   // Esquema JSON para args
    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult>;
}
}

Cada Tool es también Attributable, por lo que las emisiones de log y los rastros de auditoría de una llamada a herramienta llevan la misma atribución <kind>.<alias> que usa el resto del runtime.

Regístrate a través de la fábrica de herramientas del entorno de ejecución. Consulta Desarrollo → Protocolo de plugins para ver el patrón completo.

Descripción de herramientas para el modelo

Las descripciones de herramientas son cadenas Mozilla Fluent: una por herramienta, localizada por configuración regional. Esto mantiene las descripciones de herramientas concisas en la ventana de contexto del modelo, a la vez que permite la localización de la interfaz de usuario.

Fuente de verdad: crates/zeroclaw-runtime/locales/en/tools.ftl. Las traducciones se generan y mantienen mediante cargo fluent fill --locale <code> (consulta Mantenedores → Documentación y traducciones).

Riesgo y aprobación

Cada invocación de herramienta se clasifica por riesgo:

• Bajo (solo lectura, sin efectos secundarios): file_read, memory_recall, http_request GET a dominios permitidos
• Medio (muta el estado local): file_write, shell con comandos conocidos seguros
• Alto (efectos secundarios destructivos o remotos): shell con comandos desconocidos, http_request POST a URLs sin restricciones

El nivel de autonomía determina lo que puede hacer cada nivel de riesgo sin la aprobación del operador. Predeterminado (Supervised): las ejecuciones de bajo nivel, las de nivel medio solicitan, y las de alto nivel bloquean.

Cuando los recibos están habilitados, las ejecuciones exitosas reciben un recibo de herramienta. Las llamadas denegadas, bloqueadas, reemplazadas, fallidas o interrumpidas no reciben recibos.

Desactivar herramientas en canales que no son CLI

El esquema no tiene un campo tools_allow / tools_deny por canal. El control de acceso a herramientas reside en el perfil de riesgo del agente ([risk_profiles.<alias>]):

• excluded_tools elimina las herramientas listadas de todos los canales que no sean CLI (Discord, Telegram, Bluesky, Matrix, Slack, etc.) y deja intacta la CLI local. La granularidad es binaria (CLI frente a no CLI), no por canal. Además, resta de la lista de अनुमति permitida de agentic-delegate resuelta en tiempo de ejecución, que es la única forma de bloquear nombres MCP individuales <server>__<tool> que de otro modo serían admitidos automáticamente por la regla siguiente.
• allowed_tools es lo inverso: una lista de अनुमति de herramientas que el agente puede invocar en modo agente (vacío u omitido significa que no hay restricción de autorización; la configuración TOML no distingue entre ambos).
• Excepción de MCP: cuando allowed_tools no está vacío, las herramientas MCP descubiertas en tiempo de ejecución (cualquier nombre que contenga __, la convención <server>__<tool>) se admiten automáticamente en la lista de अनुमति efectiva sin necesidad de enumerarlas allí individualmente. Esto mantiene utilizable el valor predeterminado eager-MCP posterior a #7464 para agentes que ya fijan una lista de अनुमति explícita. Para bloquear herramientas MCP individuales, enuméralas en excluded_tools.
• La excepción de MCP está limitada solo a allowed_tools del perfil de riesgo. Las listas de अनुमति por ejecución suministradas por el llamador (allowed_tools del trabajo de cron, invocaciones delegadas reducidas, etc.) siguen tratándose como intersecciones estrictas de listas explícitas. Un trabajo que se restringe a allowed_tools = ["cron_add"] no expondrá los envoltorios de MCP descubiertos en tiempo de ejecución que no haya nombrado, incluso cuando el perfil de riesgo del agente los admitiría automáticamente.

Si necesitas un control más detallado, baja el level del perfil a read_only o supervised y apóyate en las listas auto_approve / always_ask de cada perfil para condicionar las herramientas sensibles a la aprobación del operador.

Consulta Niveles de autonomía para ver el conjunto completo de campos por perfil.

Ver también

• MCP
• Ciclo de vida de ejecución de herramientas
• ACP
• Automatización del navegador
• Seguridad → Resumen