content/guides/11.ai/1.assistant/2.usage.md
This guide covers how to use AI Assistant effectively in your daily workflow.
Click the AI Assistant button in the Directus right sidebar to open the chat panel. The panel appears on the right side of your screen and persists as you navigate.
Click the model dropdown in the chat header to choose which AI model to use:
| Model | Best For |
|---|---|
| :icon{name="logos:openai-icon"} GPT-5 Nano / :icon{name="logos:claude-icon"} Claude Haiku 4.5 / :icon{name="i-simple-icons-googlegemini"} Gemini 3 Flash Preview | Quick tasks, simple queries |
| :icon{name="logos:openai-icon"} GPT-5 Mini | Balanced speed and capability |
| :icon{name="logos:openai-icon"} GPT-5 / :icon{name="logos:claude-icon"} Claude Sonnet 4.5 / :icon{name="i-simple-icons-googlegemini"} Gemini 3 Pro Preview | Complex operations, detailed analysis |
Only models for configured providers appear in the dropdown.
Type your message and press Enter to send (Shift+Enter for new line). Responses stream in real-time with full Markdown formatting.
Attach context to your messages using the Add Content button (+) next to the input field. Context helps the AI understand what you're working with and provide more relevant responses.
Click the + button to open the context menu where you can search and browse available content.
Reusable prompt templates stored in your Directus instance. Prompts can include variables using {{variable}} syntax. A dialog appears to fill in values when needed.
"Write a blog post using our brand voice"
::callout{icon="material-symbols:info" color="info"} Prompts require MCP to be enabled and a prompts collection configured. See Prompts Collection for setup. ::
Attach items from any collection as context. Select a collection, then choose items from the drawer. The item data is captured as a snapshot when you send your message.
"Make this product description match the style of the attached article"
When using the Visual Editor, you can add page elements as context. Click the AI icon on any editable element to add it as context. Hovering over visual element cards in the pending context bar highlights the corresponding element on the page.
"Translate this heading to Spanish"
::callout{icon="material-symbols:lightbulb" color="primary"} Visual element context persists while navigating within the Visual Editor but clears when leaving the module. ::
Upload files or select existing assets from your File Library to include as context. The AI can analyze images, read documents, and process audio and video.
Two options are available when a built-in provider (OpenAI, Anthropic, or Google) is selected:
You can also drag and drop files directly onto the conversation area.
<video title="Drag and drop files onto the AI Assistant conversation" autoplay playsinline muted loop controls class="rounded-md"> <source src="/docs/video/ai-assistant-file-drag-drop.mp4" type="video/mp4" /> </video>| Category | Types |
|---|---|
| Images | JPEG, PNG, GIF, WebP |
| Documents | PDF, Plain Text |
| Audio | MP3, WAV |
| Video | MP4 |
Maximum file size is 50MB. Files are uploaded to your AI provider when the message is sent.
::callout{icon="material-symbols:info" color="info"} File attachments require a built-in provider. OpenAI-compatible providers do not support file uploads. See Setup for details. ::
::callout{icon="material-symbols:warning" color="warning"} Google file uploads expire after approximately 24 hours. If you start a new conversation, you may need to re-upload files previously sent to Google. ::
Selected context appears in a horizontal bar above the input. Each card shows an icon and display name—click the x to remove. Image files show a thumbnail preview, while other file types show a file icon. You can add up to 10 context items per message.
AI Assistant displays several types of content in responses:
Standard conversational responses with Markdown formatting.
Collapsible sections showing the AI's internal reasoning (extended thinking). Click to expand.
When the AI performs an action, it displays a tool call card showing:
When the AI references uploaded files in its response, images display inline and can be clicked to open in a lightbox viewer. Non-image files appear as compact cards with a file icon and filename.
All tools require approval by default. When a tool needs approval, review the action then choose Approve, Deny (Esc), or Always Allow.
Configure per-tool approval settings via the gear icon in the chat header. See Tool Behavior for details.
Click the clear button (trash icon) in the chat header to start fresh. This resets:
While the AI is generating a response, the send button becomes a stop button. Click it to interrupt generation.
If an error occurs, a retry button appears. Click to regenerate the last response.
::callout{icon="material-symbols:lightbulb" color="primary"} Start a new conversation when switching topics. The AI performs better with focused, single-topic conversations. Long conversations may have older messages dropped automatically. ::
The AI operates with your existing Directus permissions. If you don't have access to a collection or operation, neither does the AI. See Security for more details.
::card-group
:::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 more out of AI Assistant with practical tips. :::
:::card{title="Security" icon="material-symbols:security" to="/guides/ai/assistant/security"} Access control and data protection. :::
::