Перейти к содержанию

Flows Public API

A2A (Agent-to-Agent) API - протокол для взаимодействия с ИИ-агентами в платформе Humanitec.

Обзор

A2A API реализует спецификацию Google A2A Protocol для управления агентами, отправки сообщений и работы с задачами. API поддерживает как синхронные, так и потоковые (streaming) запросы через JSON-RPC 2.0.

Базовый URL

https://humanitec.ru/flows/a2a/{flow_id}

Где {flow_id} - уникальный идентификатор агента в платформе.

Аутентификация

Все запросы требуют аутентификации через JWT токен:

  • Bearer токен в заголовке Authorization: Bearer {token}
  • API ключ в заголовке X-API-Key: {key}
  • Embed Session токен для встроенных виджетов

Токены содержат информацию о компании, пользователе и правах доступа.

Agent Card

Agent Card - это метаданные агента, описывающие его возможности, capabilities и настройки.

Получение Agent Card

GET /flows/a2a/{flow_id}
GET /flows/a2a/{flow_id}/.well-known/agent-card.json

Query параметры: - v - версия агента (опционально)

Пример: 

curl -H "Authorization: Bearer {token}" \
  https://humanitec.ru/flows/a2a/my-agent

Ответ: 

{
  "agentId": "my-agent",
  "displayName": "My AI Assistant",
  "description": "Helpful assistant for various tasks",
  "capabilities": [
    "streaming",
    "pushNotifications"
  ],
  "skills": [...]
}

JSON-RPC методы

Все методы вызываются через POST запрос на /{flow_id} с JSON-RPC 2.0 телом:

POST /flows/a2a/{flow_id}
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "content": {
        "parts": [
          {"text": "Hello, agent!"}
        ]
      }
    }
  }
}

message/send

Отправляет сообщение агенту и получает полный ответ.

Параметры: - message - объект сообщения с role и content - sessionId - идентификатор сессии (опционально) - metadata - дополнительные метаданные

Пример: 

curl -X POST https://humanitec.ru/flows/a2a/my-agent \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "content": {
          "parts": [
            {"text": "What is the capital of France?"}
          ]
        }
      }
    }
  }'

message/stream

Отправляет сообщение и получает потоковый ответ через Server-Sent Events (SSE).

Параметры: те же, что и message/send

Пример: 

curl -X POST https://humanitec.ru/flows/a2a/my-agent \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/stream",
    "params": {
      "message": {
        "role": "user",
        "content": {
          "parts": [
            {"text": "Tell me a story"}
          ]
        }
      }
    }
  }'

Ответ: SSE события с фрагментами ответа в реальном времени.

tasks/get

Получает информацию о задаче по её идентификатору.

Параметры: - taskId - идентификатор задачи

Пример: 

curl -X POST https://humanitec.ru/flows/a2a/my-agent \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tasks/get",
    "params": {
      "taskId": "task-123"
    }
  }'

tasks/cancel

Отменяет выполняющуюся задачу.

Параметры: - taskId - идентификатор задачи

Пример: 

curl -X POST https://humanitec.ru/flows/a2a/my-agent \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tasks/cancel",
    "params": {
      "taskId": "task-123"
    }
  }'

tasks/resubscribe

Переподписывается на потоковый ответ задачи через SSE.

Параметры: - taskId - идентификатор задачи

tasks/pushNotificationConfig/*

Управление конфигурацией push-уведомлений для задач:

  • tasks/pushNotificationConfig/get - получить конфигурацию
  • tasks/pushNotificationConfig/set - установить конфигурацию
  • tasks/pushNotificationConfig/delete - удалить конфигурацию
  • tasks/pushNotificationConfig/list - список всех конфигураций

agent/getAuthenticatedExtendedCard

Получает расширенную Agent Card с аутентифицированными данными пользователя.

Skills

Skills - это специализированные режимы работы агента для конкретных задач.

Список skills

GET /flows/a2a/{flow_id}/skills

Получение skill

GET /flows/a2a/{flow_id}/skills/{branch_id}

Tools в skill

GET /flows/a2a/{flow_id}/skills/{branch_id}/tools

Создание skill

POST /flows/a2a/{flow_id}/skills
Content-Type: application/json

{
  "branch_id": "my-skill",
  "name": "My Skill",
  "description": "Skill description",
  ...
}

Обновление skill

PUT /flows/a2a/{flow_id}/skills/{branch_id}
Content-Type: application/json

{
  "name": "Updated Skill",
  ...
}

Удаление skill

DELETE /flows/a2a/{flow_id}/skills/{branch_id}

Schema для создания skill

GET /flows/a2a/{flow_id}/schema

Возвращает JSON Schema для создания skill в формате ISchema.

Embed Integration

Для встроенных виджетов используется специальный endpoint с embed токеном:

POST /flows/a2a/embed/{embed_id}

Embed токены ограничивают доступ к конкретному flow, skill и origin.

Версионирование

Агенты поддерживают версионирование. Версию можно указать:

  • Query параметр: ?v=20241226120000000000
  • В metadata: {"metadata": {"version": "20241226120000000000"}}

Приоритет у query параметра.

Ошибки

JSON-RPC ошибки возвращаются в стандартном формате:

{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32000,
    "message": "Error description"
  }
}

Коды ошибок: - -32700 - Parse error (невалидный JSON) - -32600 - Invalid Request - -32601 - Method not found - -32602 - Invalid params - -32000 - Server error / Custom error

Примеры использования

Простой запрос

curl -X POST https://humanitec.ru/flows/a2a/my-agent \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "content": {
          "parts": [
            {"text": "Hello!"}
          ]
        }
      }
    }
  }'

Потоковый запрос

curl -N -X POST https://humanitec.ru/flows/a2a/my-agent \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/stream",
    "params": {
      "message": {
        "role": "user",
        "content": {
          "parts": [
            {"text": "Tell me a story"}
          ]
        }
      }
    }
  }'

Работа с конкретной веткой (branch / skill в конфиге flow)

curl -X POST https://humanitec.ru/flows/a2a/my-agent \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "content": {
          "parts": [
            {"text": "Help me with math"}
          ]
        }
      },
      "metadata": {
        "branch": "math-helper"
      }
    }
  }'

Дополнительные ресурсы

Сервис flows: конфигурации, runtime и A2A

Интерактивная документация

Info

Интерактивная документация сервиса:

Доступно полное описание всех эндпоинтов с возможностью тестирования.

Эндпоинты

➕ POST /flows/api/v1/embed/{embed_id}

Json Rpc Embed Handler

Параметры

  • embed_id (path, string) (обязательно):
  • v (query):

Ответ

  • 200: Successful Response
  • 422: Validation Error

⬇️ GET /flows/api/v1/{flow_id}

Get Agent Card

Agent Card по A2A спецификации - GET на URL агента.

Query params: v: версия агента (опционально)

Параметры

  • flow_id (path, string) (обязательно):
  • v (query):

Ответ

  • 200: Successful Response
  • 422: Validation Error

➕ POST /flows/api/v1/{flow_id}

Json Rpc Handler

Параметры

  • flow_id (path, string) (обязательно):
  • v (query):

Ответ

  • 200: Successful Response
  • 422: Validation Error

⬇️ GET /flows/api/v1/{flow_id}/.well-known/agent-card.json

Get Agent Card Well Known

Agent Card по well-known URL.

Query params: v: версия агента (опционально)

Параметры

  • flow_id (path, string) (обязательно):
  • v (query):

Ответ

  • 200: Successful Response
  • 422: Validation Error

⬇️ GET /flows/api/v1/{flow_id}/branches

List Branches

Параметры

  • flow_id (path, string) (обязательно):

Ответ

  • 200: Successful Response
  • 422: Validation Error

➕ POST /flows/api/v1/{flow_id}/branches

Create Branch

Создать новую ветку.

Параметры

  • flow_id (path, string) (обязательно):

Ответ

  • 200: Successful Response
  • 422: Validation Error

🗑️ DELETE /flows/api/v1/{flow_id}/branches/{branch_id}

Delete Branch

Удалить ветку.

Параметры

  • flow_id (path, string) (обязательно):
  • branch_id (path, string) (обязательно):

Ответ

  • 200: Successful Response
  • 422: Validation Error

⬇️ GET /flows/api/v1/{flow_id}/branches/{branch_id}

Get Branch

Параметры

  • flow_id (path, string) (обязательно):
  • branch_id (path, string) (обязательно):

Ответ

  • 200: Successful Response
  • 422: Validation Error

✏️ PUT /flows/api/v1/{flow_id}/branches/{branch_id}

Update Branch

Обновить существующую ветку.

Параметры

  • flow_id (path, string) (обязательно):
  • branch_id (path, string) (обязательно):

Ответ

  • 200: Successful Response
  • 422: Validation Error

⬇️ GET /flows/api/v1/{flow_id}/branches/{branch_id}/tools

Get Branch Tools

Получить список tools для ветки с полной информацией.

Параметры

  • flow_id (path, string) (обязательно):
  • branch_id (path, string) (обязательно):

Ответ

  • 200: Successful Response
  • 422: Validation Error

⬇️ GET /flows/api/v1/{flow_id}/schema

Get Branch Schema

Получить JSON Schema для создания ветки в формате ISchema.

Параметры

  • flow_id (path, string) (обязательно):

Ответ

  • 200: Successful Response
  • 422: Validation Error