Prompts & instructions.json
Everything the model is told comes from config/instructions.json. The engine assembles the system prompt from it on every call, so changing agent behavior means editing this file, not Python code.
Structure of config/instructions.json
| Key | Required | What it holds |
|---|---|---|
agent_profile |
Yes | name, description, supported_languages, and persona with its voice_guidelines list |
system_directives.core_rules |
Yes | The list of rules the agent always follows |
conversation_states_and_flows |
Yes | The stages of a call: opening, working out what the caller wants, handling it, closing |
guardrails_and_fallbacks |
Yes | What to do when a tool fails, a question is out of scope, or language is unsupported |
system_guardrails |
No | identity_anchor, immutable_rules, boundary_enforcement, anti_extraction, tool_safety |
tools.<name>.description |
For built-ins | Descriptions of built-in tools. end_call must have one |
languages.<lang>.prompts |
Yes | Per-language lines: assistant, greeting, returning_greeting, silence_reprompt, silence_disconnect |
greeting.returning_caller_template |
If used | How a returning caller is greeted |
language_policy |
Gemini Live | The per-reply language reminder (forced_enforcer_default, forced_enforcer_suffix) |
agent_profile.terminology_glossary |
No | Domain terms and phonetic spellings the agent should use |
Minimal Example
{
"agent_profile": {
"name": "My Helpline",
"description": "A phone assistant for agriculture",
"supported_languages": ["sinhala", "english"],
"persona": {
"role": "A friendly, patient advisor",
"voice_guidelines": [
"Keep answers short: this is a phone call.",
"Ask one question at a time."
]
}
},
"system_directives": {
"core_rules": [
"Never invent facts. Use a tool or say you do not know."
]
},
"conversation_states_and_flows": {
"1_initiation": "Greet the caller and ask how you can help.",
"2_intent_execution": "Use the right tool, then answer briefly.",
"3_closing": "Ask for a 1 to 5 rating, save a summary, then end the call."
},
"guardrails_and_fallbacks": {
"api_failure_fallback": "Apologise briefly and say there is a system issue.",
"out_of_scope_queries": "Politely say you can only help with agriculture."
},
"tools": {
"end_call": {
"description": "End the call after the caller says goodbye."
}
},
"languages": {
"english": {
"prompts": {
"assistant": "Speak plain, warm English.",
"greeting": "Greet the caller and introduce the service.",
"silence_reprompt": "Ask if the caller is still there.",
"silence_disconnect": "Say goodbye and that you are ending the call."
}
}
}
}
Per-Skill Prompt Files
Each skill can maintain its own prompt advice and flows in config/modules/<skill>/prompts.json, loaded cleanly using PromptLoader:
{
"instructions": {
"get_current_weather": {
"when_to_use": "When the caller asks about the weather or rainfall."
}
},
"flows": {
"WEATHER_INQUIRY": {
"agent_instruction": "Handle weather and farming condition queries."
}
}
}
Load it inside your skill:
Best Practices
- State each rule once: The entire prompt is sent with every turn. Repetition increases token latency and costs without improving adherence.
- Write Sinhala and Tamil in native script: Write lines in the spoken style you want. A model told in English to "speak Sinhala" tends to sound stiff, overly formal, and literary.
- Do not repeat tool descriptions in the prompt: The model automatically receives
@function_tooldescriptions attached to tool declarations. - Inspect assembled prompts: Run
chakra-convai prompt <language>to review the exact prompt the model sees at runtime.