AI Agents API

Base path /api/ai, gated by requireAI() (AI-enabled license flag). A single dispatcher runs every agent; the agent id selects the input/output contract while the route stays uniform. Provider and model come from settings (ai_provider, ai_api_key, ai_model) and can be overridden per-provider via the LLM env vars.

GET /api/ai/agents

{ "agents": [ "script-review", "nl-to-sql", "schema-explorer", "error-diagnosis",
              "query-optimization", "auto-rollback", "change-impact",
              "release-summary", "compliance", "anomaly-detection" ] }

POST /api/ai/agents/:id

Dispatches a run through AgentRunner. Body carries the agent input plus optional grounding context.

{ "input": { /* agent-specific */ },
  "context": { "connectionId": "uuid",   // optional; used by schema-grounded agents
               "dialect": "postgresql" } // optional; derived from the connection if omitted
}

Response

{ "ok": true,
  "result": { /* agent-specific output */ },
  "error": null,                 // set when ok=false
  "runId": "uuid",               // agent_runs row id
  "ms": 1234,
  "model": "claude-sonnet-4-20250514",
  "usage": { "promptTokens": 1240, "completionTokens": 380, "totalTokens": 1620 } }

Examples

POST /api/ai/agents/script-review
{ "input": { "script": "DROP TABLE users;", "dialect": "postgresql", "connectionId": "abc-123" } }

POST /api/ai/agents/nl-to-sql
{ "input": { "prompt": "Top 10 customers by revenue last quarter",
             "connectionId": "abc-123", "dialect": "postgresql" } }

Per-agent input/output shapes are documented in the AI Agents category.

Async jobs

Long-running agent work is tracked as jobs.

GET /api/ai/agents/:id/runs

Recent runs of one agent for the cost dashboard / anomaly feed. ?limit= (default 50, max 500).

{ "runs": [
    { "id": "uuid", "agent": "script-review", "status": "success", "model": "gpt-4o",
      "input_summary": "dialect=postgresql, 412c, schema=yes",
      "output_summary": "risk=high, findings=4",
      "cost_total_tok": 1820, "ms": 2380, "error_message": null,
      "created_at": "2026-04-29T08:55:39.787Z" } ] }

Providers, status, settings

Direct helpers

Convenience routes wrapping the two most-used agents.