> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API de herramientas

> Referencia interna para la API de herramientas: configuración de herramientas HTTP, resumen de páginas web, herramientas de resumen de YouTube y administración de herramientas de agentes.

> **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

| Método  | Punto final                       | Archivo de controlador                | Descripción                                 |
| ------- | --------------------------------- | ------------------------------------- | ------------------------------------------- |
| `GET`   | `/api/tools/http-tool`            | `tools/http-tool/route.ts`            | Configuración/prueba de la herramienta HTTP |
| `POST`  | `/api/tools/http-tool`            | `tools/http-tool/route.ts`            | Crear herramienta HTTP                      |
| `GET`   | `/api/tools/web-page-summary`     | `tools/web-page-summary/route.ts`     | Herramienta de resumen de páginas web       |
| `POST`  | `/api/tools/web-page-summary`     | `tools/web-page-summary/route.ts`     | Resumir una URL                             |
| `GET`   | `/api/tools/youtube-summary`      | `tools/youtube-summary/route.ts`      | Herramienta de resumen de YouTube           |
| `POST`  | `/api/tools/youtube-summary`      | `tools/youtube-summary/route.ts`      | Resumir un vídeo de YouTube                 |
| `GET`   | `/api/agents/[id]/tools`          | `agents/[id]/tools/route.ts`          | Listar herramientas para un agente          |
| `PATCH` | `/api/agents/[id]/tools/[toolId]` | `agents/[id]/tools/[toolId]/route.ts` | Actualizar configuración de la herramienta  |

***

## Tipos de herramientas

| Tipo de herramienta | Descripción                                               | Almacenado como                  |
| ------------------- | --------------------------------------------------------- | -------------------------------- |
| `http`              | Herramienta de solicitud HTTP personalizada (llamada API) | `config: HttpToolConfig`         |
| `agent`             | Delegación de subagente (especialista)                    | `config: { targetAgentId, ... }` |
| `web_page_summary`  | Resumir contenido de una URL                              | Integrado, sin configuración     |
| `youtube_summary`   | Resumir un vídeo de YouTube                               | Integrado, sin configuración     |

***

## Esquema de configuración de la herramienta HTTP

```ts theme={null}
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

Todas las configuraciones de herramientas se almacenan como `Prisma.InputJsonObject` en la columna `Tool.config`. Al leer, emita apropiadamente:

```ts theme={null}
const config = tool.config as HttpToolConfig | null;
```

***

## Resumen de la página web

La herramienta `web-page-summary` busca una URL y utiliza IA para resumir su contenido. Notas clave de implementación:

* 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

La herramienta `youtube-summary` extrae transcripciones de videos y las resume:

* 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

Cuando un agente tiene herramientas:

```ts theme={null}
// 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`.