Best practices and troubleshooting
Improve prompt quality, choose the right model, and fix the most common issues users face with Odoo AI.
AI works best when each agent has a clear scope, a concise prompt, and compact, updated supporting documents. The AI module provides Ask AI, agent chat, AI email composition, voice transcription, and semantic search (RAG).
When issues happen, check API configuration, source status, connectivity, and user permissions in that order. Most errors relate to incorrect API keys, unsupported files, or insufficient permissions. If you need to compare against the intended setup, revisit Odoo AI configuration, AI Agents and knowledge sources, and AI Knowledge.
Writing effective System Prompts
The system prompt is the most important instruction for defining the agent role and behaviour. A good prompt helps the agent respond accurately, consistently, and appropriately for the business context.
Key points
• Clear: State the agent role explicitly (e.g., "You are a professional sales assistant").
• Specific: Provide examples of desired responses so the agent understands expectations.
• Concise: Keep it short, focus on key points, avoid redundant information.
• Good example: "You are a sales assistant. Help customers find products. Always be polite and professional. If you don't know, say so clearly."
• Example for Customer Support: "You are a customer service specialist. Respond politely, empathetically, and provide specific solutions."
Choosing the right LLM model
Each LLM model has different strengths in speed, quality, and cost. Choose the model that fits your business needs to optimize performance and cost.
LLM model comparison
| Model | Speed | Quality | Best for | Notes |
|---|---|---|---|---|
| GPT-4.1 Mini | Fast | Good | Simple questions, quick searches | Low cost, suitable for high volume |
| GPT-4o | Medium | Very good | Most business cases | Good balance between quality and speed |
| GPT-4.1 | Slow | Excellent | Complex analysis, critical decisions | High cost, use when maximum quality needed |
| Gemini 2.5 Flash | Very fast | Good | Quick searches, instant responses | High speed, suitable for real-time chat |
| Gemini 2.5 Pro | Medium | Very good | Data analysis, reporting | Handles large data and multimedia well |
When to use RAG (Retrieval-Augmented Generation)
RAG allows agents to reference internal documents when responding. RAG is not always needed, only use it when you have specific documents to reference.
Key points
• Use RAG when: You have internal documents (guides, policies, procedures), need to cite sources, information changes frequently.
• Don't use RAG when: Only need Odoo data (orders, customers, products), general questions don't need specific documents.
• Optimize RAG documents: Split long documents into parts (1-2 pages each), use clear headings, update regularly.
• Best formats: PDF (max 5 pages), Markdown (easy to process), TXT (simplest).
• Avoid: Very large files (>10MB), complex formats, outdated documents.
Designing effective Agents
Key points
• Set a clear business Name (e.g., "Sales Coach", "Support Assistant", "HR Helper") so users can easily identify it.
• Write a short Subtitle (1 sentence) so users quickly understand the purpose without opening details.
• Assign the right Topic expertise, avoid one agent doing everything. Each agent should have a clear scope (e.g., only sales, only customer service).
• Use Default Prompts to standardize tone and create Buttons for frequently used commands (e.g., "Write thank you email").
• Test with the Test button before wide deployment to ensure response quality.
• Monitor Sources status regularly, handle Failed immediately so the agent always has complete knowledge sources.
Smart source management
Key points
• Only add quality, updated documents directly relevant to the agent role.
• Monitor source status: Processing (processing), Indexed (ready), Failed (error).
• If a source fails, use Retry before deleting. Check if the file format or URL is valid.
• Use Reprocess to re-index successful URL sources (e.g., when web content changes).
• Split long documents into smaller parts with clear headings so the agent can search and cite easily.
• Do not add sensitive documents (passwords, personal information, financial data) to knowledge sources.
Standardizing prompts with Default Prompts
Default Prompts help standardize how agents are called based on context. For example, when composing an email to a customer, automatically call the appropriate agent with a default prompt.
Key points
• Use Default Prompts to standardize tone (polite, professional, concise).
• Create Buttons for frequently used commands to save time (e.g., "Write follow-up email", "Write apology email").
• Separate rules by model to avoid overly generic prompts (e.g., separate rules for res.partner, sale.order).
• Only system administrators can configure Default Prompts.
Security when using AI
Key points
• API keys are entered as passwords (hidden characters), only system administrators can view/edit them.
• Do not share API keys via internal chat/email, Slack, or unencrypted tools.
• Review keys periodically (3-6 months) and rotate when needed for security.
• Only add public documents to RAG, do not add sensitive information (passwords, ID numbers, financial data).
• Check access permissions: Ask AI only accesses data the current user is allowed to view.
• Data may be sent to OpenAI or Google for processing, so review the provider privacy policy.
• Administrators can disable AI in Settings when not in use or for maintenance.
Common issues and fixes
API and configuration errors
| Issue | Common cause | Suggested fix | Notes |
|---|---|---|---|
| Invalid API key | Wrong key, expired, or not entered | Generate new key from OpenAI/Google, update in Settings → AI → Providers, save and retry | Check key matches provider (OpenAI vs Google) |
| Cannot call OpenAI/Gemini | Wrong API key, provider not enabled, or quota exceeded | Go to Settings → Providers, check key and enable correct provider, check remaining quota | Contact provider if quota exceeded |
| AI menu not visible | Module ai_app not installed or no permissions | Check module installed, check user permissions (must be internal user), reload interface | Contact admin if still not visible |
| Settings/Default Prompts not visible | Not a system administrator | Log in with account having base.group_system permission | Only admins see this menu |
Knowledge source (RAG) errors
| Issue | Common cause | Suggested fix | Notes |
|---|---|---|---|
| Source indexing failed | Unsupported file, too large (>10MB), or corrupted | Check format (PDF, PNG, Excel, TXT), try different file, click Retry, view error details | Split large files into smaller parts |
| Source Processing too long | Large file or system processing many sources | Wait a few minutes, check status again, if over 10 minutes then Retry | PDF files >5 pages may take longer |
| Agent not using knowledge sources | Source not Indexed or Restrict to Sources not enabled | Check source status (must be Indexed), enable Restrict to Sources if mandatory | Agent may use general knowledge if Restrict not enabled |
| URL source error | URL not accessible, requires login, or blocked | Check URL opens in browser, try different URL, use Binary instead of URL | Only supports public URLs |
Feature usage errors
| Issue | Common cause | Suggested fix | Notes |
|---|---|---|---|
| Ask AI not working | Missing API key, connection error, or no permissions | Check API key configured, check internet connection, retry after a few minutes, contact admin | May be due to quota exceeded or service down |
| AI email not showing | AI Composer not configured or no Default Prompts | Check AI Composer settings, create Default Prompts for mail composer, contact admin | Need to configure Default Prompts first |
| Agent poor response quality | Unclear prompt, wrong topic, source not processed or failed | Improve system prompt (clear, concise), reassign appropriate topic, check Sources tab and handle Failed, use Test button to experiment | Try changing LLM model if still poor |
| AI chat not responding | Connection error, wrong API key, or agent not configured correctly | Check connection, check API key, check agent has System Prompt and LLM Model | View logs for error details |
| Voice transcription error | Unsupported audio file or too large | Use MP3, WAV, M4A format, reduce file size if too large | Maximum 25MB for audio files |
Using Ask AI effectively
Ask AI allows you to ask questions in natural language to find Odoo data. AI understands your intent, finds relevant data, and opens views (list, chart, pivot).
Key points
• Be specific: "Show unpaid invoices" instead of "Invoices".
• Be clear: "List customers from Hanoi" instead of "Customers".
• Add context: "Total sales this month" instead of "Sales".
• Good question examples: "Open orders for company ABC", "Best-selling products in March", "Overdue invoices".
• AI can open lists, charts, pivots, or apply filters automatically.
Tips for AI email composition
Key points
• Be specific: "Write apology email for late delivery" instead of "Write email".
• Be clear: "Write follow-up email for order #12345" instead of "Follow up order".
• Be professional: "Write formal email for new customer" to get appropriate tone.
• Edit options: Use "Rewrite more professionally", "Make it shorter", "Add details", "Fix spelling".
• Always review content before sending to ensure accuracy.
AI operations management
Key points
• Clear permissions: users use Agents, admins manage Settings/Prompts, only system admins see Configuration.
• Test with Test button before wide deployment to ensure agent works well.
• Review keys periodically (3-6 months) and rotate when needed for security.
• Monitor API usage and quota to avoid running out mid-operation.
• Create separate agents for each department (Sales, Support, HR) instead of sharing one agent.
• Update RAG documents regularly so the agent always has the latest information.
Frequently Asked Questions (FAQ)
Key points
• Q: What data can Ask AI access? A: Ask AI can access all data the current user has permission to view (according to Odoo permissions).
• Q: Is data sent to OpenAI/Google? A: Yes, for processing. Review their privacy policy and do not send sensitive information.
• Q: Can AI be disabled? A: Yes, administrators can disable it in Settings or not configure API keys.
• Q: Are there usage limits? A: Depends on your API plan (quota from OpenAI/Google).
• Q: Can agents perform actions? A: Yes, if configured with Tools (e.g., create orders, send emails).
• Q: Does RAG support Vietnamese? A: Yes, fully supports Vietnamese and many other languages.
• Q: How to know which source the agent is using? A: The agent will cite sources in responses if Restrict to Sources is enabled.
• Q: Can I use multiple API keys? A: No, only configure 1 key for OpenAI and 1 key for Google.
Reference documentation
Key points
• AI Module: ~/odoo/addons/ai/ (core AI, embeddings, LLM service)
• AI App Module: ~/odoo/addons/ai_app/ (management interface for agents, topics, default prompts)
• Vietnamese translations: ~/odoo/addons/ai/i18n/vi.po and ~/odoo/addons/ai_app/i18n/vi.po
• Agent guides (technical): ~/agent_guide/ai.md and ~/agent_guide/ai_app.md
• Related modules: attachment_indexation (file indexing), mail (AI email), discuss (chat)