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

Эта страница описывает прежний профиль регистрации. Для установки SDK-агента в aip-qa-agents используйте инструкцию 2026.3.5. Новый профиль требует соответствующего обновления Registry и настроек среды.

Как работает регистрация

В Agent Registry нет отдельной операции создания агента. Регистрация выполняется автоматически после развертывания рабочей нагрузки и k8s сущности Service с регистрационными метками в доверенном пространстве имён Kubernetes.

Agent Registry:

1. обнаруживает Service;
2. проверяет метки, аннотации и привязку пространства имён к рабочему пространству;
3. дожидается готового адреса из принадлежащего службе EndpointSlice;
4. загружает карточку агента по внутреннему адресу службы;
5. проверяет A2A 1.0, имя, версию, навыки и заявленные возможности;
6. добавляет разрешенную проекцию агента в каталог.

Объектом регистрации является Service, а не Deployment или отдельный Pod. Перезапуск экземпляра не создает новую запись, пока служба и логическая версия агента остаются прежними.

Что подготовить заранее

До развертывания запросите у владельца среды:

• точное пространство имён, включенное в состав доверенных в Agent Registry;
• идентификатор рабочего пространства для регистрационной метки;
• идентификатор команды из доверенного каталога владельцев;
• разрешенный способ доставки через Garden и Helm;
• требования среды к внутреннему TLS и публичному маршруту;
• права на просмотр и, при необходимости, вызов зарегистрированного агента.

Имя агента имеет форму <domain>-<function>-v<major> и должно быть допустимым DNS именем длиной не более 63 символов. Суффикс имени должен совпадать с основной частью SemVer: версии 1.0.0 соответствует суффикс -v1.

Подготовить карточку агента

Агент должен возвращать карточку по адресу /.well-known/agent-card.json, если в аннотации службы не указан другой безопасный абсолютный путь.

Минимальный пример для A2A 1.0 HTTP+JSON:

{
  "name": "finance-invoice-v1",
  "description": "Проверяет счет и извлекает структурированные поля.",
  "supportedInterfaces": [
    {
      "url": "https://agent.example/a2a/finance-invoice-v1",
      "protocolBinding": "HTTP+JSON",
      "protocolVersion": "1.0"
    }
  ],
  "version": "1.2.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "extendedAgentCard": false
  },
  "defaultInputModes": ["application/json", "text/plain"],
  "defaultOutputModes": ["application/json"],
  "skills": [
    {
      "id": "invoice_parsing",
      "name": "Разбор счета",
      "description": "Извлекает нормализованные поля из счета.",
      "tags": ["invoice", "finance"],
      "examples": ["Извлеки поставщика, сумму и НДС из этого счета"]
    }
  ]
}

Значения name и version должны точно совпадать с метками службы. В поставке 2026.3.3 для HTTP+JSON подтверждена возможность streaming. Не объявляйте неподдерживаемую возможность: Agent Registry не запускает агент для пробного вызова во время регистрации и полагается на правдивую неизменяемую карточку и проверку совместимости до развертывания.

Опубликовать Service

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

apiVersion: v1
kind: Service
metadata:
  name: finance-invoice-v1
  namespace: finance
  labels:
    agent-platform.inno.tech/registrable: "true"
    agent-platform.inno.tech/protocol: a2a
    agent-platform.inno.tech/agent-name: finance-invoice-v1
    agent-platform.inno.tech/version: "1.2.0"
    agent-platform.inno.tech/owner: team-finance-ai
    agent-platform.inno.tech/implementation-type: sdk
  annotations:
    agent-platform.inno.tech/registration-contract: agent-platform.agent-registry.registration/v1
    agent-platform.inno.tech/card-path: /.well-known/agent-card.json
    agent-platform.inno.tech/service-port: a2a
spec:
  type: ClusterIP
  selector:
    app.kubernetes.io/name: finance-invoice-v1
  ports:
    - name: a2a
      protocol: TCP
      port: 8443
      targetPort: a2a

Обязательные значения:

Поддерживается служба ClusterIP с селектором. Не используйте ExternalName, службу без селектора, созданный вручную EndpointSlice или publishNotReadyAddresses: true.

Проверить регистрацию

Сначала проверьте готовность рабочей нагрузки и принадлежность адреса службе:

kubectl --namespace finance get service/finance-invoice-v1 --output=wide
kubectl --namespace finance get endpointslice \
  --selector kubernetes.io/service-name=finance-invoice-v1 \
  --output=wide

Для диагностики в непроизводственной среде получите у владельца среды разрешенный тестовый адрес и проверьте карточку:

curl --fail --silent --show-error \
  "${AGENT_TEST_URL}/.well-known/agent-card.json" \
| jq '{name, version, supportedInterfaces, capabilities, skills}'

Схему внутреннего соединения и доверенный сертификат выбирает среда. Не отключайте проверку TLS ради диагностики.

После асинхронного обнаружения запросите каталог с пользовательским токеном:

curl --fail --silent --show-error \
  "${REGISTRY_URL}/api/v1/agents?workspaceId=finance&protocol=a2a&implementationType=sdk&limit=20" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
| jq '.items[] | select(.name == "finance-invoice-v1") | {
    id,
    name,
    implementationType,
    lifecycleStatus,
    selectedVersion
  }'

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

Подробности каталога и правил видимости приведены в руководстве по Agent Registry, а форма ответов — в описании API.

Проверить потоковую передачу A2A

Если карточка содержит streaming: true, до публикации версии проверьте фактический HTTP+JSON SSE-путь. Для контролируемой непроизводственной среды:

message_id="$(python3 -c 'import uuid; print(uuid.uuid4())')"

curl --no-buffer --fail-with-body --show-error \
  --request POST "${AGENT_TEST_URL}/message:stream" \
  --header 'A2A-Version: 1.0' \
  --header 'Accept: text/event-stream' \
  --header 'Content-Type: application/a2a+json' \
  --data-binary @- <<JSON
{
  "message": {
    "messageId": "${message_id}",
    "role": "ROLE_USER",
    "parts": [
      {
        "text": "Проверь тестовый документ",
        "mediaType": "text/plain"
      }
    ]
  }
}
JSON

Поток должен начинаться отправленной задачей, содержать рабочее состояние и последовательные обновления результата, а завершаться терминальным состоянием. Разрыв соединения, повторная подписка и получение завершенной задачи должны соответствовать A2A 1.0. Agent Registry сохраняет возможность потоковой передачи в каталоге, но не выполняет этот тест вместо разработчика.

Разобрать ошибку регистрации

Важно: При обращении в поддержку передавайте имя агента, версию, пространство имён, время развертывания и безопасный traceId. Не передавайте токен, секрет модели, внутренние учетные данные и полный закрытый запрос.

Обновить зарегистрированного агента

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

1. назначьте новую SemVer;
2. согласованно обновите карточку, образ и метку версии службы;
3. повторите проверки A2A и готовности;
4. дождитесь появления новой выбранной версии в Agent Registry;
5. сохраняйте предыдущую версию как явную точку отката на принятый срок.

При переходе с 1.x на 2.x измените суффикс логического имени с -v1 на -v2. Не меняйте содержимое уже опубликованной версии без изменения SemVer.

Граница безопасности

• Не помещайте ключи, токены и внутренние адреса в метки или описание карточки.
• Не публикуйте сырой адрес Service как пользовательский интерфейс.
• Не считайте регистрацию разрешением на просмотр или вызов.
• Не передавайте исходный пользовательский токен непосредственно SDK-агенту.
• В производственной среде вызывайте агент только через интерфейс Platform Agent Gateway, возвращенный Agent Registry после проверки прав.