Skip to content

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:

from chakra_convai import PromptLoader

cfg = PromptLoader.load("weather")


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_tool descriptions attached to tool declarations.
  • Inspect assembled prompts: Run chakra-convai prompt <language> to review the exact prompt the model sees at runtime.