Интеграция Agent Client Protocol (ACP)¶

CodeGraph поддерживает Agent Client Protocol (ACP) для бесшовной интеграции с IDE: Zed, JetBrains IDEs, VS Code и другими ACP-совместимыми редакторами.

Обзор¶

ACP - стандартизированный протокол взаимодействия между редакторами кода и AI-агентами. CodeGraph реализует ACP для предоставления интеллектуального анализа кода прямо в вашей IDE.

Транспорты¶

CodeGraph поддерживает три механизма транспорта:

Транспорт	Сценарий использования	Endpoint
stdio	Локальный subprocess (запускается IDE)	команда `codegraph-acp`
HTTP	Удалённый REST API	`POST /api/v1/acp/rpc`
WebSocket	Real-time стриминг	`WS /api/v1/acp/ws`

Поддерживаемые методы¶

Базовые методы (обязательные)¶

Метод	Описание
`initialize`	Согласование capabilities
`authenticate`	JWT аутентификация
`session/new`	Создание новой сессии
`session/prompt`	Отправка сообщения
`session/cancel`	Отмена операции

Опциональные методы¶

Метод	Описание
`session/load`	Возобновление существующей сессии
`fs/read_text_file`	Чтение файла
`fs/write_text_file`	Запись файла
`terminal/create`	Создание терминала
`terminal/output`	Получение вывода терминала
`terminal/wait_for_exit`	Ожидание завершения команды
`terminal/kill`	Завершение команды
`terminal/release`	Освобождение ресурсов

Capabilities агента¶

CodeGraph объявляет следующие capabilities:

{
  "loadSession": true,
  "setMode": false,
  "promptCapabilities": {
    "image": false,
    "audio": false,
    "embeddedContext": true
  },
  "mcp": {
    "stdio": true,
    "http": true,
    "sse": false
  },
  "authMethods": ["bearer"]
}

Жизненный цикл сессии¶

1. Инициализация
   Client -> initialize -> Agent
   Agent -> capabilities -> Client

2. Создание сессии
   Client -> session/new {cwd} -> Agent
   Agent -> {sessionId} -> Client

3. Отправка запроса
   Client -> session/prompt {sessionId, prompt} -> Agent
   Agent -> session/update (plan) -> Client
   Agent -> session/update (tool_call) -> Client
   Agent -> session/update (agent_message_chunk) -> Client
   Agent -> {stopReason} -> Client

4. Закрытие
   Client -> session/cancel -> Agent

API Endpoints¶

HTTP транспорт¶

POST /api/v1/acp/rpc

Единый JSON-RPC endpoint для всех вызовов.

Запрос:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "clientCapabilities": {},
    "clientInfo": {"name": "my-ide", "version": "1.0"}
  }
}

Ответ:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {...},
    "agentInfo": {
      "name": "codegraph",
      "version": "0.1.0",
      "title": "CodeGraph Code Analysis Agent"
    }
  }
}

WebSocket транспорт¶

WS /api/v1/acp/ws?token=

Streaming endpoint с real-time обновлениями.

Health Check¶

GET /api/v1/acp/health

Возвращает статус агента и capabilities.

GET /api/v1/acp/info

Возвращает метаданные агента.

Session Updates¶

Во время обработки запроса CodeGraph отправляет session/update notifications:

План выполнения¶

{
  "sessionUpdate": "plan",
  "plan": {
    "entries": [
      {"id": "1", "title": "Классификация интента", "status": "completed"},
      {"id": "2", "title": "Запрос к графу кода", "status": "in_progress"},
      {"id": "3", "title": "Генерация ответа", "status": "pending"}
    ]
  }
}

Вызов инструмента¶

{
  "sessionUpdate": "tool_call",
  "toolCallId": "tc_abc123",
  "title": "Анализ безопасности",
  "kind": "search",
  "status": "in_progress"
}

Фрагмент ответа¶

{
  "sessionUpdate": "agent_message_chunk",
  "chunk": "На основе анализа..."
}

Маппинг сценариев¶

CodeGraph отображает свои сценарии на ACP tool kinds:

Сценарий	Tool Kind
Анализ безопасности	search
Code Review	read
Анализ производительности	search
Рефакторинг	edit
Документация	read
Анализ архитектуры	think

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

Для HTTP/WebSocket аутентификация опциональна, но рекомендуется:

Authorization: Bearer <jwt_token>

Аутентифицированные сессии имеют: - Персистентную историю диалогов - Пользовательские настройки - Квоты rate limit

Коды ошибок¶

Код	Значение
-32700	Ошибка парсинга
-32600	Неверный запрос
-32601	Метод не найден
-32602	Неверные параметры
-32603	Внутренняя ошибка
-32002	Агент не инициализирован

Примеры¶

Инициализация и создание сессии¶

# Инициализация
curl -X POST http://localhost:8000/api/v1/acp/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": 1,
      "clientCapabilities": {},
      "clientInfo": {"name": "curl-client"}
    }
  }'

# Создание сессии
curl -X POST http://localhost:8000/api/v1/acp/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "session/new",
    "params": {"cwd": "/path/to/project"}
  }'

Отправка запроса¶

curl -X POST http://localhost:8000/api/v1/acp/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "session/prompt",
    "params": {
      "sessionId": "acp_xxx",
      "prompt": [
        {"type": "text", "text": "Какие основные точки входа?"}
      ]
    }
  }'

Поддержка MCP серверов¶

CodeGraph может подключаться к внешним MCP серверам:

{
  "method": "session/new",
  "params": {
    "cwd": "/project",
    "mcpServers": [
      {
        "id": "github",
        "name": "GitHub MCP",
        "transport": "stdio",
        "command": "github-mcp-server"
      }
    ]
  }
}

Интеграция Agent Client Protocol (ACP)