The Sonore Phone Agent uses prompts to define the AI agent’s behavior, personality, and conversation flow. Prompts are tenant-specific and version-controlled.
Prompt Architecture
The system uses two types of prompts:
- Greeting - Initial message when answering a call
- Instruction - Detailed system prompt with conversation rules and knowledge base
Prompt Storage
Prompts can be stored in two locations:
File-Based Prompts (Default)
Location: data/prompts/
Configuration:
INSTRUCTIONS_FILE=baseline.md
GREETING_FILE=greeting.md
The prompt folder path is computed as: src/core/settings.py:77
prompt_folder: Path = Path(__file__).parent.parent.parent / "data" / "prompts"
Database Prompts (Multi-Tenant)
Prompts are stored in MongoDB collections for versioning and per-tenant customization:
prompts - Prompt text versions
tenant-prompt-state - Active prompt pointers per tenant
Prompt Models
PromptKind Enum
File: src/models/instructions/utils.py:4
from src.models.instructions.utils import PromptKind
class PromptKind(Enum):
GREETING = "greeting"
INSTRUCTION = "instruction"
PromptText Model
File: src/models/instructions/prompts.py:14
Stores a specific version of a prompt.
Tenant identifier this prompt belongs to
Type of prompt: "greeting" or "instruction"
The actual prompt content in Markdown format
Optional reference to parent prompt version for change tracking
Hash of the prompt text for deduplication and change detection
When this version was created
User or system that created this version
TenantPromptState Model
File: src/models/instructions/prompts.py:31
Tracks which prompt versions are active for a tenant.
Tenant ID (used as primary key)
Pointers to currently active prompts
Pointers to safety/fallback prompts
Pointers to previous prompt versions
User who made the last update
PromptPointer Model
File: src/models/instructions/prompts.py:9
ObjectId string pointing to a greeting prompt
ObjectId string pointing to an instruction prompt
ActiveInstructions Model
File: src/models/instructions/prompts.py:43
Full resolved prompts ready for use.
Full greeting prompt text
Full instruction prompt text
Reference to source greeting prompt
Reference to source instruction prompt
When these instructions were last updated
Baseline Prompt Structure
The baseline instruction prompt (data/prompts/baseline.md) demonstrates the recommended structure:
1. Role & Objective
Define who the agent is and what it does:
# Rôle & objectif
- Tu es l'agent téléphonique automatique d'AXEO Services.
- Tu réponds UNIQUEMENT en dehors des heures d'ouverture des agences.
- Tu échanges principalement avec des PARTICULIERS (clients ou prospects).
- Ton objectif :
- Comprendre la demande de l'appelant.
- Classer sa demande dans un type (renseignement général, renseignement spécifique, message à transmettre, demande d'action).
- Répondre en suivant les règles associées à ce type.
2. Language Settings
# Langue
- La conversation se déroule UNIQUEMENT en français.
- Tu réponds TOUJOURS en français, même si l'appelant utilise une autre langue.
3. Style, Tone & Rhythm
# Style, ton & rythme
- Français correct, précis, légèrement soutenu.
- Voix douce, bienveillante, posée.
- Rythme légèrement rapide :
- Phrases courtes et directes.
- 1 à 2 phrases par prise de parole, UNE seule question à la fois.
4. Context & Knowledge Base
# Contexte AXEO
- AXEO Services : réseau français de services à domicile pour particuliers.
- Services principaux :
- Ménage, repassage.
- Entretien de jardin et extérieurs.
- Petits bricolages.
- Aide à domicile et accompagnement des seniors.
# Base de connaissances AXEO
## 1. Informations générales commerciales
- Horaires d'ouverture des agences : ...
- Services proposés aux particuliers : ...
5. Intent Classification
# Classification des demandes (intents)
## 1. Intent RENSEIGNEMENT_GENERAL
Quand l'utiliser :
- L'appelant pose une question **générale**, qui ne dépend pas d'un dossier précis
Comportement :
- Tu DONNES une réponse claire et factuelle (5 phrases maximum).
# Tools — Transfert (refer)
## Destinations disponibles
- **commercial** — *Mme Gogny (demandes commerciales)*
- **planning** — *le service planning*
- **comptabilite** — *la comptabilité*
## Script de transfert
« Très bien. Je vous mets en relation avec {{label}}. Restez en ligne, s'il vous plaît. »
7. Conversation Flow
# Flux de conversation
## 1. Compréhension de la demande & réponse initiale
- Invite l'appelant à préciser sa demande
- Identifie le type de service
- Choisis l'INTENT le plus approprié
## 2. Décision de suivi et de rappel
- Décider s'il est nécessaire de prévoir un rappel
## 3. Collecte des coordonnées (conditionnelle)
- Ne demande les coordonnées qu'après avoir répondu
## 4. Reformulation de la demande & conclusion
- Valider le récapitulatif final
8. Edge Cases & Safety
# Cas particuliers & sécurité
- Urgence médicale ou danger immédiat :
« Pour toute urgence ou situation de danger immédiat, le plus rapide est de contacter les services d'urgence au 15 ou au 112. »
- Appelant très agressif ou insultant :
« Je comprends que la situation soit très désagréable. Je vais transmettre votre demande. »
Prompt Best Practices
Structure
- Use clear markdown headings (
#, ##, ###)
- Break content into logical sections
- Use bullet points for lists
- Include examples for complex instructions
Language
- Be explicit about the agent’s capabilities and limitations
- Define the tone, style, and conversation rhythm
- Specify when to use formal vs. informal language
Rules
- State what the agent MUST do and what it MUST NOT do
- Provide clear decision trees for different scenarios
- Include fallback behavior for edge cases
Knowledge Base
- Include domain-specific information
- Provide example responses
- Define terminology and acronyms
Conversation Flow
- Define clear steps in the conversation
- Specify when to collect information
- Include validation and confirmation steps
Example: Custom Greeting
# Greeting
Agence AXEO Services, bonjour. Comment puis-je vous aider aujourd'hui ?
For the baseline prompt, this is stored in data/prompts/greeting.md.
Example: Database Prompt Document
{
"_id": ObjectId("65a1b2c3d4e5f6a7b8c9d0e1"),
"tenant_id": "tenant-prod-001",
"kind": "instruction",
"prompt_text": "# Rôle & objectif\n\n- Tu es l'agent téléphonique...",
"parent_id": null,
"checksum": "sha256:abc123...",
"created_at": ISODate("2026-03-02T10:00:00Z"),
"created_by": "[email protected]"
}
Example: Tenant Prompt State
{
"_id": "tenant-prod-001",
"tenant_id": "tenant-prod-001",
"active": {
"greeting_id": "65a1b2c3d4e5f6a7b8c9d0e1",
"instruction_id": "65a1b2c3d4e5f6a7b8c9d0e2"
},
"safety": {
"greeting_id": "65a1b2c3d4e5f6a7b8c9d0e1",
"instruction_id": "65a1b2c3d4e5f6a7b8c9d0e2"
},
"previous": {
"greeting_id": "65a1b2c3d4e5f6a7b8c9d0e0",
"instruction_id": "65a1b2c3d4e5f6a7b8c9d0d9"
},
"updated_at": ISODate("2026-03-02T14:30:00Z"),
"updated_by": "[email protected]"
}
Updating Prompts
File-Based Update
- Edit the prompt file in
data/prompts/
- Restart the application to load changes
Database Update
- Create new prompt version:
const newPromptId = db.prompts.insertOne({
tenant_id: "tenant-prod-001",
kind: "instruction",
prompt_text: "# Updated instructions...",
parent_id: ObjectId("65a1b2c3d4e5f6a7b8c9d0e2"),
checksum: "sha256:def456...",
created_at: new Date(),
created_by: "[email protected]"
}).insertedId
- Update tenant prompt state:
db['tenant-prompt-state'].updateOne(
{ _id: "tenant-prod-001" },
{
$set: {
"previous.instruction_id": "65a1b2c3d4e5f6a7b8c9d0e2",
"active.instruction_id": newPromptId.toString(),
updated_at: new Date(),
updated_by: "[email protected]"
}
}
)
Testing Prompts
After updating prompts:
- Make a test call to verify behavior
- Test different conversation flows (intents)
- Verify edge cases and safety rules
- Check tool usage (transfer, refer)
- Validate tone and style
Always test prompts thoroughly before deploying to production. Poorly configured prompts can lead to incorrect agent behavior.
Prompt Versioning Strategy
Safety Prompts
Keep a “safety” version that is known to work well. This can be rolled back to if a new prompt causes issues.
Parent Tracking
Use the parent_id field to track prompt evolution:
v1 (parent: null)
└─ v2 (parent: v1)
└─ v3 (parent: v2)
└─ v4 (parent: v3)
Checksums
Use checksums to detect duplicate prompts and avoid creating unnecessary versions.
Advanced: Prompt Variables
Some prompts may use template variables:
# Greeting
Agence {{tenant_display_name}}, bonjour. Comment puis-je vous aider ?
These are resolved at runtime using tenant configuration.
The baseline prompt in data/prompts/baseline.md is 572 lines and includes comprehensive instructions for the AXEO Services use case. Use it as a reference when creating prompts for new tenants.