AI Chat documentation

content/guides/10.ai/1.chat/.navigation.yml

@@ -0,0 +1,3 @@
+title: AI Chat
+headline: AI Chat
+---

content/guides/10.ai/1.chat/0.index.md

@@ -0,0 +1,82 @@
+---
+title: Overview
+description: Chat with an AI assistant directly inside Directus. Create content, manage your schema, trigger automations, and explore your data through natural conversation.
+---
+
+Directus AI Chat is an embedded conversational assistant that helps you interact with your Directus instance through natural language.
+
+<video title="AI Chat creating a blog post" autoplay playsinline muted loop controls class="rounded-md">
+  <source src="/video/ai-chat-blog-post.mp4" type="video/mp4" />
+</video>
+
+::callout{icon="material-symbols:science" color="warning"}
+**AI Chat is currently in beta.** Features and tools may change as we refine the experience based on feedback.
+::
+
+::callout{icon="material-symbols:info" color="info"}
+**AI Chat requires an OpenAI or Anthropic API key.** Administrators [configure API keys](/guides/ai/chat/setup) in Settings → AI.
+::
+
+## What can AI Chat do?
+
+- **Content Management**: Create, update, and organize items across your collections
+- **Schema Operations**: Explore your data model, add new fields and collections
+- **Flow Automation**: Create new Flows and trigger them manually
+- **Data Exploration**: Query your data and understand your schema structure
+
+## Supported Models
+
+### :icon{name="i-simple-icons-openai" class="align-middle mr-1 size-5"} OpenAI
+
+| Model | Model ID | Context Window Size |
+|-------|----------|---------|
+| GPT-5 Nano | `gpt-5-nano` | 400k tokens |
+| GPT-5 Mini | `gpt-5-mini` | 400k tokens |
+| GPT-5 | `gpt-5` | 400k tokens |
+
+### :icon{name="i-simple-icons-claude" class="align-middle mr-1 size-5"} Anthropic
+
+| Model | Model ID | Context Window Size |
+|-------|----------|---------|
+| Claude Haiku 4.5 | `claude-haiku-4-5` | 200k tokens |
+| Claude Sonnet 4.5 | `claude-sonnet-4-5` | 200k tokens |
+
+Want additional models or features? [Submit a request on our roadmap](https://roadmap.directus.io/).
+
+## Key Features
+
+- **Tool Approval**: All tools require approval by default. [Configure per-tool settings](/guides/ai/chat/tools#tool-behavior).
+- **Uses Your Permissions**: The AI operates with your existing Directus role and access policies.
+- **Streaming Responses**: Responses stream in real-time. Stop or retry at any time.
+
+::callout{icon="material-symbols:warning" color="warning"}
+**Conversations are stored in your browser only.** They are not saved to the server or shared between devices. Closing your browser or clearing localStorage will delete your conversation history.
+::
+
+---
+
+## Get Started
+
+::card-group
+
+:::card{title="Admin Setup" icon="material-symbols:settings" to="/guides/ai/chat/setup"}
+Configure API keys and customize the AI assistant behavior.
+:::
+
+:::card{title="User Guide" icon="material-symbols:chat" to="/guides/ai/chat/usage"}
+Learn how to use AI Chat effectively in your daily workflow.
+:::
+
+:::card{title="Available Tools" icon="material-symbols:construction" to="/guides/ai/chat/tools"}
+Reference of all tools the AI can use to interact with Directus.
+:::
+
+:::card{title="Tips & Best Practices" icon="material-symbols:lightbulb" to="/guides/ai/chat/tips"}
+Get the most out of AI Chat with practical tips and example prompts.
+:::
+
+:::card{title="Security" icon="material-symbols:security" to="/guides/ai/chat/security"}
+Access control, data protection, and security considerations.
+:::
+
+::

content/guides/10.ai/1.chat/1.setup.md

@@ -0,0 +1,187 @@
+---
+title: Setup
+description: Configure AI Chat by adding your AI provider API keys and customizing assistant behavior.
+headline: AI Chat
+---
+
+AI Chat 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 OpenAI or Anthropic (see below)
+- Users must have **App access** - Public (non-authenticated) or API-only users cannot use AI Chat
+
+::callout{icon="material-symbols:info" color="info"}
+Note that all users of AI Chat 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](https://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](https://platform.openai.com/api-keys))
+3. Click **Create new secret key**
+4. Give it a name like "Directus AI Chat"
+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).
+
+1. Go to [console.anthropic.com](https://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 Chat"
+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.
+::
+
+:::
+
+::
+
+## Configure API Keys in Directus
+
+::steps{level="3"}
+
+### Navigate to AI Settings
+
+Go to **Settings → AI** in the Directus admin panel.
+
+![AI Settings page in Directus](/img/ai-chat-settings-disabled.png)
+
+### Enter Your API Key
+
+Add your API key for one or both providers:
+
+- **OpenAI API Key** - Enables GPT-5 models
+- **Anthropic API Key** - Enables Claude models
+
+::callout{icon="material-symbols:security" color="info"}
+API keys are encrypted at rest in the database and masked in the UI.
+::
+
+### Save Settings
+
+Click **Save** to apply your changes. AI Chat is now available to all users with [App access](/guides/auth/access-control#studio-users).
+
+::
+
+## Custom System Prompt
+
+Optionally customize how the AI assistant behaves in **Settings → AI → Custom System Prompt**.
+
+The [default system prompt](https://github.com/directus/directus/blob/main/api/src/ai/chat/constants/system-prompt.ts) 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"}
+
+```xml
+<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.
+
+## Managing Costs
+
+::callout{icon="material-symbols:warning" color="warning"}
+**AI Chat 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) for simple tasks
+- Disable unused tools - disabled tools are not loaded into context, reducing token usage
+- Set spending limits in your [OpenAI](https://platform.openai.com/settings/organization/limits) or [Anthropic](https://console.anthropic.com/) dashboard
+
+## Next Steps
+
+::card-group
+
+:::card{title="User Guide" icon="material-symbols:chat" to="/guides/ai/chat/usage"}
+Learn how users interact with AI Chat.
+:::
+
+:::card{title="Available Tools" icon="material-symbols:construction" to="/guides/ai/chat/tools"}
+See what actions the AI can perform.
+:::
+
+:::card{title="Tips & Best Practices" icon="material-symbols:lightbulb" to="/guides/ai/chat/tips"}
+Get the most out of AI Chat.
+:::
+
+:::card{title="Security" icon="material-symbols:security" to="/guides/ai/chat/security"}
+Access control and data protection.
+:::
+
+::