Руководство пользователя

Для кого предназначено руководство

Документация описывает основные пользовательские роли. Один человек может совмещать их, однако права и ответственность остаются разными.

Agent Registry и Low-code Конструктор используют токен пользователя, но выполняют разные проверки доступа. Возможность открыть Low-code Конструктор не дает права видеть любой агент в каталоге. Для A2A-вызова нужен действующий токен платформы: проверка токена на Gateway выполняется отдельно от прав просмотра каталога и аналитики Activity.

Общая последовательность работы

1. Создать Поток (Flow)

Откройте адрес Low-code Конструктора, предоставленный администратором вашей среды, и войдите через SSO.

Создайте новый поток или откройте рабочую версию. Используйте только компоненты, доступные в разрешенной палитре — она задана действующей политикой компонентов. В версии 2026.4.1 компоненты PlatformRAG и PlatformMemory отсутствуют. Минимальный поток содержит вход, PlatformLLM и выход.

Не добавляйте:

• внешних поставщиков моделей и векторных хранилищ;
• сетевых загрузчиков с непроверяемым исходящим соединением;
• открытых ключей, паролей и токенов;
• произвольного кода, если он не разрешен действующей политикой компонентов.

Подробные действия приведены в руководстве по Low-code Конструктору.

2. Сохранить рабочую версию

Сохраните Flow до запуска проверки. Убедитесь, что название отражает назначение агента, а не адрес среды или имя автора. Любая правка после зафиксированной версии создает новую рабочую версию; повторное сохранение одной неизмененной версии дает одинаковую контрольную сумму SHA-256.

Сохранение означает только фиксацию рабочей версии в Low-code Конструкторе. Оно не разворачивает экземпляр агента для взаимодействия с ним.

3. Проверить Flow

Запустите серверную проверку и дождитесь итогового состояния. Успешный результат содержит версию проверяющего модуля, версию политики и SHA-256 исходных данных. Проверка должна подтвердить:

• корректность структуры и отсутствие недопустимых циклов;
• наличие обязательных полей;
• соответствие действующей политике компонентов;
• отсутствие открытых секретов и запрещенных импортов;
• совместимость с принятой версией lfx;
• согласованность входных и выходных данных с карточкой агента.

Код component_not_allowed означает, что схему нельзя публиковать: нужно удалить компонент или заменить его на разрешенный.

4. Опубликовать Агента

Публикация выполняется прямо из интерфейса Low-code Конструктора через Control Plane:

1. Запустите проверку Flow и дождитесь успешного результата.
2. Откройте сохраненную рабочую версию и вызовите публикацию.
3. Система экспортирует Flow в канонический формат platform.low-code.flow/v2 и от вашего имени вызывает Control Plane через api-gw.
4. Control Plane выполняет проверку, создает запись Агента и версии, а также операцию публикации.
5. Publisher собирает артефакт и развертывает workload в Kubernetes.

Ответ 202 Accepted означает, что операция публикации принята, а не что Агент уже готов. О завершении публикации говорит конечный статус операции в Control Plane. Изменяемые поля Flow.data в публикацию не попадают, прямой загрузкой схемы в OCI, Kubernetes или Agent Registry пользоваться нельзя.

5. Дождаться готовности среды исполнения

После развертывания workload Publisher доводит Low-code Runtime до рабочего состояния. Готовность подтверждается конечным статусом операции публикации.

6. Найти агента

Agent Registry автоматически обнаруживает опубликованный workload в Kubernetes. Запись появляется в каталоге только после взаимодействия с Kubernetes, формирования карточки агента и авторизационных данных в SpiceDB, поэтому появление агента не мгновенно. Каталог показывает только активные записи (lifecycleStatus = active), на которые подтверждено право agent#view.

Откройте каталог и найдите агента:

• по фильтру — протоколу (a2a, mcp) или типу реализации (low-code, sdk);
• по владельцу через ownerType, ownerIssuer, ownerSubject;
• гибридным поиском POST /api/v2/agents/search — по смыслу и по точным формулировкам.

Если агент еще не появился:

1. подождите несколько секунд и повторите запрос;
2. проверьте, что операция публикации достигла конечного успешного статуса;
3. обратитесь к администратору с идентификатором операции публикации.

Подробности приведены в руководстве по Agent Registry.

Разработчик отдельного SDK-агента использует автоматическое обнаружение через Kubernetes по инструкции регистрации SDK A2A агента.

7. Вызвать агента

Карточка активного A2A-агента содержит проверенный интерфейс вызова, когда выбранная версия готова, отношения просмотра согласованы, а публичный маршрут актуален и связан с текущей службой Kubernetes. Используйте URL из карточки: это стабильный адрес агента через Platform Agent Gateway. Идентификатор выбранной версии указан отдельно и не добавляется в URL пользователем.

Gateway проверяет токен платформы. В действующем профиле любой прошедший эту проверку пользователь или сервис может вызвать опубликованного A2A-агента; отдельное разрешение agent#invoke не применяется. Исходный токен и личность вызывающего не передаются агенту. Поэтому агент не исполняет вызов от имени пользователя, а его расход через служебный LLM-ключ не связывается автоматически с человеком, инициировавшим обращение.

8. Посмотреть активность и потребление

Откройте Control Plane и выберите «Активность и потребление». Вкладка «LLM-потребление» показывает доступные запросы к моделям, известный расход токенов, ошибки и длительности. Вкладка «Обращения к агентам» показывает HTTP-обращения к агентам; HTTP-статус не означает успешное завершение их бизнес-задач.

Выберите период, метрику и разрезы, например «агент × модель». Фильтры оставляют нужные записи, а разрезы распределяют их по группам. «Мои ключи» означает прямое владение ключами, а не личное выполнение всех учтённых запросов. При наличии диагностического доступа можно перейти от графика к журналу и карточке LLM-запроса. Стоимость и остаток квоты не рассчитываются.

Пошаговые примеры, правила доступа и объяснение неполных данных приведены в руководстве «Активность и потребление».

Использование Platform RAG

Важно: В релизе 2026.4.1 Platform RAG поставляется как самостоятельный сервис и не интегрирован с другими компонентами Платформы ИИ. Компонент PlatformRAG недоступен в палитре Low-code Конструктора, поэтому сервис доступен только агентам, которые обращаются к нему через Platform SDK.

Platform RAG предоставляет управляемую возможность извлечения знаний для агентов. Коллекция — это управляемый контейнер документов с закреплённым профилем эмбеддинга, моделью ACL и стратегией чанкинга. Поиск выполняется одновременно по смыслу (векторное сходство) и по точным формулировкам (BM25), результаты сливаются для оптимального ранжирования.

Доступные коллекции

Список коллекций, доступных пользователю, определяется правами доступа. Каждая коллекция имеет статус, количество документов и чанков. Статус ready означает, что документы проиндексированы и доступны для поиска.

Поиск в коллекции

Потребитель вызывает поиск через Platform SDK. Необходимо указать коллекцию и текст запроса. Результаты содержат цитаты — ссылки на источник, что обеспечивает проверку достоверности ответа.

Упаковка контекста

Для передачи контекста в LLM используется метод retrieve_and_pack. Он автоматически подбирает наиболее релевантные фрагменты, укладываясь в заданный бюджет токенов.

Подробности приведены в руководстве по Platform RAG.

Использование Memory Service

Важно: В релизе 2026.4.1 Memory Service поставляется как самостоятельный сервис и не интегрирован с другими компонентами Платформы ИИ. Компонент PlatformMemory недоступен в палитре Low-code Конструктора, поэтому сервис доступен только агентам, которые подключаются к нему через Platform SDK.

Memory Service предоставляет управляемый слой персистентной памяти для агентов. Агент запоминает факты о пользователях, сессиях и задачах, чтобы обращаться к ним в будущем — без повторного переспрашивания.

Сервис совместим с mem0: контракт API повторяет mem0, но аутентификация выполняется через JWT платформы, а авторизация — через SpiceDB.

Добавление памяти

Агент отправляет ход диалога — платформа извлекает атомарные факты, проводит дедупликацию и проиндексирует их. Извлечение выполняется асинхронно, результат возвращается через event_id.

Поиск памяти

Перед вызовом LLM агент ищет релевантные факты по семантике и BM25. Результаты ранжированы и уложены в заданный бюджет токенов.

Управление записями

Разработчик и аудитор читают, правят и удаляют конкретные записи памяти и видят историю их изменений. Пользователь может просматривать, редактировать и удалять записи об себе через интерфейс T1GPT.

Рабочая память сессии

Агент сохраняет и восстанавливает состояние сессии (чекпоинт) с настраиваемым временем жизни — без собственного Redis.

Подробности приведены в руководстве по Memory Service.

Что пользователь увидит при ошибке

Работа с файлами

Если агент принимает файл, клиент передает FileRef, а не произвольный URL или путь к хранилищу. FileRef связан с пользователем, целевым агентом, операцией и сроком действия. Измененный, просроченный или предназначенный другому агенту FileRef отклоняется до выполнения схемы.

Не включайте в обращение:

• прямую ссылку на объектное хранилище;
• идентификатор файла внутреннего поставщика;
• пользовательский токен;
• содержимое секрета или профиля Vault.

Безопасная работа

• Не размещайте секреты, персональные данные и внутренние адреса в названии, описании или полях схемы.
• Не передавайте токены и FileRef через сообщения, снимки экрана и журналы.
• Не повторяйте запрос с побочным действием автоматически, если результат предыдущего вызова неизвестен.
• Сообщая об ошибке, передавайте безопасный traceId, время, версию агента и код ошибки, но не исходный токен и не полный текст запроса.

Ограничения версии

Пользовательский путь заканчивается подтвержденным вызовом только после готовности Low-code Конструктора, Low-code Runtime и Agent Registry. В релизе 2026.4.1 сохраняются ограничения:

• PlatformRAG и PlatformMemory отсутствуют в палитре Low-code Конструктора; Platform RAG и Memory Service поставляются как самостоятельные сервисы и не интегрированы с другими компонентами Платформы ИИ — доступ только через Platform SDK;
• промышленная готовность семантического поиска не подтверждена;
• полный жизненный цикл задач A2A и расширенные возможности MCP не входят в гарантированный профиль;
• Activity учитывает наблюдаемые запросы и обращения, но не полный жизненный цикл запуска агента; инициатор расхода служебного LLM-ключа остаётся неизвестным;
• нагрузочная приёмка Activity и итоговая проверка поставки продолжаются; наличие пользовательского интерфейса не означает завершения этих проверок.

Перед началом работы ознакомьтесь с известными ограничениями.