82 lines
3.7 KiB
Markdown
82 lines
3.7 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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
|
|
|
|
```bash
|
|
./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.
|