The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
Supabase Assistant code guide
Start here when working on the Assistant in Studio. This guide maps the implementation for contributors and coding agents. Follow Studio's agent instructions and load the skills that apply to your change.
Request flow
flowchart TD
UI[AssistantChat] --> State[ai-assistant-state: chat transport]
State --> API[POST /api/ai/sql/generate-v4]
API --> Access[Resolve organization access and model]
Access --> Tools[getTools]
Tools --> Response[generateAssistantResponse]
Response --> Stream[Stream messages and tool calls to the UI]
Stream --> Parts[Message.Parts: render text and tool cards]
Parts --> Approval[User approves a tool when required]
Approval --> State
The sidebar provider mounts AIAssistant. AssistantChat manages the active conversation UI and supplies project and organization context to ai-assistant-state.
The state module owns the AI SDK chat instances, request transport, chat persistence, and approval continuation. Its transport sends messages to generate-v4, which validates and authenticates the request, resolves access and the model, builds tools, and streams the response. The TanStack route adapts this same handler. Keep both runtimes in mind; see the migration guide.
generateAssistantResponse combines prompts, context, prepared conversation history, and tools for the model. Message.Parts dispatches streamed message parts to their UI renderers. Approval responses travel back through the chat transport so the server can continue tool execution.
Rules to keep
- Enforce access in code. Resolve organization/project access on the server and keep the restrictive fallback for an unverified pairing. Prompts and UI visibility are not authorization checks.
- Keep execution approval separate from data sharing. Full data opt-in does not approve AI-generated SQL execution. Promote untrusted SQL only after explicit user approval.
- Protect results on every model path. Apply output filtering to both live tool results and replayed history. Raising opt-in must not expose SQL results collected under a lower level.
- Keep the tool allowlist. Register tools explicitly and declare their minimum opt-in level. Remote MCP tools must pass the filter; the remote server's read-only setting does not replace it.
- Keep request context out of the shared system prompt. Put project, chat, clock, and logs context in
assistant-context.tsto preserve provider caching. - Keep tool contracts safe to import in the browser. Shared contracts contain schemas and pure output transformations; database calls and other server execution belong in the server implementation.
- Preserve both runtimes. Keep the TanStack adapter and Next.js handler aligned. The chat route currently delegates to the shared handler; do not remove that handler while the adapter uses it.
Where to make changes
Chat and rendering
| Change | Start here |
|---|---|
| Panel layout, chat selection, and header | AIAssistant.tsx, AIAssistantHeader.tsx |
| Composer, attachments, and sending messages | AssistantChat.tsx, AssistantChatForm.tsx |
| Chat state, persistence, transport, and selected model | ai-assistant-state.tsx |
| Message rendering and tool-specific cards | Message.Parts.tsx, Message.Parts.utils.ts |
| SQL results and charts | AssistantQueryCell.tsx, AssistantQueryCell.utils.ts |
| Approval UI | Confirm.tsx, Confirm.utils.ts |
Model requests and context
| Change | Start here |
|---|---|
| Chat endpoint and request validation | generate-v4.ts |
| Model streaming and response orchestration | generate-assistant-response.ts |
| System instructions and topic knowledge | prompts.ts; load_knowledge topics in knowledge-topics.ts |
| Project, chat, clock, and logs context | assistant-context.ts, assistant-message-metadata.ts |
| History preparation and output sanitization | generate-assistant-response.utils.ts, tool-sanitizer.ts, registry.ts |
| Model catalog, defaults, and provider configuration | model.utils.ts, model.ts, bedrock.ts; entitlement and throttling decisions in generate-v4.ts |
| Tracing and feedback | braintrust-logger.ts, feedback API, rate-message-mutation.ts |
Keep per-request context in assistant-context.ts. The shared system prompt is deliberately static for provider caching.
Tools
| Change | Start here |
|---|---|
| Tool assembly and platform/self-hosted selection | tools/index.ts |
| Allowlist, minimum opt-in levels, and blocked-tool responses | tool-filter.ts |
| Studio tool assembly and opt-in requests | studio-tools.ts |
| Remote MCP connection and tool selection | supabase-mcp.ts, mcp-tools.ts |
| Schema and policy tools | schema-tools.ts |
| Reports, notebooks, incidents, and support | report-tools.ts, notebook-tools.ts, incident-tools.ts, support-tools.ts |
| Self-hosted tools | fallback-tools.ts |
| Contract-based tools (see Tool contracts) | registry.ts lists them in TOOL_CONTRACTS (and remote MCP tools in REMOTE_TOOL_CONTRACTS); types.ts, tool-from-contract.ts |
Tools are moving to contracts; the rest declare their schemas and output handling directly. registry.ts is the source of truth for which are which: a tool in TOOL_CONTRACTS or REMOTE_TOOL_CONTRACTS is a contract tool.
For a new or changed tool:
- Prefer a contract for a new tool. Otherwise implement it in the appropriate tool module.
- Include it in
getToolsthrough the module's tool getter, and add its name to the allowlist intool-filter.ts. A contract, local or remote, declares minimum access asminOptInLevel; other tools useTOOL_CATEGORY_MAP. - Decide whether execution needs user approval and what output may reach the model, including on history replay. Read the SQL safety skill before changing SQL execution.
- Update
Message.Parts.tsxand its helpers if the tool needs a UI renderer. - Update relevant tests, mock tools, and evaluation cases. See local development and validation.
Tool contracts
A contract declares a tool once: name, description, input and output schemas, minOptInLevel, needsApproval, and toModelOutput, which decides what the model may see of the output. The registry also applies toModelOutput to persisted outputs when it replays history, so it must be safe to run on its own result.
Each contract tool is a pair of files named after the tool, plus an optional output helper:
<tool-name>.tsexportscontract. The browser imports it, so it contains only zod schemas and pure functions, with no data-layer or other server imports.<tool-name>.server.tsexportscreateTool, which builds the executable tool from the contract withtoolFromContract, orapprovalGatedToolFromContractwhenneedsApprovalis true.<tool-name>-output.tsholds output schemas and transformations that outgrow the contract file.
update-notebook.ts and update-notebook.server.ts show the split with approval. update-opt-in-level.ts shows createInputSchema, for a tool whose stored input depends on the request: the SDK stores the parsed input, so the contract's inputSchema describes the stored shape and the per-request schema is built from the context. execute-sql.ts shows an output schema that also accepts an older persisted shape.
To migrate a tool to a contract:
- Create
<tool-name>.tsand<tool-name>.server.ts, moving the schemas, description, andexecuteout of the old definition. - Make
outputSchemaaccept every shape already saved in chat history, normalizing older ones with a union and transform. SetoutputOnInvalidif the model should see something other than nothing when a saved output doesn't parse. - Register the contract in
TOOL_CONTRACTS, and composecreateToolinto the module's tool getter. - Remove the tool from
TOOL_CATEGORY_MAP. Keep it in the allowlist intool-filter.ts. - Delete any per-tool sanitizer. tool-sanitizer.ts only delegates to
sanitizeContractPart. - Replace imports of the old inline schemas in the UI, evals, and
generate-assistant-response.tswithcontract.inputSchema,contract.outputSchema, orToolContractInput/ToolContractOutput. - Test the contract's
toModelOutputat every opt-in level and on history replay, in registry.test.ts and tool-sanitizer.test.ts as applicable. - Call out any change to what the model sees or to the stored shape in the PR description.
Remote contracts
A tool the remote MCP server implements has a RemoteToolContract: only name, minOptInLevel, and needsApproval. The server owns the description, input schema, execution, and output, so there is no .server.ts file and its parts stay dynamic-tool, outside StudioUIMessage. Register it in REMOTE_TOOL_CONTRACTS and remove it from TOOL_CATEGORY_MAP; mcp-tools.ts applies needsApproval, since MCP tool definitions can't declare it. list-extensions.ts is an example.
Access and data sharing
These checks have different responsibilities:
| Responsibility | Implementation |
|---|---|
| Resolve the saved organization opt-in tags for the UI | useOrgOptedIntoAi.ts |
| Resolve server-side access for an organization/project pair | ai-details.ts |
| Check permission to change organization settings | useCheckPermissions.ts, used by OptInRequest.tsx and AIOptInModal.tsx |
| Save organization opt-in settings | useAIOptInForm.ts, DataPrivacyForm.tsx |
| Gate tool availability by opt-in level | tool-filter.ts |
| Approve SQL execution and call the database | execute-sql.ts (approval) and execute-sql.server.ts (execution), using execute-sql-mutation.ts |
| Control which SQL results reach the model | toModelOutput in execute-sql-output.ts, applied to live results by the SDK and to history by registry.ts |
The opt-in levels are disabled, schema, schema_and_log, and schema_and_log_and_data. execute_sql is available at every level and requires user approval; sharing its result rows with the model requires schema_and_log_and_data. History sanitization also considers the level stamped on the original SQL output. Permission to change opt-in settings, user approval to run SQL, and the database's authorization checks are separate from result sharing.
The model can call update_opt_in_level with requiredLevel to request higher access, or without requiredLevel when the user asks to review or change the setting. Every call requires approval through the opt-in request card, even when the organization already has the requested level. If the requested level is already satisfied, the contract's createInputSchema transform removes requiredLevel and treats the call as a review request; levelWhenAsked records the organization's level when the call was made.
On platform, the endpoint resolves organization access and getTools includes platform tools when an access token is available. It also registers the opt-in request tool. Self-hosted requests use the schema level and fallback tools instead of the platform tool set. Check getTools and generate-v4 when changing either environment.
Related AI features
The chat Assistant shares code with other Studio AI features, but those have separate endpoints:
- pages/api/ai/sql/ contains policy generation, SQL title, filter, and cron helpers alongside the chat endpoint.
- pages/api/ai/code/complete.ts handles code completions.
- pages/api/ai/onboarding/design.ts handles onboarding design.
- data/ai/ contains client queries and mutations for AI helpers and feedback. The chat transport itself lives in
ai-assistant-state.tsx. - routes/api/ai/ contains the corresponding TanStack API adapters.
Local development and validation
Use the Studio setup instructions for the application and backend configuration. From the repository root, pnpm dev:studio starts Studio on port 8082 by default. The chat endpoint currently selects the OpenAI provider, which requires a server-side OPENAI_API_KEY; see model.ts. A self-hosted session exercises the fallback tool set, so use a platform development environment when working on platform-only tools or organization settings.
Tests are colocated with the implementation under lib/ai/, components/ui/AIAssistantPanel/, and state/. For example, from apps/studio:
pnpm exec vitest run lib/ai/tool-filter.test.ts lib/ai/tools/studio-tools.test.ts
Use the Assistant evaluation guide for behavioral datasets, local evaluation commands, CI labels, and scoring. dataset.ts contains scenarios and mock-tools.ts supplies tool behavior for evaluations. The browser test is assistant.spec.ts; read the E2E setup guide before running it.
Update this map when moving entry points or changing the request/tool lifecycle.