Part 3 · ACP Protocol Embedding
The cross-language embedding path: any language that can spawn a subprocess and read/write stdio (Node / Go / Rust / Kotlin / Swift / C# / Java …) can drive Agentao as an ACP server.
Key terms in this Part
Wire-level vocabulary you'll see throughout — full glossary in Appendix G.3.
- ACP — Agent Client Protocol; stdio JSON-RPC 2.0 between host (client) and agent runtime (server) · §3.1, G.3
- NDJSON — newline-delimited JSON; one full object per line. Stdout pollution = broken framing · §3.1
- session/prompt — host-driven request that starts one turn (returns once with
stopReason) · §3.2 - session/update — server-pushed notification (no
id, no reply) — streaming text, thinking, tool events · §3.2 - session/request_permission — server-pushed request (has
id, host MUST reply) for tool approval · §3.2
Coverage
- 3.1 ACP Protocol Tour — protocol positioning, relation to MCP, the four message quadrants, v1 capability boundaries
- 3.2 Agentao as an ACP Server — launch command, full method catalog, wire traces, minimal client example
- 3.3 Host as ACP client architecture — subprocess lifecycle, three-loop I/O, permission UI bridge, TypeScript + Go references
- 3.4 Reverse: calling external ACP agents —
ACPManager.prompt_once(), delegating sub-agents,.agentao/acp.json - 3.5 Zed / IDE integration walkthrough — Zed config, wire trace, multi-workspace, upgrade path
Read by task
| What you're doing now | Shortest path |
|---|---|
| Decide whether ACP fits | 3.1 ACP Protocol Tour → 1.3 Integration Modes |
| Hand-write a minimal ACP client | 3.2 Launch command and minimal host |
| Build a production IDE / service host | 3.3 Host architecture → 3.5 IDE integration |
| Look up protocol fields / errors | Appendix C · ACP message fields and Appendix D · Error codes |
Before you start
- 1.3 Integration Modes — confirm ACP is the right fit
- 1.4 Hello Agentao · Example B — hand-fed protocol messages
Mental model
ACP is "LSP for agents" — your host spawns
agentao --acp --stdioas a subprocess and both sides speak NDJSON JSON-RPC 2.0 over the same stdio pair. Every message is visible, auditable, and replayable.