API de ferramentas

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

​

Tipos de ferramentas

​

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

​

Armazenamento de configuração de ferramentas

const config = tool.config as HttpToolConfig | null;

​

Resumo da página da web

• 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

• 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

// 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.