Tools API

Internal documentation for developers. This page covers the Tools API: tool CRUD, HTTP tool configuration, and built-in AI tool types. Not intended for end users.

​

Route Map

​

Tool Types

​

HTTP Tool Config Schema

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
}

​

Tool Config Storage

const config = tool.config as HttpToolConfig | null;

​

Web Page Summary

• GET /api/tools/web-page-summary returns the latest three LLMTaskOutput rows where type = web_page_summary.
• POST /api/tools/web-page-summary requires the api-key header to match NEXTAUTH_SECRET.
• Request payload is validated with WebPageSummarySchema and includes url plus optional date.
• Page HTML is loaded through loadPageContent, stripped with Cheerio, chunked with splitTextByToken, and summarized with ChatModel.
• Chunk sizing uses ModelConfig[modelName].contextWindowTokens * 0.5; keep catalog context sizing on contextWindowTokens.
• JSON output requests use the OpenAI SDK response_format type carried by CallInput.
• Returns a persisted LLMTaskOutput payload with metadata, summary sections, and FAQ data.

curl -X POST "$APP_URL/api/tools/web-page-summary" \
  -H "api-key: $NEXTAUTH_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article"}'

​

YouTube Summary

• GET /api/tools/youtube-summary returns the latest three LLMTaskOutput rows where type = youtube_summary.
• POST /api/tools/youtube-summary is implemented in tools/youtube-summary/functions.ts and exposed by the route module.
• Request payload is validated with YoutubeSummarySchema; do not cast parsed payloads to any.
• Unauthenticated requests are rate limited with heavyRateLimiter; authenticated internal calls use the api-key header.
• Transcript chunks are sized from ModelConfig[summaryModel].contextWindowTokens * 0.5.
• Model calls are typed as Omit<CallInput, 'model'> before the concrete model name is attached.
• Chapter extraction uses the youtube_summary OpenAI tool schema; normal summaries and FAQs use direct ChatModel calls.
• Returns or upserts a persisted LLMTaskOutput with localized transcript, chapters, summary, and FAQ fields depending on options.

curl -X POST "$APP_URL/api/tools/youtube-summary" \
  -H "api-key: $NEXTAUTH_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=VIDEO_ID","options":{"summarize":true,"extractChapters":true}}'

​

Agent Tool Management

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

​

Known Issues / Gotchas

• HTTP tool secret exposure: The auth.value field stores API keys/tokens. Never return these in GET responses — mask with *** or omit. Only set new values via PATCH.
• HTTP tool injection risk: The url and body fields support template variables. Validate that variable substitution cannot be used for SSRF (block internal IP ranges: 10.x, 172.16-31.x, 192.168.x, 127.x, 169.254.x).
• Specialist tools (type: 'agent') use the same Tool table but have completely different config structure from HTTP tools. Always check tool.type before reading config.