agent-control-center/docs/CONNECTOR_API.md

Connector API v1

Версия: 0.1.0-draft | Статус: Draft

Transport

• Протокол: WSS (WebSocket Secure) + HTTPS fallback
• Аутентификация: mTLS (клиентский сертификат) + JWT
• Формат: JSON (все payloads)
• Сжатие: per-message deflate (опционально)
• Keepalive: ping/pong каждые 30 секунд

Endpoints

1. register

Регистрация коннектора при первом подключении.

// → Request
{
  "type": "register",
  "connector_id": "uuid",
  "version": "1.0.0",
  "host": "server01.example.com",
  "adapters": ["hermes", "openclaw"]
}

// ← Response
{
  "type": "register_ack",
  "connector_id": "uuid",
  "server_time": "2026-07-20T12:00:00Z",
  "config": { ... }
}

2. heartbeat

Периодический health-check.

// → Request (каждые 30s)
{
  "type": "heartbeat",
  "connector_id": "uuid",
  "timestamp": "2026-07-20T12:00:30Z",
  "metrics": {
    "cpu_pct": 45.2,
    "memory_mb": 512,
    "active_runs": 2,
    "queued_runs": 1
  }
}

// ← Response
{ "type": "heartbeat_ack" }

3. capabilities

Объявление возможностей коннектора и его агентов.

// → Request
{
  "type": "capabilities",
  "connector_id": "uuid",
  "agents": [{
    "agent_id": "uuid",
    "runtime": "hermes",
    "model": "opencode-go/kimi-k2.7-code",
    "tools": ["terminal", "browser", "file", "delegation"],
    "max_turns": 60,
    "supports": ["streaming", "cancellation", "handoff"]
  }]
}

4. create_run

Запуск задачи на агенте.

// → Request
{
  "type": "create_run",
  "run_id": "uuid",
  "agent_id": "uuid",
  "goal": "Research GRPO papers",
  "context_bundle": {
    "objective": "...",
    "acceptance_criteria": ["..."],
    "memory_keys": ["key1", "key2"],
    "artifacts": ["artifact-id-1"]
  },
  "constraints": {
    "max_tokens": 100000,
    "timeout_seconds": 600,
    "tools": ["terminal", "browser"]
  }
}

// ← Response
{
  "type": "run_accepted",
  "run_id": "uuid",
  "status": "queued"
}

5. stream_events

Поток событий от агента (server → client push).

{
  "type": "run_event",
  "run_id": "uuid",
  "event": "tool_call",
  "timestamp": "2026-07-20T12:01:00Z",
  "payload": {
    "tool": "terminal",
    "command": "ls -la",
    "output": "total 48\n..."
  }
}

Типы событий: thinking, tool_call, tool_result, progress, warning, error, completion.

6. cancel_run

Отмена запущенной задачи.

// → Request
{ "type": "cancel_run", "run_id": "uuid" }
// ← Response
{ "type": "run_cancelled", "run_id": "uuid" }

7. handoff

Передача контекста между агентами.

// → Request
{
  "type": "handoff",
  "from_run_id": "uuid",
  "to_agent_id": "uuid",
  "bundle": {
    "objective": "...",
    "progress": "...",
    "decisions": ["..."],
    "artifacts": ["id1"],
    "open_questions": ["..."]
  }
}

8. upload_artifact / download_artifact

Загрузка/выгрузка артефактов через Object Storage.

// → upload_artifact
{
  "type": "upload_artifact",
  "run_id": "uuid",
  "name": "results.csv",
  "content_type": "text/csv",
  "size_bytes": 1024
}
// ← Response: { "upload_url": "https://...", "artifact_id": "uuid" }

// → download_artifact
{ "type": "download_artifact", "artifact_id": "uuid" }
// ← Response: { "download_url": "https://..." }

9. approve

Запрос подтверждения опасного действия.

// → Request (connector → server)
{
  "type": "approval_request",
  "run_id": "uuid",
  "action": "rm -rf /tmp/build",
  "risk_level": "high"
}

// ← Response (server → connector, after human approval)
{
  "type": "approval_granted",
  "approval_id": "uuid",
  "approved_by": "user@example.com"
}

Коды ошибок

Код	Описание
4001	Invalid request format
4002	Unknown message type
4003	Agent not found
4004	Run not found
4005	Agent busy (max concurrent runs)
4006	Quota exceeded
4007	Unauthorized action
4008	Approval denied
5001	Connector internal error
5002	Adapter error

Retry Policy

Ошибка	Стратегия
Network timeout	Exponential backoff: 1s, 2s, 4s, 8s, 16s, затем каждые 30s
5001/5002	Мгновенный retry × 3, затем fail
4005	Отложить run в очередь, retry через 60s
4006	Остановить run, уведомить operator

Таймауты

Операция	Таймаут
register	10s
heartbeat response	5s
create_run accept	30s
stream_event доставка	60s (затем reconnect)
cancel_run подтверждение	15s
upload_artifact URL	300s