Agent Prompt and Tools

TZ-10 adds the final AI-operator behavior layer on top of the existing dialogue state machine, language selection, region resolver, Knowledge Base, and VoiceProvider abstraction.

Behavior

The operator must:

introduce itself as Жанна, the AI operator of QazAimaqGas;
avoid IVR-style "choose language" and "choose region" prompts;
infer Russian or Kazakh from the caller's speech;
ask for region only when a regional answer is needed;
answer general questions through global KB without selected region;
call only tools allowed by the current dialogue state;
answer business questions only after search_knowledge_base;
use only KB tool results as answer evidence;
return a controlled no-answer message when KB has no relevant result;
format the caller-facing answer in the selected language;
support kk answers from ru KB sources through cross-language fallback without inventing facts.

Final Prompt

internal/agent.BuildSystemPrompt builds the state-aware system prompt. It includes Жанна/QazAimaqGas identity, current state, language, region, allowed next actions, forbidden actions, no-hallucination rules, and internal-detail restrictions.

The live flow starts ready to listen after the natural greeting. LANGUAGE_SELECTION and REGION_SELECTION remain for compatibility, but they are no longer blocking IVR steps. In READY_TO_HELP and QUESTION_ANSWERING, the assistant must call search_knowledge_base before answering business questions.

If region is missing:

general questions search global KB;
branch, address, contact, city, oblast, or region questions return region_required_for_question;
"Алматы" remains ambiguous and must be clarified as city vs oblast.

Tool Flow

VoiceProvider event
  -> Call Manager voice event pump
  -> Dialogue Orchestrator
  -> Tool Policy
  -> KB Service when allowed
  -> ToolResult
  -> VoiceProvider.SendToolResult

Tool denials are returned as structured tool results and are safe to send back to the provider.

Knowledge Answers

search_knowledge_base returns answer_text, answer_language, KB results, citations, cross_language_fallback_used, message_key, and reason_code.

The answer text is built from returned KB content only. It does not expose chunk IDs, SQL, embeddings, vector search, credentials, or prompt internals.

Cross-Language Fallback

If the caller selected kk and no kk KB result exists, the KB service can search ru content. TZ-10 formats the response with Kazakh framing while keeping factual content grounded in the returned source.

CLI

./bin/ai-operator agent-self-test --env /etc/ai-operator/ai-operator.env
./bin/ai-operator natural-dialogue-self-test --env /etc/ai-operator/ai-operator.env
./bin/ai-operator openai-tool-smoke-test --env /etc/ai-operator/ai-operator.env

agent-self-test and natural-dialogue-self-test use PostgreSQL, fake embeddings, and FakeVoiceProvider. They do not call OpenAI. openai-tool-smoke-test fails before network when OPENAI_API_KEY is empty.

Not Implemented Yet

real business tools;
human transfer;
final production route switch;
production Kazakhtelecom call testing;
curated Kazakh KB content parity.

TZ-11 Handoff Prompt Rules

If the caller asks for a human, operator, consultant, specialist, or live agent, the assistant must call request_human_handoff. It must not promise a real transfer unless the tool result confirms successful transfer. If the tool result is stubbed or not configured, the assistant must explain that politely.

Audit Integration

Tool calls and tool results are persisted through ai_tool_audit after recursive redaction. KB search audit records result counts and citations, not raw credentials or audio.

3.7 KiB Raw Blame History