Best Practices

Follow these tips to work effectively with AI Assistant and get better results from your conversations.

Be Specific About Collections and Fields

The more specific you are, the better results you'll get.

Less effective:

"Add a new post"

More effective:

"Create a new article in the articles collection with title 'Getting Started with Directus', status 'draft', and assign it to the 'Tutorials' category"

Complex Tasks

Break complex requests into smaller, more manageable steps:

"First, show me all products without descriptions"
"Now update product X with this description: ..."
"Next, do the same for product Y..."
"Finally, verify the products were updated correctly"

Start Fresh for New Topics

Long conversations can lose context. When switching to a different task, clear the conversation and start fresh.

Signs you should start a new conversation:

The AI seems confused about your schema
Responses are becoming less relevant
You're working on an unrelated task

Configure Tool Approvals

Read-only tools like Schema can safely be set to :icon{name="material-symbols:check" class="text-success"} Always Allowed
Keep write operations on :icon{name="material-symbols:approval-delegation" class="text-warning"} Needs Approval until you're confident
:icon{name="material-symbols:block" class="text-error"} Disable tools you don't need to reduce token usage

See Tool Behavior for more details.

Use Context Effectively

Context attachments help the AI understand what you're working with. See Adding Context for setup details.

When to attach context:

Asking about or modifying specific items
Comparing or batch-processing content
Making AI-assisted edits in the Visual Editor
Using prompts to maintain consistent formatting
Asking the AI to analyze or describe images
Providing reference documents (PDFs, text files) for content tasks
Sharing audio or video files for transcription or analysis

Keep in mind:

Maximum 10 context items per message
Context is captured as a snapshot when sent
Large items increase token usage

Visual Editor tips:

Add multiple elements as context before sending a message
Hover context cards to verify you've selected the right elements
Add elements from different pages—context persists while navigating

File attachment tips:

Use drag-and-drop for quick uploads from your desktop
Select from the File Library when referencing existing assets
Image files show previews; other types show a file icon
Files are uploaded to your AI provider — review Security for data handling details

Context Example Prompts

With Prompts attached:

Use the "Brand Voice" prompt to write a product announcement

Apply the "SEO Description" template to this page

With Items attached:

Compare these two products and highlight the differences

Update this article to match the tone of the attached reference

With Visual Elements attached:

Translate this section to French

Make this paragraph more concise while keeping the key points

Rewrite this heading to be more engaging

With Files attached:

Describe what's in this image

Summarize the key points from this PDF

Transcribe this audio recording

Manage Costs

AI Assistant requires API keys from OpenAI or Anthropic — you cannot use a ChatGPT Plus or Claude Pro subscription. API access is billed per token, so costs scale with usage. Be mindful of this, especially with larger models.

::callout{icon="material-symbols:paid" color="warning"} Disable tools you don't use. Disabled tools are not loaded into context, reducing token usage and API costs. If you only work with content, disable schema modification tools. ::

Example Prompts by Use Case

Content Management

Show me all published articles from this month

Create a new blog post titled "AI in Content Management" with status draft

Update all products in the "Summer Sale" category to have a 20% discount tag

Find articles without a featured image

Schema Operations

What fields does the products collection have?

Add a "featured" boolean field to the articles collection

Create a relationship between products and categories (many-to-many)

Show me how the pages collection is structured

Flow Automation

List all active flows

Create a flow that sends an email when a new order is placed

Trigger the "Generate Report" flow for all products

Data Exploration

How many users signed up last week?

Show me the 10 most recent orders

What's the relationship between articles and authors?

Find all items with status "pending review"

Common Gotchas

Permissions Apply

The AI operates with your user permissions. If you're receiving permissions errors in AI Assistant, it's likely the user account doesn't have the necessary permissions to perform the action.

Deletions Require Extra Care

The AI is instructed to ask for confirmation before deleting items. However, LLMs don't always follow instructions perfectly — keep destructive tools on "Ask" approval mode if you want guaranteed confirmation before deletions.

When deleting items that have relationships, consider cascade behavior:

Deleting an author may affect related articles
Deleting a category may orphan products

The LLM may not always warn you about potential impacts.

When AI Assistant Works Best

Great for:

Exploring and understanding your schema
Quick content operations (create, update, query)
Setting up new collections and fields
Triggering manual flows

Consider other approaches for:

Very large bulk operations (use direct API or import / export through the Data Studio)
Complex data migrations (use scripts or dedicated tools)
Sensitive operations on production data (test in staging first)

Next Steps

::card-group

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

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