# 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.