Skip to main content
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:
  1. Greeting - Initial message when answering a call
  2. 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.
_id
ObjectId
MongoDB document ID
tenant_id
string
required
Tenant identifier this prompt belongs to
kind
PromptKind
required
Type of prompt: "greeting" or "instruction"
prompt_text
string
required
The actual prompt content in Markdown format
parent_id
ObjectId | null
Optional reference to parent prompt version for change tracking
checksum
string | null
Hash of the prompt text for deduplication and change detection
created_at
datetime
required
When this version was created
created_by
string | null
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.
_id
string
required
Tenant ID (used as primary key)
tenant_id
string
required
Tenant identifier
active
PromptPointer
required
Pointers to currently active prompts
safety
PromptPointer
required
Pointers to safety/fallback prompts
previous
PromptPointer
required
Pointers to previous prompt versions
updated_at
datetime
required
Last update timestamp
updated_by
string | null
User who made the last update

PromptPointer Model

File: src/models/instructions/prompts.py:9
greeting_id
string | null
ObjectId string pointing to a greeting prompt
instruction_id
string | null
ObjectId string pointing to an instruction prompt

ActiveInstructions Model

File: src/models/instructions/prompts.py:43 Full resolved prompts ready for use.
tenant_id
string
required
Tenant identifier
greeting_text
string
required
Full greeting prompt text
instruction_text
string
required
Full instruction prompt text
greeting_id
string | null
Reference to source greeting prompt
instruction_id
string | null
Reference to source instruction prompt
updated_at
datetime | null
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).

6. Tool Configuration

# 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

  1. Edit the prompt file in data/prompts/
  2. Restart the application to load changes

Database Update

  1. 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
  1. 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:
  1. Make a test call to verify behavior
  2. Test different conversation flows (intents)
  3. Verify edge cases and safety rules
  4. Check tool usage (transfer, refer)
  5. 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.

Build docs developers (and LLMs) love