> ## 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 ferramentas

> Referência interna para a API de ferramentas — configuração de ferramenta HTTP, resumo de página da web, ferramentas de resumo do YouTube e gerenciamento de ferramentas de agente.

> **Documentação interna para desenvolvedores.** Esta página aborda a API de ferramentas: ferramenta CRUD, configuração de ferramenta HTTP e tipos de ferramentas de IA integradas. Não se destina a usuários finais.

***

## Mapa de rotas

| Método  | Ponto final                       | Arquivo manipulador                   | Descrição                              |
| ------- | --------------------------------- | ------------------------------------- | -------------------------------------- |
| `GET`   | `/api/tools/http-tool`            | `tools/http-tool/route.ts`            | Configuração/teste da ferramenta HTTP  |
| `POST`  | `/api/tools/http-tool`            | `tools/http-tool/route.ts`            | Criar ferramenta HTTP                  |
| `GET`   | `/api/tools/web-page-summary`     | `tools/web-page-summary/route.ts`     | Ferramenta de resumo de páginas da web |
| `POST`  | `/api/tools/web-page-summary`     | `tools/web-page-summary/route.ts`     | Resuma um URL                          |
| `GET`   | `/api/tools/youtube-summary`      | `tools/youtube-summary/route.ts`      | Ferramenta de resumo do YouTube        |
| `POST`  | `/api/tools/youtube-summary`      | `tools/youtube-summary/route.ts`      | Resuma um vídeo do YouTube             |
| `GET`   | `/api/agents/[id]/tools`          | `agents/[id]/tools/route.ts`          | Listar ferramentas para um agente      |
| `PATCH` | `/api/agents/[id]/tools/[toolId]` | `agents/[id]/tools/[toolId]/route.ts` | Atualizar configuração da ferramenta   |

***

## Tipos de ferramentas

| Tipo de ferramenta | Descrição                                                     | Armazenado como                  |
| ------------------ | ------------------------------------------------------------- | -------------------------------- |
| `http`             | Ferramenta de solicitação HTTP personalizada (chamada de API) | `config: HttpToolConfig`         |
| `agent`            | Delegação de subagente (especialista)                         | `config: { targetAgentId, ... }` |
| `web_page_summary` | Resuma o conteúdo de um URL                                   | Integrado, sem configuração      |
| `youtube_summary`  | Resuma um vídeo do YouTube                                    | Integrado, sem configuração      |

***

## Esquema de configuração da ferramenta 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
}
```

***

## Armazenamento de configuração de ferramentas

Todas as configurações da ferramenta são armazenadas como `Prisma.InputJsonObject` na coluna `Tool.config`. Ao ler, lance adequadamente:

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

***

## Resumo da página da web

A ferramenta `web-page-summary` busca uma URL e usa IA para resumir seu conteúdo. Principais notas de implementação:

* Respeita `robots.txt` (não ignore)
* Tamanho máximo do conteúdo: 500 KB (truncado se for maior)
* Tempo limite: 15 segundos
* Retorna: `{ url, title, summary, extractedAt }`

***

## Resumo do YouTube

A ferramenta `youtube-summary` extrai transcrições de vídeo e as resume:

* Usa API de dados do YouTube ou extração de transcrição (verifique a implementação atual)
* Volta à descrição se a transcrição não estiver disponível
* Retorna: `{ videoId, title, summary, duration }`

***

## Gerenciamento de ferramentas de agente

Quando um agente possui ferramentas:

```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 conhecidos/pegadinhas

* **Exposição secreta da ferramenta HTTP:** O campo `auth.value` armazena chaves/tokens de API. Nunca devolva-os em respostas `GET` – mascare com `***` ou omita. Defina novos valores apenas por meio de `PATCH`.
* **Risco de injeção de ferramenta HTTP:** Os campos `url` e `body` suportam variáveis ​​de modelo. Valide que a substituição de variável não pode ser usada para SSRF (bloqueie intervalos de IP internos: `10.x`, `172.16-31.x`, `192.168.x`, `127.x`, `169.254.x`).
* **Ferramentas especializadas** (`type: 'agent'`) usam a mesma tabela `Tool`, mas têm uma estrutura `config` completamente diferente das ferramentas HTTP. Sempre verifique `tool.type` antes de ler `config`.