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

Namespaces и персоны

Namespace задаёт личность и поведение AI-ассистента внутри отдела. У каждого namespace может быть свой 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 — формальный юридический стиль.

Устаревшее поле persona.tone API больше не принимает.

System prompt

Поле systemPrompt подставляется первым сообщением в контекст LLM. Через него задаются роль ассистента, ограничения и границы знаний.

API

Список namespaces

GET /api/v1/namespaces

Создать namespace

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

Обновить namespace

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

Удалить namespace

DELETE /api/v1/namespaces/:id

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

Поле agentRunner в Namespace.config определяет, какой адаптер обрабатывает задачи для этого namespace.

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	Какой адаптер использовать для этого namespace
adapters.<type>	объект	Настройки конкретного адаптера (модель, таймаут, ключи и т.д.)

Смена адаптера для namespace делается одним обновлением конфига — менять код не нужно.

Связь с другими фичами

• Agent runner — каждый namespace выбирает свой адаптер через config.agentRunner.activeAdapter.
• Intent trust — у каждого namespace своя матрица доверия (записи IntentTrust, привязанные к namespaceId).
• Intent examples — обучающие примеры ограничены namespace-ом.
• Разговоры — каждый разговор может принадлежать namespace.
• RAG — system prompt namespace подставляется в RAG-контекст.

---

Маршруты моделей

AgentCore использует OpenAI-совместимые API для генерации и 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
OPENAI_API_KEY	да	—	OpenAI API-ключ
JWT_SECRET	да	—	Секрет подписи JWT, минимум 32 символа
NODE_ENV	нет	development	Режим работы: development, production или test
PORT	нет	3000	Порт сервера
HOST	нет	0.0.0.0	Bind address
REDIS_URL	нет	redis://localhost:6379	Строка подключения Redis
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	нет	—	Langfuse tracing public key
LANGFUSE_SECRET_KEY	нет	—	Langfuse tracing secret key
LANGFUSE_HOST	нет	—	URL сервера Langfuse
JWT_EXPIRES_IN	нет	7d	Срок жизни JWT-токена
PII_ENCRYPTION_KEY	да	—	32-байтовый AES-GCM ключ в Base64
WHATSAPP_APP_ID	нет	—	ID приложения WhatsApp Cloud API
WHATSAPP_APP_SECRET	нет	—	Secret приложения WhatsApp Cloud API
WHATSAPP_PHONE_NUMBER_ID	нет	—	Phone number ID WhatsApp
WHATSAPP_ACCESS_TOKEN	нет	—	Access-токен WhatsApp API
WHATSAPP_WEBHOOK_VERIFY_TOKEN	нет	—	Verify-токен webhook
WA_PHONE_NUMBER	нет	+380000000000	Номер отправителя WhatsApp
WA_RATE_LIMIT_PER_MIN	нет	60	Лимит WhatsApp-сообщений в минуту
TG_BOT_TOKEN	нет	—	Токен Telegram-бота
TG_RATE_LIMIT_PER_MIN	нет	30	Лимит Telegram-сообщений в минуту
ALLOWED_ORIGINS	нет	http://localhost:5173	Разрешённые CORS origins (точный match)
MEMORY_EXTRACT_EVERY_N_MESSAGES	нет	10	Каждые N сообщений — запуск memory extraction
MEMORY_EXTRACTION_MODEL	нет	gpt-4o-mini	Модель для memory extraction
INTENT_TRIGGER_WORDS	нет	см. config.ts	Триггерные слова HITL через запятую

Memory extraction

Переменная	По умолчанию	Описание
MEMORY_EXTRACTION_MODEL	gpt-4o-mini	Модель для извлечения профиля сотрудника

По умолчанию стоит более дешёвая модель ради экономии. Извлечение профиля менее чувствительно к качеству, чем RAG-генерация.

Anthropic (опционально)

Переменная	По умолчанию	Описание
ANTHROPIC_API_KEY	—	Ключ Anthropic API

Зарезервировано для будущей маршрутизации между несколькими провайдерами. Сейчас в основном generation-пайплайне не используется.

---

RAG-веса

Веса поиска настраиваются per-knowledge base — можно тюнить качество поиска под разный тип контента.

Дефолтные веса

Поле	По умолчанию	Описание
vector	0.65	Доля итогового скора от векторного (embedding) поиска
keyword	0.35	Доля итогового скора от полнотекстового keyword-поиска

Внутри векторного бюджета 85% идёт на content embeddings и 15% — на синтетические embeddings вопросов. Эти доли зашиты и не настраиваются. Сумма vector + keyword должна быть ≤ 1.0.

Настройка per-KB

Кастомные веса задаются через отдельный config-эндпоинт базы знаний:

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

Передайте "ragWeights": null, чтобы сбросить веса KB и вернуться к глобальным дефолтам.

Рекомендации по тюнингу

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

Как считается скор

1. Каждый путь поиска возвращает кандидатов с сырыми скорами.
2. Скоры нормализуются в каждом пути (диапазон 0–1).
3. Итоговый скор: (vector × 0.85) × vecScore + (vector × 0.15) × qScore + keyword × keyScore.
4. Топ-6 кандидатов отбираются по итоговому скору.