| 1 | # Заметка: Agent Client Protocol (ACP), Cascade и Cursor |
| 2 | |
| 3 | **Статус:** рабочая заметка (терминология и ссылки; не дублирует ADR). **Архитектурное решение** по встроенному чату и Cursor CLI — **[ADR 0016](../adr/0016-agent-client-protocol-external-agent.md)**. Детали протокола — в [официальной спецификации](https://agentclientprotocol.com/). |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## 1. Терминология: не путать два «ACP» |
| 8 | |
| 9 | | Название | Суть | Где смотреть | |
| 10 | | -------- | ---- | ------------ | |
| 11 | | **Agent Client Protocol** | Связь **редактор/IDE ↔ агент**, JSON-RPC; по духу близко к LSP. Cascade в перспективе — **клиент**, внешний Cursor/другой агент — **агент** (или наоборот, если Cascade экспортирует агента). | [agentclientprotocol.com](https://agentclientprotocol.com/), [обзор транспортов](https://agentclientprotocol.com/protocol/transports.md) | |
| 12 | | **Agent Communication Protocol** (другой проект) | Межагентский REST, BeeAI / A2A и т.д. | [agentcommunicationprotocol.dev](https://agentcommunicationprotocol.dev/) — **не то же самое**, хотя аббревиатура совпадает. | |
| 13 | |
| 14 | В разговоре часто говорят «Agent Context Protocol» — у Cursor в документации и у JetBrains фигурирует именно **Agent Client Protocol** ([пост Cursor про JetBrains](https://cursor.com/blog/jetbrains-acp)). |
| 15 | |
| 16 | --- |
| 17 | |
| 18 | ## 2. Зачем это Cascade |
| 19 | |
| 20 | - **Развязка:** IDE не обязана встраивать весь UI чужого агента — достаточно ACP-транспорта (часто **stdio**: клиент поднимает процесс агента, сообщения — JSON-RPC по строкам, без мусора в stdout). |
| 21 | - **Совместимость:** агенты с ACP могут подключаться к разным клиентам; клиент с ACP — к разным агентам ([реестр](https://agentclientprotocol.com/get-started/registry.md)). |
| 22 | - **Связь с UX:** внешний агент и отдельное окно Cursor логично считать **отдельным «дисплеем»**, не смешивая с внутренним PFD/MFD — см. [`concept-pfd-mfd-cascade-v1.md`](concept-pfd-mfd-cascade-v1.md) §8. |
| 23 | |
| 24 | --- |
| 25 | |
| 26 | ## 3. Cursor как агент |
| 27 | |
| 28 | - Cursor поставляет ACP-совместимого агента для сторонних IDE (например JetBrains): установка из реестра ACP, авторизация аккаунтом Cursor ([доки Cursor](https://cursor.com/docs/cli/acp#ide-integrations)). |
| 29 | - Точная команда запуска и флаги — по актуальной документации Cursor; в этой заметке не фиксируем (могут меняться). |
| 30 | |
| 31 | --- |
| 32 | |
| 33 | ## 4. Что делать в Cascade (направления, без обязательств) |
| 34 | |
| 35 | 1. Спроектировать **роль клиента ACP**: запуск процесса агента, stdio, жизненный цикл сессий, отображение потока обновлений (diff, tool calls — см. спеку). |
| 36 | 2. Отделить **встроенный чат/MCP** от **сессии ACP** в UI (разные поверхности или явные режимы). |
| 37 | 3. Опционально: **MCP-over-ACP** ([RFD](https://agentclientprotocol.com/rfds/mcp-over-acp.md)) — если нужен единый контур с уже существующими MCP-инструментами. |
| 38 | |
| 39 | --- |
| 40 | |
| 41 | ## 5. Локальный smoke (репозиторий) |
| 42 | |
| 43 | - [`samples/AcpSmoke/README.md`](../../samples/AcpSmoke/README.md) — Python-клиент (`agent-client-protocol` на PyPI) + эталонный `echo_agent` из upstream. |
| 44 | - [`samples/AcpSmokeDotnet/README.md`](../../samples/AcpSmokeDotnet/README.md) — тот же сценарий клиентом на **.NET** (NuGet [`AgentClientProtocol`](https://www.nuget.org/packages/AgentClientProtocol), неофициальный SDK). |
| 45 | |
| 46 | Проверяется, что цепочка `initialize` → `new_session` → `prompt` работает на машине разработчика. Это **не** замена интеграционного теста с Cursor. |
| 47 | |
| 48 | --- |
| 49 | |
| 50 | ## 6. Полезные ссылки |
| 51 | |
| 52 | - [Introduction](https://agentclientprotocol.com/get-started/introduction.md) |
| 53 | - [Initialization](https://agentclientprotocol.com/protocol/initialization.md), [Prompt turn](https://agentclientprotocol.com/protocol/prompt-turn.md) |
| 54 | - [Python SDK](https://agentclientprotocol.com/libraries/python.md), [TypeScript SDK](https://agentclientprotocol.com/libraries/typescript.md); для C# в smoke используется community-пакет на NuGet (см. §5). |
| 55 | - Список [клиентов и редакторов](https://agentclientprotocol.com/get-started/clients.md) |
| 56 | |