Setup

AI Assistant requires an API key from a supported AI provider. This page covers the administrator setup process.

Requirements

• Administrator access to your Directus instance
• API key from at least one supported provider: OpenAI, Anthropic, or Google (see below)
• Users must have App access - Public (non-authenticated) or API-only users cannot use AI Assistant
• AI Assistant can be disabled at the infrastructure level using the AI_ENABLED environment variable

Alternatively, you can use an OpenAI-compatible provider like Ollama or LM Studio for self-hosted models.

::callout{icon="material-symbols:info" color="info"} Note that all users of AI Assistant will share a single API key from your configured provider. Usage limits and costs will be shared across all users. See your provider's dashboard for monitoring usage details and costs. ::

Get an API Key

You'll need an API key from at least one provider. Choose based on which models you want to use.

::accordion{type="single"}

:::accordion-item{label="OpenAI" icon="i-simple-icons-openai"}

OpenAI provides GPT-5 models (Nano, Mini, Standard).

1. Go to platform.openai.com and sign in or create an account
2. Navigate to API Keys in the left sidebar (or go directly to platform.openai.com/api-keys)
3. Click Create new secret key
4. Give it a name like "Directus AI Assistant"
5. Copy the key immediately - you won't be able to see it again

::callout{icon="material-symbols:info" color="info"} OpenAI requires a payment method and has usage-based pricing. Set spending limits in Settings → Limits to control costs. ::

:::

:::accordion-item{label="Anthropic" icon="i-simple-icons-anthropic"}

Anthropic provides Claude models (Haiku 4.5, Sonnet 4.5, Opus 4.5).

1. Go to console.anthropic.com and sign in or create an account
2. Navigate to API Keys in the settings
3. Click Create Key
4. Give it a name like "Directus AI Assistant"
5. Copy the key immediately

::callout{icon="material-symbols:info" color="info"} Anthropic requires a payment method and has usage-based pricing. Monitor usage in the Console dashboard. ::

:::

:::accordion-item{label="Google AI" icon="i-simple-icons-googlegemini"}

Google provides Gemini models (2.5 Flash, 2.5 Pro, 3 Flash Preview, 3 Pro Preview).

1. Go to aistudio.google.com and sign in with your Google account
2. Click Get API Key in the left sidebar
3. Click Create API Key
4. Select or create a Google Cloud project
5. Copy the generated API key

::callout{icon="material-symbols:info" color="info"} Google AI Studio offers a free tier with rate limits. For production use, consider enabling billing in Google Cloud Console to increase quotas. ::

:::

::

Configure Providers in Directus

::steps{level="3"}

Navigate to AI Settings

Go to Settings → AI in the Directus admin panel.

Enter Your API Keys

Add your API key for one or more providers:

• OpenAI API Key - Enables GPT-4 and GPT-5 models
• Anthropic API Key - Enables Claude models
• Google API Key - Enables Gemini models

::callout{icon="material-symbols:security" color="info"} API keys are encrypted at rest in the database and masked in the UI. ::

Configure Allowed Models

For each provider, you can restrict which models are available to users. Use the Allowed Models dropdown next to each API key field to select the models users can choose from.

• If no models are selected, no models from that provider will be available
• You can add custom model IDs by typing them and pressing Enter (useful when new models are released)

This is useful for:

• Controlling costs by limiting access to expensive models
• Ensuring compliance by only allowing approved models
• Simplifying the user experience by reducing model choices

Save Settings

Click Save to apply your changes. AI Assistant is now available to all users with App access.

::

OpenAI-Compatible Providers

In addition to the built-in providers, Directus supports any OpenAI-compatible API endpoint. This allows you to use self-hosted models, alternative providers, or private deployments.

::callout{icon="material-symbols:warning" color="warning"} For best results, use built-in cloud providers. Local models vary significantly in their tool-calling capabilities and may produce inconsistent results. If using OpenAI-compatible providers, we recommend cloud-hosted frontier models over locally-run models on personal hardware. ::

::callout{icon="material-symbols:info" color="info"} File attachments are not supported with OpenAI-compatible providers. File uploads require a built-in provider (OpenAI, Anthropic, or Google). The file attachment buttons are hidden when an OpenAI-compatible model is selected. ::

Configuration

In Settings → AI, scroll to the OpenAI-Compatible section and configure:

Model Configuration

For each model, you can specify:

::callout{icon="material-symbols:info" color="info"} The Provider Options field allows you to pass provider-specific parameters to the AI SDK. This is useful for enabling features like extended thinking or custom sampling parameters. See the Vercel AI SDK documentation for details. ::

Example Configurations

::accordion{type="single"}

:::accordion-item{label="Ollama" icon="i-simple-icons-ollama"}

Ollama lets you run open-source models locally.

1. Install Ollama and pull a model: ollama pull gpt-oss:20b
2. Ollama runs on http://localhost:11434 by default

Directus Configuration:

• Provider Name: Ollama
• Base URL: http://localhost:11434/v1
• API Key: ollama (required by the OpenAI SDK but ignored by Ollama)
• Models: Add your pulled models (e.g., gpt-oss:20b, gpt-oss:120b, qwen3:8b)

::callout{icon="material-symbols:info" color="info"} You can copy an existing model to an OpenAI-compatible name if needed: ollama cp gpt-oss:20b gpt-4 ::

See Ollama OpenAI compatibility docs for supported endpoints and features.

:::

:::accordion-item{label="Azure OpenAI" icon="i-simple-icons-microsoftazure"}

Azure OpenAI Service provides OpenAI models through Microsoft Azure.

1. Create an Azure OpenAI resource in the Azure portal
2. Deploy a model (e.g., GPT-4, GPT-4o)
3. Get your endpoint and API key from the Develop tab in your resource

Directus Configuration:

• Provider Name: Azure OpenAI
• Base URL: https://YOUR-RESOURCE.openai.azure.com/openai/v1
• API Key: Your Azure OpenAI API key
• Models: Add your deployed model names

::callout{icon="material-symbols:info" color="info"} The v1 API (August 2025+) no longer requires an api-version header. If using an older API version, add api-version as a custom header (e.g., 2024-10-21). ::

See Azure OpenAI documentation for setup details.

:::

:::accordion-item{label="Mistral AI" icon="simple-icons:mistralai"}

Mistral AI provides high-performance open and commercial models.

1. Create an account at console.mistral.ai
2. Generate an API key

Directus Configuration:

• Provider Name: Mistral
• Base URL: https://api.mistral.ai/v1
• API Key: Your Mistral API key
• Models: Add models like mistral-large-latest, mistral-small-latest, codestral-latest

See Mistral AI documentation for available models and pricing.

:::

::

Custom System Prompt

Optionally customize how the AI assistant behaves in Settings → AI → Custom System Prompt.

The default system prompt provides the AI with helpful instructions on how to interact with Directus and is tuned to provide good results.

If you choose to customize the system prompt, it's recommended to use the following template as a starting point:

::accordion{type="single"}

:::accordion-item{label="View Default System Prompt" icon="material-symbols:code"}

<behavior_instructions>
You are **Directus Assistant**, a Directus CMS expert with access to a Directus instance through specialized tools

## Communication Style

- **Be concise**: Users prefer short, direct responses. One-line confirmations: "Created collection 'products'"
- **Match the audience**: Technical for developers, plain language for content editors
- **NEVER guess**: If not at least 99% about field values or user intent, ask for clarification

## Tool Usage Patterns

### Discovery First

1. Understand the user's task and what they need to achieve.
2. Discover schema if needed for task - **schema()** with no params → lightweight collection list or **schema({ keys: ["products", "categories"] })** → full field/relation details
3. Use other tools as needed to achieve the user's task.

### Content Items

- Use `fields` whenever possible to fetch only the exact fields you need
- Use `filter` and `limit` to control the number of fetched items unless you absolutely need larger datasets
- When presenting repeated structured data with 4+ items, use markdown tables for better readability

### Schema & Data Changes

- **Confirm before modifying any schema**: Collections, fields, relations always need approval from the user.
- **Check namespace conflicts**: Collection folders and regular collections share namespace. Collection folders are distinct from file folders.

### Safety Rules

- **Deletions require confirmation**: ALWAYS ask before deleting anything
- **Warn on bulk operations**: Alert when affecting many items ("This updates 500 items")
- **Avoid duplicates**: Never create duplicates if you can't modify existing items
- **Use semantic HTML**: No classes, IDs, or inline styles in content fields (unless explicitly asked for by the user)
- **Permission errors**: Report immediately, don't retry

### Behavior Rules

- Call tools immediately without explanatory text
- Use parallel tool calls when possible
- If you don't have access to a certain tool, ask the user to grant you access to the tool from the chat settings.
- If there are unused tools in context but task is simple, suggest disabling unused tools (once per conversation)

## Error Handling

- Auto-retry once for clear errors ("field X required")
- Stop after 2 failures, consult user
- If tool unavailable, suggest enabling in chat settings
</behavior_instructions>

:::

::

Leave blank to use the default behavior.

Prompts Collection

Enable reusable prompts in AI Assistant by configuring a prompts collection:

1. Go to Settings → AI → Model Context Protocol
2. Find AI Prompts Collection
3. Either generate a new collection or select an existing one

::callout{icon="material-symbols:info" color="info"} This is the same collection used by the MCP Server. Prompts created here are available in both AI Assistant and external MCP clients. This also requires MCP to be enabled. ::

For details on creating prompts with variables, see MCP Prompts.

Managing Costs

::callout{icon="material-symbols:warning" color="warning"} AI Assistant uses your own AI provider API keys. Every message and tool call costs money. Be mindful of usage, especially with larger models. You are responsible for the costs of your usage. ::

Tips for controlling costs:

• Use faster, cheaper models (GPT-5 Nano, Claude Haiku 4.5, Gemini 2.5 Flash) for simple tasks
• Use Allowed Models to restrict access to expensive models
• Disable unused tools - disabled tools are not loaded into context, reducing token usage
• Set spending limits in your provider dashboard:
  • OpenAI
  • Anthropic
  • Google AI
• Consider self-hosted models via OpenAI-compatible providers for cost control

Next Steps

::card-group

:::card{title="User Guide" icon="material-symbols:chat" to="/guides/ai/assistant/usage"} Learn how users interact with AI Assistant. :::

:::card{title="Available Tools" icon="material-symbols:construction" to="/guides/ai/assistant/tools"} See what actions the AI can perform. :::

:::card{title="Tips & Best Practices" icon="material-symbols:lightbulb" to="/guides/ai/assistant/tips"} Get the most out of AI Assistant. :::

:::card{title="Security" icon="material-symbols:security" to="/guides/ai/assistant/security"} Access control and data protection. :::

::