Регистрация SDK A2A агента

Результат и область инструкции

Команда разрабатывает агента на выбранном языке, поставляет его контейнерный образ и Helm-чарт. После установки в aip-qa-agents Agent Registry проверяет ресурсы и карточку A2A, затем показывает доступного агента в общем каталоге. Пользователь входит через Keycloak и вызывает агента через Agent Gateway.

Инструкция относится к любому приложению, совместимому с профилем agent-platform.agent-registry.sdk-helm/v1. Профиль включается владельцем среды. Наличие документации само по себе не означает, что обновление платформы уже установлено в QA.

Язык, библиотеку SDK, модель, инструменты и хранение истории выбирает команда. Агенту не обязательно использовать LLM, Team Docs, RAG или Memory. Пример агента Team Docs описан отдельно: его Node.js, SQLite, выбор выпуска и ограничения файлов не являются общими требованиями.

Владение и подготовка

Самостоятельный SDK устанавливается отдельным Helm release. Для него не создаются фиктивные Agent, AgentVersion или задания публикации в CP. Registry не устанавливает приложение и не предоставляет API ручного создания агента. Общая платформа продолжает развёртываться через Garden.

Готового установщика, который знал бы содержимое чужого чарта, нет: автор поставляет свой чарт и свой prepare-values-скрипт, соответствующие требованиям ниже, — платформа не подгружает и не проверяет их заранее. В репозитории agent-platform есть необязательный оркестратор механических шагов — docs/runbooks/sdk-agent-deployment/deploy-sdk-agent.sh: он резолвит тег образа в digest, проверяет архитектуру образа под узлы кластера, запускает helm lint и двухпроходный helm upgrade --install (см. шаг 5). Он не заменяет ваш чарт и prepare-values, только вызывает их; prepare-values при этом должен быть написан на Node.js — для другого языка тулинга используйте шаги ниже как образец команд без самого скрипта. Настройки конкретного приложения и шаблоны платформенной регистрации — разные части этого чарта.

1. Проверить интерфейс приложения

Внутри Pod приложение обслуживает HTTP на TCP/8443; номер порта сам по себе не означает TLS. Публичный HTTPS обеспечивает шлюз среды. Карточка доступна на /.well-known/agent-card.json.

Пример карточки текстового агента:

{
  "name": "Мой SDK-агент",
  "description": "Описание задачи",
  "version": "1.0.0",
  "supportedInterfaces": [{
    "url": "https://agent-gw-qa.ai-dev.inno.tech/a2a/v1/agents/<agentId>",
    "protocolBinding": "HTTP+JSON",
    "protocolVersion": "1.0"
  }],
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [{
    "id": "main",
    "name": "Основная задача",
    "description": "Что делает агент",
    "tags": ["assistant"]
  }]
}

Вместо <agentId> подставляется UUIDv7 агента. Внутренние адреса Service и Pod в карточку не попадают. Валидатор принимает описанный набор полей; пустые securitySchemes, securityRequirements и signatures допускаются, собственная схема авторизации в карточке — нет. Подмена версии старой карточки A2A 0.3 не делает её совместимой.

Приложение реализует /message:send и методы работы с задачами, необходимые для его сценария. Для потока нужен /message:stream. Идентификаторы, состояния, события и ошибки соответствуют A2A. Произвольный HTTP-обработчик JSON не становится A2A-агентом автоматически.

Файлы указываются в карточке только при реальной поддержке приложением. Встроенное вложение A2A 1.0 использует raw (base64), mediaType и filename. Размеры, форматы, OCR и загрузка по URL определяются приложением, а не фактом регистрации. Для SSE проверьте, что фрагменты поступают до конца обработки. Запрос уточнения передаётся через TASK_STATE_INPUT_REQUIRED.

Расширение событий инструментов необязательно. Для urn:agent-platform:activity:v1 поле required отсутствует или равно false, params отсутствует или пуст. Метаданные сообщения состояния под этим URI содержат kind: tool, id, name, state: running|completed|failed. Сообщение одного вызова сохраняет свой идентификатор. Комментарии передаются отдельным артефактом с kind: commentary, итоговый ответ — другим артефактом. Это позволяет Harness разделять ответ и ход работы, но не требуется агентам без таких событий.

2. Получить параметры QA

Оператор согласует контекст Kubernetes, разрешённую identity Helm, доступ к registry, StorageClass, необходимые секреты и сетевые зависимости. Параметры общего шлюза, ListenerSet, OIDC и правил доступа берутся из QA.

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. Владелец среды сохраняет sdkHelmEnabled: true и sdkHelmWriter с разрешённой identity в конфигурации Garden. Одноразовые параметры команды не сохраняются при следующих обновлениях.

Не создавайте отдельный общий Gateway, Keycloak или TLS ради установки агента. Личная конфигурация другого стенда не является конфигурацией QA.

3. Подготовить зависимости

Если агент обращается к модели платформы, администратор выдаёт отдельный виртуальный ключ CP с доступом к нужным моделям. Ключ доставляется в Secret в aip-qa-agents. Тариф и политика Guardrails выбираются по сценарию. Общих фиксированных лимитов токенов и обязательного поставщика для SDK нет.

Аналогично настраиваются базы данных, инструменты и остальные зависимости. В сетевой политике разрешаются нужные исходящие соединения с фактическими портами назначения. Секреты не записываются в образ, values или Git.

Пользовательский токен вызова A2A проверяет Gateway. Исходный токен и заголовки личности в процесс агента не передаются. Этот профиль не предоставляет делегирование пользовательских прав внутренним инструментам агента.

4. Подготовить образ и чарт

Соберите и проверьте приложение средствами своего языка. Загрузите образ в доступный QA registry и зафиксируйте repository@sha256:<digest>. Проверьте архитектуру образа, настройки запуска и готовность.

Не монтируйте токен Kubernetes ServiceAccount в процесс агента без отдельного согласованного требования. Число реплик определяется реализацией приложения: для нескольких реплик нужен согласованный доступ к задачам и контекстам.

Service и идентификаторы

agentId — постоянный UUIDv7; agentVersionId — UUIDv7 неизменяемой версии. publicationRevision и metadataRevision — положительные целые числа. Имя Service: sdk-<agentVersionId без дефисов>-r<publicationRevision>.

Метки Service используют префикс agent-platform.inno.tech/:

Селектор Service содержит ровно три метки с тем же префиксом: agent-id, agent-version-id, publication-revision. Те же значения должны быть на Pod. publishNotReadyAddresses не включается.

Аннотации Service с тем же префиксом:

Хеш метаданных вычисляется по объекту agentId, metadataRevision, name, owner, schemaVersion. Значение схемы — agent-platform.control-plane.agent-metadata-owner/v1. Владелец — null либо объект type, issuer, subject; тип — principal или service. Ключи JSON сортируются, пробелы-разделители убираются, Unicode сохраняется. SHA-256 вычисляется по UTF-8 и записывается как sha256:<hex>. Название схемы не означает создание объекта в CP.

Маршруты и политики

Публичный путь: /a2a/v1/agents/<agentId> на https://agent-gw-qa.ai-dev.inno.tech. Имя маршрута: agent-<agentId без дефисов>-public; профиль — r2-public-selection. Префикс переписывается в корень приложения, backend — Service данной публикации на 8443.

Путь проверки: /internal/agent-validation/v1/agents/<agentId>/versions/<agentVersionId>/publications/<publicationRevision>. Имя: validate-<agentVersionId без дефисов>-r<publicationRevision>; профиль — r2-candidate-validation. Точный путь переписывается в /.well-known/agent-card.json. Маршрут проверки не является публичным интерфейсом каталога.

Оба маршрута привязаны к согласованному ListenerSet и фактическому UID Service. Публичный доступ — platform_oidc / authenticated_all; проверка карточки доступна только согласованным служебным identity. Issuer, аудитории, JWKS, TTL и удаление заголовков должны соответствовать профилю среды. Registry сравнивает спецификацию AgentgatewayPolicy и входящее правило NetworkPolicy с ожидаемыми значениями.

Для разработки чарта используйте реализацию профиля в исходниках платформы src/agent_registry/publication_observation.py. Рабочие шаблоны маршрутов и политик указаны в отдельном примере. Настройки приложения из примера заменяются вашими; параметры OIDC и шлюза — значениями QA. Похожая произвольная политика не заменяет точный профиль.

NetworkPolicy <имя Service>-gateway выбирает те же три метки публикации. Вход разрешён от согласованного шлюза на TCP/8443, с точными дополнительными адресами шлюза, если их требует среда. Не открывайте второй путь в обход шлюза.

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

Команды используют ваш чарт и его файл параметров. Имена полей values задаёт автор чарта; Registry проверяет итоговые ресурсы Kubernetes.

export SDK_RELEASE='<имя Helm release>'
export SDK_CHART='<путь к распакованному чарту>'
export SDK_VALUES='<путь к параметрам QA вне Git>'
helm lint "$SDK_CHART" -f "$SDK_VALUES"
helm template "$SDK_RELEASE" "$SDK_CHART" \
  --namespace aip-qa-agents -f "$SDK_VALUES"
helm upgrade --install "$SDK_RELEASE" "$SDK_CHART" \
  --kube-context "$QA_CONTEXT" --namespace aip-qa-agents \
  --values "$SDK_VALUES" --wait --timeout 5m

Чарт должен ссылаться на существующие секреты, а не выводить их содержимое при проверке шаблонов.

При создании Service его UID ещё неизвестен. Референтный чарт сначала создаёт приложение и Service; повторный helm upgrade после готовности Pod читает UID и создаёт маршруты. Если ваш чарт использует такой порядок, повторите команду. Подставлять придуманный UID или UID службы другого агента нельзя.

Вместо ручного повтора helm upgrade можно вызвать оркестратор из раздела выше, docs/runbooks/sdk-agent-deployment/deploy-sdk-agent.sh. Он сам определяет первую установку и смену ревизии публикации (новый agentVersionId переименовывает Service) и в обоих случаях выполняет второй проход. Ваш чарт и prepare-values при этом не меняются — оркестратор лишь вызывает их с готовым --image <repo>@sha256:<digest>.

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

kubectl --context "$QA_CONTEXT" -n aip-qa-agents get pods,services,endpointslices
kubectl --context "$QA_CONTEXT" -n aip-qa-agents get httproutes,agentgatewaypolicies
kubectl --context "$QA_CONTEXT" -n aip-qa-agents get networkpolicies

Для своих ресурсов проверьте готовность Pod и EndpointSlice, условия HTTPRoute Accepted=True и ResolvedRefs=True, принятую и прикреплённую AgentgatewayPolicy. Registry отдельно проверяет карточку, digest, UID, защищённый маршрут и сетевой доступ. Успешный Helm upgrade недостаточен.

После входа пользователь должен увидеть своего агента с типом sdk. Каталог доступен через https://api-gw-qa.ai-dev.inno.tech/agent-registry/api/v2/agents?implementationType=sdk&protocol=a2a. Параметры и права описаны в API Registry.

7. Проверить вызов

Войдите в A2A-клиент через Keycloak, выберите агента и начните диалог. Отправьте запрос по его назначению. Проверьте содержательный результат, а не только HTTP 200.

Для HTTP-вызова используйте адрес из проверенной карточки, A2A-Version: 1.0 и действующий платформенный bearer-токен. Аудитория берётся из AP_REGISTRY_PUBLIC_ROUTE_AUDIENCE профиля среды (стандартное значение — agent-platform-agent-gateway). Токен только для Registry может не подойти.

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

8. Обновить или удалить

При смене образа или возможностей создайте новый agentVersionId, SemVer и следующую publicationRevision. Сохраните agentId. Согласуйте карточку, digest, метки, селекторы и маршруты с UID новой службы. Повторите проверки регистрации и вызова.

Harness сохраняет старый разговор для чтения, но начинает общение с новой версией в новом диалоге. Это поведение клиента, а не требование ко всем внешним A2A-клиентам.

Перед удалением закройте публичный маршрут средствами чарта, подтвердите недоступность вызова и скрытие записи из доступного каталога, затем удалите release:

helm uninstall "$SDK_RELEASE" --kube-context "$QA_CONTEXT" --namespace aip-qa-agents

Сохранение PVC, резервирование, удаление истории и отзыв ключей определяются чартом и правилами приложения. Не предполагайте, что любой чарт сохраняет том. Откат выполняется Helm с совместимыми данными и проверенным образом; операции отката low-code публикации CP здесь неприменимы.

Диагностика

Граница проверки

Профиль проверен на самостоятельном SDK-агенте в dev-local. Команда подтверждает совместимость своего образа и чарта отдельно; регистрация не добавляет приложению отсутствующие возможности. Установка и приёмка QA выполняются владельцем среды и здесь не объявляются пройденными.