# Usage

> Learn how to use AI Assistant to interact with your Directus instance through natural conversation.

This guide covers how to use AI Assistant effectively in your daily workflow.

## Opening AI Assistant

![AI Assistant button in Directus header](/img/ai-chat-collapsed-point.png)

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.

## Selecting a Model

![Model selector dropdown](/img/ai-chat-model-selector-cropped.png)

Click the model dropdown in the chat header to choose which AI model to use:

<table>
<thead>
  <tr>
    <th>
      Model
    </th>
    
    <th>
      Best For
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <icon name="logos:openai-icon">
        
      </icon>
      
       GPT-5 Nano / <icon name="logos:claude-icon">
        
      </icon>
      
       Claude Haiku 4.5 / <icon name="i-simple-icons-googlegemini">
        
      </icon>
      
       Gemini 3 Flash Preview
    </td>
    
    <td>
      Quick tasks, simple queries
    </td>
  </tr>
  
  <tr>
    <td>
      <icon name="logos:openai-icon">
        
      </icon>
      
       GPT-5 Mini
    </td>
    
    <td>
      Balanced speed and capability
    </td>
  </tr>
  
  <tr>
    <td>
      <icon name="logos:openai-icon">
        
      </icon>
      
       GPT-5 / <icon name="logos:claude-icon">
        
      </icon>
      
       Claude Sonnet 4.5 / <icon name="i-simple-icons-googlegemini">
        
      </icon>
      
       Gemini 3 Pro Preview
    </td>
    
    <td>
      Complex operations, detailed analysis
    </td>
  </tr>
</tbody>
</table>

Only models for [configured providers](/guides/ai/assistant/setup) appear in the dropdown.

## Having a Conversation

Type your message and press **Enter** to send (**Shift+Enter** for new line). Responses stream in real-time with full Markdown formatting.

## Adding Context

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.

![Context menu showing Prompts and Content options](/img/ai-assistant-context-menu.png)

Click the + button to open the context menu where you can search and browse available content.

### Prompts

![Prompts list in context menu](/img/ai-assistant-prompts.png)

Reusable prompt templates stored in your Directus instance. Prompts can include variables using `{{variable}}` syntax. A dialog appears to fill in values when needed.

![Prompt variables dialog](/img/ai-assistant-prompt-variables.png)

> "Write a blog post using our brand voice"

<callout color="info" icon="i-lucide-info">

Prompts require MCP to be enabled and a prompts collection configured. See [Prompts Collection](/guides/ai/assistant/setup#prompts-collection) for setup.

</callout>

### Content (Items)

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"

### Visual Elements

When using the [Visual Editor](/guides/content/visual-editor/studio-module), 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 color="primary" icon="i-lucide-lightbulb">

Visual element context persists while navigating within the Visual Editor but clears when leaving the module.

</callout>

### Files

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.

![Context menu showing Upload File and File Library buttons](/img/ai-assistant-context-menu-files.png)

Two options are available when a built-in provider (OpenAI, Anthropic, or Google) is selected:

- **Upload File** — Select files from your local machine
- **File Library** — Browse and select existing assets from Directus

You can also drag and drop files directly onto the conversation area.

<video title="Drag and drop files onto the AI Assistant conversation" autoPlay="true" playsInline="true" muted="true" loop="true" controls="true" className="rounded-md">
<source src="/docs/video/ai-assistant-file-drag-drop.mp4" type="video/mp4" />
</video>

#### Supported File Types

<table>
<thead>
  <tr>
    <th>
      Category
    </th>
    
    <th>
      Types
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Images
    </td>
    
    <td>
      JPEG, PNG, GIF, WebP
    </td>
  </tr>
  
  <tr>
    <td>
      Documents
    </td>
    
    <td>
      PDF, Plain Text
    </td>
  </tr>
  
  <tr>
    <td>
      Audio
    </td>
    
    <td>
      MP3, WAV
    </td>
  </tr>
  
  <tr>
    <td>
      Video
    </td>
    
    <td>
      MP4
    </td>
  </tr>
</tbody>
</table>

Maximum file size is 50MB. Files are uploaded to your AI provider when the message is sent.

<callout color="info" icon="i-lucide-info">

**File attachments require a built-in provider.** OpenAI-compatible providers do not support file uploads. See [Setup](/guides/ai/assistant/setup#openai-compatible-providers) for details.

</callout>

<callout color="warning" icon="i-lucide-triangle-alert">

**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.

</callout>

### Pending Context Bar

![Pending context bar with staged items](/img/ai-assistant-pending-context.png)

![Pending context bar with staged items and file thumbnails](/img/ai-assistant-context-menu-files.png)

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.

## Understanding Responses

AI Assistant displays several types of content in responses:

### Text Messages

Standard conversational responses with Markdown formatting.

### Reasoning Blocks

![Reasoning block showing AI's internal thinking](/img/ai-chat-reasoning-cropped.png)

Collapsible sections showing the AI's internal reasoning (extended thinking). Click to expand.

### Tool Calls

![Completed tool call showing results](/img/ai-chat-tool-call-complete-cropped.png)

When the AI performs an action, it displays a tool call card showing:

- The tool being used
- Input parameters
- Results after execution

### File References

![AI response showing an uploaded image inline](/img/ai-assistant-file-response.png)

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.

## Tool Approval

All tools require approval by default. When a tool needs approval, review the action then choose **Approve**, **Deny** (Esc), or **Always Allow**.

![Tool approval dialog showing approve, deny, and always allow options](/img/ai-chat-tool-approval-requested-cropped.png)

Configure per-tool approval settings via the gear icon in the chat header. See [Tool Behavior](/guides/ai/assistant/tools#tool-behavior) for details.

![Tool settings menu with approval modes](/img/ai-chat-tool-menu-open.png)

## Managing Conversations

### Clearing the Conversation

![Clear conversation button in chat header](/img/ai-chat-clear-conversation-cropped.png)

Click the clear button (trash icon) in the chat header to start fresh. This resets:

- Message history
- Token usage tracking

### Stopping a Response

While the AI is generating a response, the send button becomes a stop button. Click it to interrupt generation.

### Retrying After an Error

If an error occurs, a retry button appears. Click to regenerate the last response.

## Context Limits

<callout color="primary" icon="i-lucide-lightbulb">

Start a new conversation when switching topics. The AI performs better with focused, single-topic conversations. Long conversations may have older messages dropped automatically.

</callout>

## Data Storage

### What's Stored in Your Browser

- Conversation history
- Selected model preference
- Tool approval settings
- Chat open/closed state

### What's NOT Stored

- Conversations are **not saved to the Directus server**
- Conversations are **not shared** between users or devices
- Closing the browser or clearing local storage deletes history

## Permissions

The AI operates with your existing [Directus permissions](/guides/auth/access-control). If you don't have access to a collection or operation, neither does the AI. See [Security](/guides/ai/assistant/security) for more details.

## Next Steps

<card-group>
<card icon="i-lucide-wrench" title="Available Tools" to="/guides/ai/assistant/tools">

See what actions the AI can perform.

</card>

<card icon="i-lucide-lightbulb" title="Tips & Best Practices" to="/guides/ai/assistant/tips">

Get more out of AI Assistant with practical tips.

</card>

<card icon="i-lucide-shield" title="Security" to="/guides/ai/assistant/security">

Access control and data protection.

</card>
</card-group>