AI Agents Overview

The AI layer is ten task-scoped agents behind a single execution path. Each is a pure function of (structured input + grounded schema context) → LLM call → parsed structured output. Everything routes through one chokepoint, AgentRunner, which owns context assembly, prompt rendering, the provider call, response parsing, and a durable audit write to agent_runs. There is no shared conversational state between agents and no hidden background inference: an agent runs when you invoke it and writes exactly one accountable row.

The ten agents

• Script Review, risk-scores a change script: destructive ops, unbounded DML, lock/performance hazards, privilege escalation, and a proposed rollback.
• Natural Language → SQL, emits a single dialect-correct statement grounded on the connected schema.
• Schema Explorer Chat, conversational exploration with full FK-graph awareness.
• Error Diagnosis, root cause, error category, and corrected SQL for a failed query.
• Query Optimization, EXPLAIN-driven plan analysis, rewrite candidates, missing-index DDL.
• Auto-Rollback Generation, inverse SQL for a forward migration, with explicit irreversible-op enumeration.
• Change Impact Analysis, FK-graph BFS from touched tables; the model classifies each downstream edge.
• Release Summary Generator, plain-language release notes for non-technical approvers.
• Compliance Agent, evaluates a script against admin-defined rules (regex / LLM / hybrid).
• Anomaly Detection, deterministic stats over execution history, LLM only for the explainer.

Where it lives

Left navigation → AI Agents, one tab per agent. Provider and governance config live under Settings → AI (admin-only).

Provider model, bring your own key, keep your data

Simcha DB Studio is self-hosted and BYO-key. You configure a provider once; keys are stored in the internal settings store, encrypted at rest (AES-256-GCM via the same EncryptionService that protects connection passwords). Prompts are built and dispatched from your own backend, no Simcha-hosted relay sits in the path, and nothing leaves your environment except the outbound call to the provider endpoint you point at. Choose a local runtime (Ollama) and inference never leaves the host at all.

The provider catalog is served by GET /api/ai/providers:

• OpenAI, default gpt-4o. Base URL overridable via OPENAI_BASE_URL, model via OPENAI_DEFAULT_MODEL.
• Anthropic, default claude-sonnet-4-20250514. Overridable via ANTHROPIC_BASE_URL / ANTHROPIC_DEFAULT_MODEL / ANTHROPIC_API_VERSION.
• Azure OpenAI, endpoint URL, deployment name, API version, API key. Point at your resource's deployment rather than the public shape.
• AWS Bedrock, region required. Access keys / instance role (static keys, or blank to fall through the AWS credential chain: instance/task role, env, ~/.aws/credentials) or Assume an IAM role (role ARN assumed via STS, no long-lived keys). Auto-detects model families: Anthropic Claude, Meta Llama, Mistral, Amazon Titan/Nova, Cohere.
• Google Gemini, default gemini-1.5-pro. Overridable via GEMINI_BASE_URL / GEMINI_DEFAULT_MODEL.
• Ollama (local), fully on-host inference for air-gapped / regulated deployments. Endpoint defaults to http://127.0.0.1:11434. Zero egress.
• OpenAI-compatible endpoint, generic Chat Completions adapter for Groq, DeepSeek, Together, OpenRouter, xAI Grok, Mistral La Plateforme, Fireworks, vLLM, LM Studio, llama.cpp server, LocalAI, and any proxy exposing that shape.
• Augment, first-class option for Augment Code, driven by the official Auggie SDK (API-only, no local Auggie install). Run auggie token print and supply the tenant API URL as the endpoint, the token as the API key, and a model such as claude-sonnet-4-5.

Per-request controls (Settings → AI): maxTokens, temperature, timeoutMs, and free-form extraHeaders for provider quirks (e.g. OpenRouter's HTTP-Referer). The base-URL override is the seam for Azure, Bedrock proxies, and on-prem gateways, pin the endpoint and the model and the rest of the pipeline is unchanged.

License gating

The agent fleet is gated on the AI-enabled license flag (requireAI() on /api/ai), orthogonal to the Starter/Professional/Enterprise tier axis. No flag, no agents, the routes refuse before any provider call is made.

Operator controls (Settings → AI → Agent Behavior)

• Schema context table cap, 0 = uncapped (default). When set, agents truncate context and surface exactly what was dropped.
• Rate limiting, per-(user × agent) sliding window. Off by default; opt in with a per-minute cap.
• Response cache, content-addressed by sha256 of agent + input + prepared context. Off by default; configurable TTL. Deterministic replay for identical inputs.
• Async mode, off / opt-in / always. Async returns 202 + jobId; a worker drains the queue; the UI polls GET /api/ai/agents/jobs/:id.

Defaults are power-user posture: nothing capped, throttled, or cached unless an operator opts in.

Privacy & governance (admin-only)

Under Settings → AI → Privacy & Governance. Changing AI settings requires the admin role.

• AI agents enabled, admin kill-switch. When off, every agent refuses independent of the license flag.
• Schema context detail level, bounds what leaves the boundary: Names only, Names + types (default; types + nullability), or Full (adds column defaults).
• Excluded tables, never serialized into any prompt (case-insensitive, optional schema.table). Keep sensitive tables out of context entirely.
• Send sample row data, off by default. Off means metadata only, never rows. Enabling ships a few real rows per table to the provider for accuracy, leave off for sensitive databases.

Default egress is schema structure only: table/column names, types, nullability. No rows.

Audit and cost accounting

Every invocation writes to agent_runs: input/output summary only (full prompts are deliberately not persisted, keeping PII out of long-term storage), prompt/completion tokens, ms duration, model, status, user, connection ID. Async runs additionally write queue state to agent_jobs. Query via GET /api/ai/agents/:id/runs and GET /api/ai/agents/jobs.