Gestión de herramientas
Descripción general
Las herramientas son las "manos y pies" que el Agent utiliza para ejecutar operaciones. El sistema ofrece 19 herramientas integradas y permite ampliar el conjunto de herramientas mediante el protocolo MCP, las definiciones OpenAPI y las habilidades. La página de gestión de herramientas sirve para configurar y administrar todas las herramientas disponibles.
19 herramientas integradas
Operaciones con archivos (7 herramientas)
| Herramienta | Función | Nivel de seguridad |
|---|---|---|
| Read File | Lee el contenido de un archivo, admite rangos de números de línea, con un límite de 5 MB | P0 (ejecución automática) |
| Write File | Escribe en un archivo; si no existe, lo crea automáticamente junto con los directorios padre | P0 |
| Edit | Realiza modificaciones parciales en un archivo existente (modo de búsqueda y reemplazo) | P0 |
| MultiEdit | Realiza múltiples modificaciones por lotes en un archivo existente | P0 |
| List Directory | Enumera los archivos y subdirectorios de un directorio, mostrando el tamaño de los archivos | P0 (bloqueado) |
| Glob Files | Busca archivos según un patrón comodín, con un máximo de 100 resultados | P0 (bloqueado) |
| Search Files | Busca dentro del contenido de los archivos mediante expresiones regulares, con un máximo de 250 resultados | P0 (bloqueado) |
Ejecución de comandos (1 herramienta)
| Herramienta | Función | Nivel de seguridad |
|---|---|---|
| Bash | Ejecuta comandos de Shell, scripts y operaciones de Git, con un tiempo de espera de 120 segundos y un límite de salida de 50 KB | P1 (confirmación la primera vez) |
Red (1 herramienta)
| Herramienta | Función | Nivel de seguridad |
|---|---|---|
| Web Fetch | Obtiene el contenido de una URL y lo convierte en Markdown, con eliminación automática de ruido y caché de 15 minutos | P1 |
Gestión de tareas (1 herramienta)
| Herramienta | Función | Nivel de seguridad |
|---|---|---|
| Task Manage | Gestiona listas de tareas estructuradas (pendientes/en curso/completadas); se invoca automáticamente en tareas de más de 3 pasos | P0 (bloqueado) |
Invocación de habilidades (1 herramienta)
| Herramienta | Función | Nivel de seguridad |
|---|---|---|
| Skill | Invoca un módulo Skill instalado para ejecutar tareas especializadas | P1 |
Interacción con el usuario (1 herramienta)
| Herramienta | Función | Nivel de seguridad |
|---|---|---|
| AskUserQuestion | El Agent formula preguntas al usuario (hasta 4 preguntas, cada una con entre 2 y 10 opciones) | P0 (bloqueado) |
Subagentes (3 herramientas)
| Herramienta | Función | Nivel de seguridad |
|---|---|---|
| create_local_sub_agent | Crea un subagente temporal en el nodo actual, con soporte para anidamiento de 1 a 3 niveles | P0 |
| dispatch_sub_agent | Asigna una tarea a un subagente ya registrado | P0 |
| dispatch_multi_node_agent | Asigna una tarea a un nodo remoto a través del Gateway | P0 |
Memoria (4 herramientas)
| Herramienta | Función | Nivel de seguridad |
|---|---|---|
| Conversation Search | Busca conversaciones anteriores por palabra clave, con filtrado por rango temporal, hasta 10 resultados | P0 (bloqueado) |
| Recent Chats | Enumera de 1 a 20 sesiones de conversación recientes, con filtrado por tiempo | P0 (bloqueado) |
| Memory Query | Busca en la memoria de usuario almacenada (búsqueda semántica + expansión por grafo) | P0 (bloqueado) |
| Memory Manage | Añade, actualiza o elimina memorias de usuario | P1 |
Explicación de los niveles de seguridad
| Nivel | Significado | Comportamiento |
|---|---|---|
| P0 | Operación segura | Se ejecuta automáticamente, sin confirmación del usuario |
| P1 | Requiere confirmación | En la primera invocación aparece una confirmación de permisos |
| P2 | Confirmación cada vez | Cada invocación requiere la confirmación del usuario |
| Bloqueado | No degradable | El nivel de seguridad es fijo y no se puede ajustar |
Los administradores pueden ajustar el nivel de permisos de las herramientas no bloqueadas (límite mínimo de la organización) en las Barreras de seguridad, y cada persona puede restringirlo aún más en la seguridad de ejecución de la APP.
Protocolo de herramientas MCP
El MCP (Model Context Protocol) es un protocolo estandarizado de comunicación entre herramientas de IA que permite ampliar el conjunto de herramientas mediante servicios externos.
Tres métodos de transporte
| Transporte | Descripción | Escenario de uso |
|---|---|---|
| stdio | Comunicación con subprocesos locales (command + args) | Herramientas CLI locales |
| SSE | Server-Sent Events (conexión HTTP de larga duración) | Servicios remotos |
| HTTP | API HTTP con streaming | Servicios remotos |
Cinco modos de autenticación
| Autenticación | Descripción |
|---|---|
| none | Sin autenticación |
| bearer | Bearer Token |
| basic | HTTP Basic Auth |
| service | Autenticación entre servicios |
| oauth2 | Flujo de código de autorización OAuth2 (descubrimiento automático del endpoint well-known) |
Interfaz de gestión de MCP
Gestiona los servidores MCP mediante el componente McpManager:
- Añadir servidor: configura el nombre, el método de transporte, los parámetros de conexión y el método de autenticación
- Editar/Eliminar: modifica o elimina configuraciones existentes
- Activar/Desactivar: cambia el estado de disponibilidad del servidor
- Descubrimiento de herramientas: tras la conexión, descubre automáticamente la lista de herramientas que ofrece el servidor
Aislamiento de seguridad
El subproceso MCP solo transmite las variables de entorno de la lista blanca, para evitar la fuga de información sensible como las API Key.
Herramientas API
Permite analizar y crear herramientas automáticamente a partir de documentos OpenAPI/Swagger:
| Función | Descripción |
|---|---|
| Análisis automático | Extrae endpoints y el Schema de parámetros a partir de la especificación OpenAPI |
| Configuración de autenticación | Cinco modos de autenticación |
| Variables de plantilla | Sustitución dinámica de {{variable}} |
| Métodos HTTP | GET / POST / PUT / DELETE / PATCH |
Directorio de herramientas personalizadas NEW
El sistema incorpora ToolDirectoryManager, que gestiona las herramientas personalizadas ubicadas en el directorio {dataDir}/TOOLs/{orgId}/_custom/ y permite cargarlas sin necesidad de reiniciar la APP.
Estructura de directorios
{dataDir}/TOOLs/{orgId}/_custom/
├── my-tool-1/
│ ├── metadata.json
│ └── ...
└── my-tool-2/
├── metadata.json
└── ...
Ejemplo de metadata.json
{
"id": "my-tool-1",
"name": "My Custom Tool",
"description": "自定义工具说明",
"type": "API",
"enabled": true,
"createdAt": 1776921208476,
"updatedAt": 1776921208476
}
Mecanismo de carga
- Método de escaneo:
scanAndLoad(orgId) - Tipos admitidos:
API/MCP - Aislamiento por organización: directorios separados por orgId, sin interferencias entre sí
- Carga en caliente: sin necesidad de reiniciar la APP
Canalización de carga de herramientas
Todas las herramientas se cargan y combinan en el siguiente orden:
① Herramientas integradas (19)
↓
② Herramientas MCP (descubiertas desde los servidores MCP configurados)
↓
③ Herramientas API (analizadas desde definiciones OpenAPI)
↓
④ Herramientas personalizadas (ToolDirectoryManager escanea el directorio _custom/)
↓
⑤ Herramientas de habilidades (inyecta execute_skill_{id} desde las Skills activadas)
↓
⑥ Combinación y eliminación de duplicados → lista final de herramientas → se envía al LLM
Escenarios de uso de las herramientas más comunes
| Ejemplo de solicitud del usuario | Herramienta invocada por el Agent | Descripción |
|---|---|---|
| "Muéstrame el contenido de package.json" | Read File | Lee y devuelve el contenido del archivo |
| "Cambia el nombre de la función de getData a fetchData" | Edit | Búsqueda y reemplazo precisos |
| "Crea un README.md" | Write File | Crea un archivo nuevo |
| "¿Qué archivos .tsx hay en el proyecto?" | Glob Files | Busca nombres de archivo según un patrón |
| "¿Dónde se usa useEffect en el código?" | Search Files | Búsqueda con expresiones regulares en el contenido de los archivos |
| "Ejecuta npm install por mí" | Bash | Ejecuta un comando de Shell |
| "Resume el contenido de esta página web: https://..." | Web Fetch | Extrae la página web y la convierte en Markdown |
| "Esta tarea es bastante compleja, primero haz un plan" | Task Manage | Crea una lista de tareas estructurada |
| "Busca la conversación de ayer sobre la migración de la base de datos" | Conversation Search | Busca en conversaciones anteriores |
| "Recuerda que prefiero usar el tema dark" | Memory Manage | Almacena en la memoria |
Guía de operaciones: añadir una herramienta MCP
- Abre la APP → Configuración → Herramientas → área de herramientas MCP
- Haz clic en Añadir servidor MCP
- Rellena la configuración:
- Nombre: asigna un nombre identificativo a este servidor MCP
- Método de transporte: elige stdio / SSE / HTTP
- Si es stdio: introduce el comando (por ejemplo,
npx) y los argumentos (por ejemplo,@anthropic/mcp-server-filesystem) - Si es SSE/HTTP: introduce la URL del servidor
- Si se requiere autenticación, elige el método de autenticación e introduce las credenciales
- Haz clic en Guardar
- El sistema se conecta automáticamente al servidor y descubre las herramientas disponibles
- Las herramientas descubiertas aparecen en la lista de herramientas, activadas de forma predeterminada
Sugerencia: El subproceso MCP solo transmite las variables de entorno de la lista blanca. Si la herramienta MCP necesita variables de entorno como una API Key, debes declararlas explícitamente en el campo env de la configuración.
Impacto de desactivar una herramienta
Tras desactivar una herramienta, el Agent desconoce por completo su existencia durante la conversación. Esto significa que:
| Herramienta desactivada | Impacto |
|---|---|
| Bash | El Agent no puede ejecutar ningún comando de Shell (npm, git, compilación, etc.) |
| Read File / Write File | El Agent no puede leer ni crear archivos |
| Web Fetch | El Agent no puede obtener contenido de páginas web; las habilidades de búsqueda también se ven afectadas |
| Memory Query / Manage | El Agent no consultará ni almacenará memoria |
| Skill | El Agent no puede invocar ningún módulo de habilidad |
| create_local_sub_agent | El Agent no puede crear subagentes para descomponer tareas |
Recomendación: A menos que exista un motivo de seguridad claro, no se recomienda desactivar las herramientas básicas de operaciones con archivos (Read / Write / Edit / Glob / Search), ya que la capacidad de ejecución de tareas del Agent se vería gravemente limitada.
Preguntas frecuentes
El Agent dice "no puedo realizar operaciones con archivos"
Comprueba si las herramientas de operaciones con archivos (Read File, Write File, Edit, etc.) están desactivadas. En la página de gestión de herramientas, confirma que estas herramientas estén activadas.
Fallo de conexión de la herramienta MCP
- Confirma que el comando/URL del servidor MCP sea correcto
- Si es el método stdio, confirma que el comando correspondiente esté instalado (por ejemplo,
npxrequiere un entorno de Node.js) - Comprueba si se necesitan variables de entorno (API Key, etc.)
- Consulta los registros de la APP para obtener información detallada del error
El Agent no usa la herramienta que yo esperaba
El Agent elige las herramientas de forma autónoma según las necesidades de la tarea. Si el Agent elige la herramienta "equivocada", puedes indicárselo explícitamente en la conversación: "Por favor, usa la herramienta Bash para ejecutar este comando".
Documentos relacionados
- Gestión de habilidades — Sistema de habilidades
- Seguridad de ejecución — Configuración de permisos de herramientas
- Barreras de seguridad — Gestión de permisos de herramientas a nivel empresarial