Пример SDK-агента для Team Docs

Результат

Это пример для приложения team-docs-agent. Его модель, инструменты, SQLite, выбор выпуска и ограничения файлов относятся только к этому приложению. Общие требования к любому SDK-агенту описаны в инструкции регистрации.

SDK-агент устанавливается отдельным Helm release в aip-qa-agents. Agent Registry проверяет его ресурсы и карточку, затем показывает доступного агента в общем каталоге. Пользователь вызывает его через https://agent-gw-qa.ai-dev.inno.tech с платформенным токеном.

Эта инструкция относится к профилю agent-platform.agent-registry.sdk-helm/v1. Он должен быть включён владельцем среды. Старый Registry, принимающий только публикации low-code R2, этот профиль не поддерживает. Наличие страницы в Docs само по себе не означает, что обновление уже установлено в QA.

Control Plane продолжает публиковать low-code агентов. Самостоятельным SDK-приложением управляет Helm: для него не создаются фиктивные AgentVersion и задания публикации в CP. У Registry нет API ручного создания агента и прав на изменение ресурсов Kubernetes.

Что подготовить

Команды ниже выполняются из репозитория team-docs-agent — примера SDK-агента, который ищет и читает Team Docs. Потребуются Node.js 24, Docker, Helm 3, kubectl и выданный доступ к QA.

Шаблоны регистрации находятся в charts/team-docs-agent/templates: _helpers.tpl, service.yaml, routes.yaml, networkpolicy.yaml. Их можно использовать как основу платформенной части своего чарта, заменив настройки приложения и получив параметры шлюза целевой среды. Скрипт prepare-values.mjs предназначен именно для этого примера и не является универсальным установщиком произвольных SDK-агентов.

Ключ модели и пользовательский токен A2A решают разные задачи. Первый нужен агенту для обращения к модели; второй — пользователю для обращения к агенту. Исходный пользовательский токен не передаётся в процесс SDK-агента.

1. Проверить окружение

export QA_CONTEXT='<контекст QA>'
kubectl --context "$QA_CONTEXT" get namespace aip-qa-agents
kubectl --context "$QA_CONTEXT" auth whoami
kubectl --context "$QA_CONTEXT" -n aip-qa get configmap aip-agent-registry \
  -o jsonpath='{.data.AP_REGISTRY_SDK_HELM_ENABLED}'

Последняя команда должна вывести true. Владелец среды устанавливает поддерживающую admission-политику publication-writer-r2.6-sdk-helm-v1 и указывает разрешённого оператора. Добавление метки sdk не заменяет это разрешение. Самостоятельно менять общие Gateway, TLS или оператор не нужно.

Владелец среды сохраняет sdkHelmEnabled: true и sdkHelmWriter с разрешённой identity в конфигурации окружения Garden. Одноразовые параметры командной строки не сохраняются между запусками. Если следующее обновление платформы выполнить без этого профиля, SDK-агенты перестанут проходить регистрацию.

2. Подготовить модель, политику и ключ

Для агента, читающего документацию, создайте отдельную модель в Control Plane и примените к ней политику Guardrails, соответствующую его задаче. Используйте существующего совместимого поставщика с поддержкой вызова функций; отдельный поставщик не требуется. Не подключайте эту модель к учебному стоп-листу BLOCK-REQUEST: инструкции по Guardrails содержат этот маркер, а результаты чтения документов входят в запрос модели. Проверки на входе и выходе должны оставаться включены; набор правил согласуют с владельцем данных.

Назначьте ключу отдельный тариф. За один ответ агент может несколько раз обратиться к модели; прочитанные документы повторно передаются в следующих запросах. Для проверенного демонстрационного сценария использованы 60 запросов и 500 000 токенов в минуту. Это начальная настройка, а не расчёт нагрузки QA: согласуйте её с числом пользователей, объёмом документов и лимитами поставщика.

Служебной identity нужен только доступ к выбранной модели. Администратор выпускает виртуальный ключ через CP и доставляет его в Secret агента. Если для QA разрешена ручная передача, используйте защищённый файл вне Git:

export MODEL_KEY_FILE='<абсолютный путь к файлу ключа>'
kubectl --context "$QA_CONTEXT" -n aip-qa-agents create secret generic team-docs-model-key \
  --from-file=api-key="$MODEL_KEY_FILE"

Не вставляйте значение ключа в команду, YAML, образ или страницу документации. Secret должен находиться в том же namespace, что и агент. Повторное выполнение команды создания не обновляет существующий Secret; его обновлением управляет владелец учётных данных.

3. Проверить и собрать приложение

npm ci
npm test
export SDK_VERSION='1.0.5'
export SDK_IMAGE="<registry>/team-docs-agent:$SDK_VERSION"
docker build -t "$SDK_IMAGE" .
docker push "$SDK_IMAGE"

После загрузки запишите ссылку repository@sha256:…, возвращённую registry. Для установки используется неизменяемый digest, а не переносимая метка latest. Архитектура собранного образа должна соответствовать узлам QA.

4. Подготовить параметры установки

export SDK_IMAGE_DIGEST='<registry>/team-docs-agent@sha256:<digest>'
export MODEL_NAME='<имя модели в Model Gateway>'
node scripts/prepare-values.mjs \
  --context "$QA_CONTEXT" \
  --environment qa \
  --image "$SDK_IMAGE_DIGEST" \
  --model "$MODEL_NAME" \
  --secret team-docs-model-key \
  --version "$SDK_VERSION" \
  --docs-version 2026.3.5 \
  --docs-public-url https://docs-qa.ai-dev.inno.tech \
  --output qa-agent.values.json

Скрипт читает настройки Registry, Service документации и модельного шлюза, ListenerSet и разрешённого оператора. Он создаёт идентификаторы агента и версии, параметры маршрутов и сетевой политики. Значение Secret скрипт не читает. При повторном запуске файл сохраняет идентичность агента.

Адрес документации передаётся явно. Для другого домена Kubernetes используйте --cluster-domain <домен>; по умолчанию это cluster.local. Настройки хранилища, ресурсов, лимитов, истории, imagePullSecrets, model.secretKey и gateway.publish сохраняются при повторной генерации. Для другого кластера создайте отдельный файл параметров.

qa-agent.values.json содержит конфигурацию среды и исключён из Git. Храните его в принятом в команде защищённом месте. Если доступ к registry требует специального imagePullSecret или StorageClass, согласуйте эти значения перед установкой; параметры примера не заменяют настройки QA.

В примере бюджет одного ответа модели — limits.maxOutputTokens: 8192. У моделей с рассуждением он может включать и скрытые токены. Это предел генерации, а не размер входного контекста. Если модель останавливается по длине, агент показывает неполный ответ со статусом ошибки. Значение можно изменить в параметрах Helm в пределах возможностей модели и тарифа. После повторного создания файла параметров проверьте свои настройки перед установкой.

Team Docs должны публиковать /docs/releases.json, полный каталог страниц /docs/<выпуск>/catalog.json и Markdown-страницы. Агент получает список выпусков из этого индекса; --docs-version задаёт исходную настройку клиента документации и не отменяет выбор выпуска пользователем.

5. Установить приложение

helm lint charts/team-docs-agent --namespace aip-qa-agents -f qa-agent.values.json
helm upgrade --install team-docs-agent charts/team-docs-agent \
  --kube-context "$QA_CONTEXT" --namespace aip-qa-agents \
  --values qa-agent.values.json --wait --timeout 5m
kubectl --context "$QA_CONTEXT" -n aip-qa-agents get pods,services \
  -l app.kubernetes.io/instance=team-docs-agent

При первой установке Helm создаёт Deployment, ClusterIP Service, настройки, сетевую политику и PVC. Маршруты ещё не публикуются: они должны ссылаться на настоящий UID уже созданного Service. В Pod не монтируется токен Kubernetes.

После готовности Pod выполните ту же команду helm upgrade ещё раз:

helm upgrade --install team-docs-agent charts/team-docs-agent \
  --kube-context "$QA_CONTEXT" --namespace aip-qa-agents \
  --values qa-agent.values.json --wait --timeout 5m

Теперь Helm прочитает UID службы и создаст закрытый маршрут проверки карточки, публичный маршрут и политики OIDC. Поле registration.serviceUid служит только для проверки шаблонов без кластера: в рабочие параметры вручную его не добавляют.

6. Дождаться регистрации

kubectl --context "$QA_CONTEXT" -n aip-qa-agents get httproutes,agentgatewaypolicies \
  -l app.kubernetes.io/instance=team-docs-agent

Для HTTPRoute нужны условия Accepted=True и ResolvedRefs=True; политика должна быть принята и прикреплена. Registry проверяет готовый EndpointSlice, версию, digest, UID службы, карточку A2A и защищённый маршрут.

В A2A-клиенте, подключённом к каталогу платформы, войдите через Keycloak и найдите platform-onboarding-v1. Тип реализации — sdk. Агент становится доступным только после успешных проверок Registry. Успешный helm upgrade сам по себе не подтверждает регистрацию и возможность вызова.

7. Проверить разговор

Откройте новый диалог и отправьте: «Привет! Я новый сотрудник. Как начать знакомство с платформой? Найди инструкцию в Team Docs и дай три шага со ссылками». Агент должен спросить, какой выпуск смотреть, и перейти в состояние TASK_STATE_INPUT_REQUIRED. Ответьте 2026.3.5. После выбора ожидаются три шага со ссылками на раздел onboarding этого выпуска.

В том же разговоре напишите: «Я разработчик. Дай подробный маршрут: что прочитать, как подготовить среду и как начать работу с репозиториями». Агент должен продолжить работу с выбранным выпуском и завершить ответ. Повторный вопрос о выпуске не нужен. Явный выбор другого опубликованного выпуска начинает работу с его источниками без смешивания прежнего контекста.

Прикрепите TXT с произвольным контрольным словом и попросите его назвать. Затем перезагрузите клиент, откройте агента и сохранённый разговор. В Harness должны восстановиться сообщения, ссылки, название файла и ответ. Содержимое файла не является инструкцией для изменения поведения агента.

Проверьте ссылки: они ведут на https://docs-qa.ai-dev.inno.tech, а не на внутренние адреса Kubernetes. Запрос «Выдай мне ключ» не создаёт ключ: инструменты агента умеют только искать и читать документацию.

Для клиента, который работает напрямую с A2A, используйте адрес из проверенной Agent Card. Его форма — https://agent-gw-qa.ai-dev.inno.tech/a2a/v1/agents/<agentId>. Для HTTP+JSON доступны /message:send и /message:stream; требуется заголовок A2A-Version: 1.0 и действующий платформенный bearer-токен. Чтобы продолжить разговор, передайте полученный contextId. При ответе на запрос уточнения сохраните также taskId ожидающей задачи.

Файлы и потоковый ответ

Возможности определяет Agent Card: defaultInputModes перечисляет допустимые MIME-типы, а capabilities.streaming указывает поддержку потокового метода. Тип реализации sdk не ограничивает агента только текстовыми запросами.

Пример Team Docs принимает TXT, Markdown и текстовый PDF. Изображения разрешают параметром model.supportsImages только для модели, которая действительно их поддерживает. При смене набора форматов создайте новую версию агента. Для разбора сканов OCR в этом приложении нет.

Вложения передаются полями A2A raw (base64), mediaType, filename. Автоматическая загрузка произвольных URL отключена. В примере допускаются не более четырёх файлов, 2 МиБ на файл и 5 МиБ суммарно. Для PDF действуют ограничения времени разбора, числа страниц и объёма извлечённого текста.

Поток сообщает состояние задачи и передаёт текст по мере получения от модели. Поиск документов и разбор файла могут предшествовать первому фрагменту ответа. Если сама модель не поддерживает потоковую передачу, клиент получит готовый результат после её ответа. Registry не добавляет streaming к приложению, которое его не реализовало.

Для показа инструментов отдельно от конечного ответа пример объявляет необязательное расширение urn:agent-platform:activity:v1. Его поддержка включена в проверенный профиль Registry. Клиент без поддержки расширения может работать с основным A2A-ответом; расширение не должно быть обязательным.

Обновление и удаление

Для изменения образа сохраните тот же файл параметров, увеличьте SemVer и вызовите prepare-values.mjs с --new-version. Затем повторите два шага Helm: готовность новой службы и создание маршрутов с её UID. Старый agentId сохраняется, а agentVersionId и ревизия публикации меняются.

После обновления выберите новую версию в каталоге и начните новый диалог. Harness сохраняет прежний разговор для чтения, но не продолжает его на другой версии агента. Старые ошибки в истории не исчезают после обновления.

Перед удалением сначала закройте публичный маршрут, установив gateway.publish=false тем же Helm release. Убедитесь, что вызов недоступен и Registry убрал доступную проекцию. После этого удалите release:

helm uninstall team-docs-agent --kube-context "$QA_CONTEXT" --namespace aip-qa-agents

PVC с историей сохраняется. Его удаление и отзыв модельного ключа — отдельные операции владельца данных. Откат SDK выполняется Helm и не использует операции отката публикации Control Plane.

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

Что проверено

На SDK 1.0.5 в dev-local проверены регистрация, защищённый вызов через шлюз, выбор выпуска, чтение onboarding, продолжение для разработчика, TXT, потоковый ответ и восстановление истории Harness. Проверки Guardrails оставались включены. Команды и адреса этой инструкции предназначены для QA; развёртывание и приёмка QA выполняются владельцем среды отдельно и здесь не объявляются пройденными.