API de herramientas

Documentación interna para desarrolladores. Esta página cubre la API de herramientas: herramienta CRUD, configuración de herramientas HTTP y tipos de herramientas de IA integradas. No está destinado a usuarios finales.

​

Mapa de ruta

​

Tipos de herramientas

​

Esquema de configuración de la herramienta HTTP

interface HttpToolConfig {
  url: string;                    // Target URL
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  headers?: Record<string, string>;
  body?: string;                  // Template with {{variables}}
  auth?: {
    type: 'bearer' | 'basic' | 'api-key';
    value: string;
    headerName?: string;          // for api-key type
  };
  responseMapping?: {
    path: string;                 // JSONPath expression
    as: string;                   // Variable name for AI
  };
  timeout?: number;               // ms, default 30000
}

​

Almacenamiento de configuración de herramientas

const config = tool.config as HttpToolConfig | null;

​

Resumen de la página web

• Respeta robots.txt (no pasar por alto)
• Tamaño máximo del contenido: 500 KB (truncado si es mayor)
• Tiempo de espera: 15 segundos
• Devoluciones: { url, title, summary, extractedAt }

​

Resumen de YouTube

• Utiliza la API de datos de YouTube o la extracción de transcripciones (consulte la implementación actual)
• Vuelve a la descripción si la transcripción no está disponible
• Devoluciones: { videoId, title, summary, duration }

​

Gestión de herramientas de agentes

// GET /api/agents/[id]/tools
// Returns all tools for the agent (including type='agent' specialists)
// authMode: 'lightweight'

// PATCH /api/agents/[id]/tools/[toolId]
// Body: partial HttpToolConfig (or other tool-specific config)
// Merges with existing config using spread

​

Problemas conocidos / Problemas

• Exposición del secreto de la herramienta HTTP: El campo auth.value almacena claves/tokens API. Nunca devuelva estos en GET respuestas; enmascare con *** u omita. Establezca nuevos valores únicamente a través de PATCH.
• Riesgo de inyección de herramienta HTTP: Los campos url y ​​body admiten variables de plantilla. Valide que la sustitución de variables no se pueda utilizar para SSRF (bloquear rangos de IP internos: 10.x, 172.16-31.x, 192.168.x, 127.x, 169.254.x).
• Herramientas especializadas (type: 'agent') usan la misma tabla Tool pero tienen una estructura config completamente diferente a la de las herramientas HTTP. Siempre verifique tool.type antes de leer config.