pacod-ap

Зачем он нужен

pacod-ap создан для агентов, чья задача — давать верные ответы со ссылками на источники в одной предметной области, где неверная цена, ставка или срок хуже, чем отсутствие ответа. Его определяют три правила:

• Каждое число берётся из структурированного источника истины, а не из памяти модели.
• Каждое утверждение ссылается на источник — фрагмент базы знаний, source_url факта или веб-страницу из списка разрешённых.
• Администраторы исправляют агента без повторного развёртывания — модели, промпты, директивы, веб-поиск и кэширование применяются со следующего хода.

Одно развёртывание, много агентов

Агент — это профиль: одна строка в таблице profiles плюс всё, что к нему относится. В поставку входят два:

• starter — универсальный шаблон: небольшая вымышленная служба поддержки («Nimbus Notes»), которая задействует базу знаний и инструменты справочных фактов. Скопируйте его, чтобы начать своего агента.
• taxes — продвинутый пример для болгарского налогообложения и бухгалтерского учёта, со своими промптами, фактами, корпусом законов и списком разрешённых источников для веб-поиска (make seed-example PROFILE=taxes). Его корпус показывает поиск по реальному массиву законодательства; он не поддерживается в актуальном состоянии, и ничто из сказанного агентом не является юридической или налоговой консультацией.

Изоляция между агентами — граница безопасности: каждая строка агента несёт profile_id, а у каждого агента свои коллекции в Qdrant.

Пользователи видят только назначенных им агентов; администраторы работают глобально или в рамках одного агента. Квоты считаются на пользователя по всем агентам вместе. Агенты говорят на болгарском и английском; третий язык — это изменение кода, а не конфигурации.

Компоненты

У каждого контейнера одно имя в общей сети Docker pacod-net: ap-* для собственных сервисов pacod-ap и pacod-* для компонентов, общих с другими проектами pacod. Собственный чат приложения — единственный интерфейс чата.

Как проходит ход чата

Проверки выполняются до того, как что-либо начнёт передаваться потоком, поэтому отказ — это нормальный HTTP-статус, а не ошибка посреди потока:

1. Аутентификация — проверяется токен pacod-id; завершённая сессия или отключённый аккаунт отклоняются.
2. Агент — запрошенный агент должен быть назначен пользователю; если агент не указан, пользователь получает своего единственного агента, а не догадку.
3. Язык — определяется на каждом ходе и сверяется с языками агента.
4. Квота — лимит токенов на пользователя в шлюзе, плюс квота запросов и ограничение частоты в Redis.
5. Тема — фильтр незаконных формулировок, затем недорогой классификатор: вопрос не по теме отклоняется, на неясный приходят уточняющие вопросы.

Затем открывается поток server-sent events. На первый вопрос может ответить семантический кэш ответов агента; иначе выполняется небольшой граф LangGraph:

• plan — планировщик возвращает JSON: какие инструменты вызвать и сложный ли вопрос.
• execute tools — все запланированные вызовы выполняются параллельно: kb_search, get_fact / list_facts, web_search.
• synthesize — основная модель потоком выдаёт ответ по этому контексту, с расширенным мышлением на сложных ходах, а в конце предлагает следующие вопросы.

Более старые ходы сворачиваются в скользящее резюме, поэтому длинный чат не отправляет заново всю переписку. OpenAI-совместимый /v1 проходит те же проверки и того же агента (без кэша ответов), и каждый агент виден в нём как модель. Он не проходит через публичную точку входа; клиенты обращаются к нему во внутренней сети.

Знания, факты и веб

Планировщик выбирает источник по типу утверждения:

• Числа, цены, ставки, лимиты и даты берутся только из справочных фактов — типизированных строк в PostgreSQL, доступных через MCP. Агента и отчётный год при каждом вызове задаёт код, а не модель, поэтому планировщик не может добраться до фактов другого агента.
• Объяснения берутся из базы знаний: плотный поиск в Qdrant, переранжирование cross-encoder'ом, затем небольшие фрагменты расширяются до родительского отрывка. Отдельная коллекция с меньшим весом, кураторская, хранит заметки, написанные или одобренные администраторами.
• Свежая информация берётся из веб-поиска, ограниченного списком разрешённых доменов для каждого агента.

У факта одна общая форма, поэтому цены службы поддержки и сроки налогового агента лежат в одной таблице — новая предметная область означает новые данные, а не новую схему:

{"fact_key": "plan_price_monthly", "variant": "plus", "category": "pricing",
 "legal_year": 2026, "value_type": "money", "value_num": 6, "unit": "EUR",
 "label_en": "Plus plan — price per user per month",
 "source_url": "https://acme.example/pricing"}

Необязательный верификатор, по умолчанию выключенный, сверяет числа в ответе с результатами инструментов. Дообучение поиска на отзывах пользователей запускается вручную; по расписанию оно не выполняется.

Цикл улучшений

Каждый агент улучшается на собственном трафике. Воркер проверяет недавние диалоги агента, с замаскированными персональными данными, ежедневно или по запросу. Он оценивает каждый ответ по тому, что ассистент действительно прочитал, — дословному контексту и действующим директивам, — поэтому вердикт не является догадкой.

Похожие находки группируются в кластеры, а кластер — это тикет, с которым работает проверяющий. Ничто не попадает в кураторскую коллекцию, пока администратор это не одобрит, — если только не включён флаг автодобавления (по умолчанию выключен) и не пройдены строгие проверки; утверждение, которое противоречит источникам, никогда не добавляется автоматически.

Безопасность и изоляция

• Идентификация делегирована. Аккаунты, пароли, сессии и роли хранятся в pacod-id. API следит за лентой событий pacod-id, поэтому завершённая сессия или отключённый аккаунт отклоняются за считанные секунды. Изменения аккаунтов и ролей выполняются в pacod-id от имени администратора, который их вносит: только суперпользователь может назначить суперпользователя, а последнего администратора удалить нельзя.
• Агенты разграничены в коде. Агент авторизуется до начала любой работы, аргументы инструментов, затрагивающие данные агента, задаёт код, /v1/models показывает только агентов вызывающего, а каждый ключ кэша агента содержит его идентификатор.
• Секреты остаются на месте. Ключи провайдеров LLM хранятся только в шлюзе. Ключи веб-поиска зашифрованы в базе данных. Файлы с секретами генерируются, имеют права 0600 и внесены в gitignore, а внутренние сервисы отказывают в доступе, если их общий токен не задан.
• Безопасность промптов. Отказ от незаконных запросов стоит в самом начале промптов планировщика и синтезатора и главнее директив администратора; текст администраторов и пользователей всегда подставляется как значение, а не как шаблон.

Эксплуатация

Три стека Docker Compose запускаются по порядку — это делает make up-all:

1. Приложение — два compose-файла. Файл приложения содержит собственные сервисы pacod-ap, Redis, PgBouncer и сервис эмбеддингов; standalone-файл — его копии общих компонентов: Caddy, PostgreSQL, Qdrant и pacod-id (локально ещё mailpit).
2. Шлюз — файл приложения pacod-gw из соседнего checkout. Он входит через тот же pacod-id, хранит свою базу данных в том же PostgreSQL и обслуживается тем же Caddy.
3. Мониторинг — Prometheus, Alertmanager и Grafana; необязательно, make up-all запускает его, если существует monitoring/.env.

Поскольку общие компоненты вынесены в отдельный файл, pacod-demo может загрузить файл приложения pacod-ap вместе с другими проектами pacod и запустить по одному экземпляру каждого общего компонента; результат работает на demo.pacod.io. На одном хосте может работать только одна копия каждого общего компонента, поэтому pacod-ap в одиночном режиме не запускается рядом с другим стеком pacod.

Локально шлюз отвечает через свои mock-провайдеры: заготовленные ответы, без затрат.

Конфигурация читается из кэша Redis, затем из строки app_settings с ключом по агенту, затем из значения по умолчанию из окружения; при сбое используются значения по умолчанию, а ход не блокируется.

Вызовы LLM атрибутируются пользователю, сессии, ходу, агенту и цели, поэтому страницы использования и затрат в консоли читают отчёты шлюза, а не ведут собственный учёт. Вызов, превысивший время ожидания, никогда не повторяется — провайдер всё равно его оплачивает, — поэтому пользователь задаёт вопрос снова.

Наблюдаемость — строка аудита на каждый запрос, пошаговая Debug Console по включению, структурированные логи и метрики Prometheus от каждого сервиса, с дашбордами Grafana для приложения, инфраструктуры, веб-трафика, краулеров и использования, плюс собственные дашборды шлюза.

Резервное копирование — make backup записывает один архив с дампами баз данных, снапшотами Qdrant, конфигурацией и секретами; make restore восстанавливает из него.

Создайте своего агента

Есть два пути:

• В консоли — суперпользователь создаёт агента на странице Profiles или в визуальном редакторе агентов. Новый агент начинает в dev; вы тестируете его там и публикуете, когда он готов. Версии только добавляются, поэтому публикация и откат просто перемещают указатель. AI-ассистент пишет черновики промптов и другого текста, но никогда не меняет сам граф.
• Как код — ProfileSpec в pacod-api/scripts/profiles/<id>.py (тема, языки, переопределения промптов и настроек) и данные в pacod-api/data/profiles/<id>/: справочные факты, корпус и эталонный набор вопросов. make seed-example PROFILE=<id> устанавливает его.

Затем пообщайтесь с ним, посмотрите Debug Console и трассировку хода в шлюзе и запустите make eval на эталонном наборе. Дальше за дело берётся цикл улучшений.

Подробнее

• Runbook — стеки, секреты, реальные провайдеры, резервное копирование, устранение неполадок.
• LLM-шлюз — атрибуция, повторные попытки, квоты, использование.
• Создайте своего агента — полное руководство.
• Архитектура API и архитектура UI — устройство в подробностях.