Конфігурація

Простори імен і персони

Простір імен визначає персону та поведінку AI-асистента в межах відділу. Кожен простір імен може мати власний system prompt, шкалу формальності, правила ескалації та матрицю довіри.

Конфігурація персони

JSON-поле persona підтримує:

{
  "language": "uk",
  "style": {
    "verbosity": "concise",
    "citations": true,
    "structure": "bullets",
    "formality": 80
  },
  "boundaries": ["Do not provide legal advice", "Redirect medical questions to HR"],
  "escalation": {
    "triggers": ["lawsuit", "termination", "complaint"],
    "defaultAssignee": "<user-id>",
    "message": "This question has been escalated to a specialist."
  },
  "greeting": "Hello! How can I help you today?",
  "fallback": "I'm not sure about that. Let me connect you with a specialist."
}

Шкала формальності

persona.style.formality — ціле число від 0 до 100.

0-33 — неформальні відповіді простою мовою
34-66 — збалансований професійний тон
67-100 — формальна юридична мова

Legacy-поле persona.tone API більше не приймає.

System prompt

Поле systemPrompt вставляється як перше повідомлення в контекст LLM. Використовуйте його, щоб задати роль асистента, обмеження та межі знань.

API

Список просторів імен

GET /api/v1/namespaces

Створення простору імен

POST /api/v1/namespaces
Body: { "name": "legal", "departmentId": "<id>", "systemPrompt": "...", "persona": {...} }

Оновлення простору імен

PATCH /api/v1/namespaces/:id
Body: { "systemPrompt": "...", "persona": {...} }

Видалення простору імен

DELETE /api/v1/namespaces/:id

Конфігурація agent runner

Поле agentRunner у Namespace.config контролює, який адаптер обробляє завдання для цього простору імен.

PATCH /api/v1/namespaces/:id
{
  "config": {
    "agentRunner": {
      "activeAdapter": "api",
      "adapters": {
        "api": { "model": "gpt-4o-mini", "apiKey": "$OPENAI_API_KEY" },
        "claude_local": { "model": "claude-sonnet-4-6", "maxTokens": 4096, "timeoutMs": 300000 },
        "codex_local": { "model": "codex-mini-latest", "timeoutMs": 300000 },
        "ollama": { "baseUrl": "http://localhost:11434", "model": "llama3.1-70b", "temperature": 0.7 }
      }
    }
  }
}

Поле	Тип	Опис
`activeAdapter`	`api` \| `claude_local` \| `codex_local` \| `ollama`	Який адаптер використовує цей простір імен
`adapters.<type>`	object	Параметри кожного адаптера (модель, timeout, ключі тощо)

Перемикайте адаптер простору імен одним оновленням конфігурації — правки коду не потрібні.

Звʼязок з іншими фічами

Agent runner: кожен простір імен вибирає свій адаптер через config.agentRunner.activeAdapter.
Intent trust: у кожного простору імен власна матриця довіри (записи IntentTrust scope-обмежені по namespaceId).
Intent examples: приклади для навчання класифікатора scope-обмежені простором імен.
Розмови: розмова може опційно належати простору імен.
RAG: system prompt простору імен вкладається в RAG-контекст.

Model routing

AgentCore використовує OpenAI-сумісні API для LLM-генерації та embeddings. Маршрутизація налаштовується через env-змінні.

LLM generation

Змінна	За замовчуванням	Опис
`OPENAI_API_KEY`	—	API-ключ (обовʼязково)
`OPENAI_BASE_URL`	`https://api.openai.com/v1`	Base URL для generation API
`OPENAI_MODEL`	`gpt-4o`	Модель для RAG-генерації

Альтернативні провайдери

Будь-який OpenAI-сумісний API підключається через зміну OPENAI_BASE_URL:

# Azure OpenAI
OPENAI_BASE_URL=https://your-resource.openai.azure.com/openai/deployments/gpt-4o
OPENAI_API_KEY=your-azure-key

# Local model (Ollama, vLLM, etc.)
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_API_KEY=not-needed
OPENAI_MODEL=llama3

Embeddings

Змінна	За замовчуванням	Опис
`OPENAI_EMBEDDING_MODEL`	`text-embedding-3-small`	Embedding-модель (1536-dim)

Embedding-модель має генерувати 1536-вимірні вектори, щоб відповідати визначенню pgvector-колонки. Якщо міняєте модель — перевірте сумісність розмірності.

Змінні оточення

Змінна	Обовʼязкова	За замовчуванням	Опис
`DATABASE_URL`	так	—	PostgreSQL connection string
`OPENAI_API_KEY`	так	—	OpenAI API-ключ
`JWT_SECRET`	так	—	Секрет підпису JWT, мін. 32 символи
`NODE_ENV`	ні	`development`	Runtime-режим: `development`, `production` або `test`
`PORT`	ні	`3000`	Порт сервера
`HOST`	ні	`0.0.0.0`	Bind-адреса
`REDIS_URL`	ні	`redis://localhost:6379`	Redis connection string
`KB_UPLOAD_DIR`	ні	`./tmp/knowledge_uploads`	Директорія аплоадів документів
`OPENAI_BASE_URL`	ні	`https://api.openai.com/v1`	Base URL LLM API
`OPENAI_MODEL`	ні	`gpt-4o`	LLM-модель для генерації
`OPENAI_EMBEDDING_MODEL`	ні	`text-embedding-3-small`	Embedding-модель
`ANTHROPIC_API_KEY`	ні	—	Anthropic API-ключ, зарезервовано під майбутню маршрутизацію
`LANGFUSE_PUBLIC_KEY`	ні	—	Public-ключ Langfuse-трейсингу
`LANGFUSE_SECRET_KEY`	ні	—	Secret-ключ Langfuse-трейсингу
`LANGFUSE_HOST`	ні	—	URL сервера Langfuse
`JWT_EXPIRES_IN`	ні	`7d`	TTL JWT-токена
`PII_ENCRYPTION_KEY`	так	—	32-байтовий AES-GCM ключ у Base64
`WHATSAPP_APP_ID`	ні	—	WhatsApp Cloud API app ID
`WHATSAPP_APP_SECRET`	ні	—	WhatsApp Cloud API app secret
`WHATSAPP_PHONE_NUMBER_ID`	ні	—	WhatsApp phone number ID
`WHATSAPP_ACCESS_TOKEN`	ні	—	WhatsApp API access token
`WHATSAPP_WEBHOOK_VERIFY_TOKEN`	ні	—	Webhook verify token
`WA_PHONE_NUMBER`	ні	`+380000000000`	Номер відправника WhatsApp
`WA_RATE_LIMIT_PER_MIN`	ні	`60`	Повідомлень WhatsApp на хвилину
`TG_BOT_TOKEN`	ні	—	Telegram bot token
`TG_RATE_LIMIT_PER_MIN`	ні	`30`	Повідомлень Telegram на хвилину
`ALLOWED_ORIGINS`	ні	`http://localhost:5173`	Точні дозволені CORS origin
`MEMORY_EXTRACT_EVERY_N_MESSAGES`	ні	`10`	Повідомлень між екстракціями памʼяті
`MEMORY_EXTRACTION_MODEL`	ні	`gpt-4o-mini`	Модель для екстракції памʼяті
`INTENT_TRIGGER_WORDS`	ні	див. `config.ts`	Тригер-слова HITL через кому

Memory extraction

Змінна	За замовчуванням	Опис
`MEMORY_EXTRACTION_MODEL`	`gpt-4o-mini`	Модель для екстракції employee profile

За замовчуванням — менша модель з економічних міркувань. Екстракція профілів менш чутлива до якості, ніж RAG-генерація.

Anthropic (опційно)

Змінна	За замовчуванням	Опис
`ANTHROPIC_API_KEY`	—	Anthropic API-ключ

Зарезервовано під майбутню мультипровайдерну маршрутизацію. Наразі не використовується в основному pipeline.

RAG weights

Ваги retrieval налаштовуються для кожної бази знань окремо, щоб оптимізувати якість пошуку для різних типів контенту.

Дефолтні ваги

Поле	За замовчуванням	Опис
`vector`	0.65	Частка фінального score від векторного (embedding) пошуку
`keyword`	0.35	Частка фінального score від keyword full-text пошуку

У межах вектор-бюджету 85% іде на content chunk embeddings, 15% — на synthetic Q&A embeddings. Ці частки жорстко зашиті й не конфігуруються. vector + keyword має бути ≤ 1.0.

Конфігурація на рівні бази знань

Задайте кастомні ваги через конфігураційний ендпоінт бази знань:

PATCH /api/v1/knowledge/bases/:id/config
{
  "ragWeights": {
    "vector": 0.70,
    "keyword": 0.30
  }
}

Передайте "ragWeights": null, щоб зняти ваги на рівні бази знань і повернутись до глобальних дефолтів.

Поради з налаштування

Тип контенту	Рекомендація
Юридичні документи (структуровані)	Вища keyword-вага (наприклад, `keyword: 0.45`) — юридичні терміни мають збігатись точно
FAQ / Q&A-пари	Вища vector-вага (наприклад, `vector: 0.80`) — важливіший семантичний матч
Звичайний текст	Дефолт працює добре
Технічна документація	Збалансовано — і терміни важливі, і контекст

Як працює scoring

Кожен шлях пошуку віддає кандидатів із сирими scores
Scores нормалізуються по кожному шляху (діапазон 0-1)
Фінальний score: (vector × 0.85) × vecScore + (vector × 0.15) × qScore + keyword × keyScore
Вибирається top-6 кандидатів за фінальним score

Конфігурація

Простори імен і персони​

Конфігурація персони​

Шкала формальності​

System prompt​

API​

Список просторів імен​

Створення простору імен​

Оновлення простору імен​

Видалення простору імен​

Конфігурація agent runner​

Звʼязок з іншими фічами​

Model routing​

LLM generation​

Альтернативні провайдери​

Embeddings​

Змінні оточення​

Memory extraction​

Anthropic (опційно)​

RAG weights​

Дефолтні ваги​

Конфігурація на рівні бази знань​

Поради з налаштування​

Як працює scoring​