Agent Communication Protocol (ACP)
Relevant source files
The following files were used as context for generating this wiki page:
The Agent Communication Protocol (ACP) is a foundational communication layer within the Atmos project designed to facilitate interaction between the Atmos system and various external AI agents (e.g., Claude Code, Codex, Aider). It serves as the bridge that allows the Atmos backend to manage, orchestrate, and communicate with these agents in a standardized manner.
The protocol is primarily implemented within the crates/agent package and provides the necessary infrastructure for the Agent Manager to handle agent lifecycles and task execution. This system is critical for features like the Project Wiki Generation which relies on controlled agent presets to perform deep codebase research and documentation generation.
Sources: crates/agent/README.md, AGENTS.md:12, specs/tech/project-wiki.md:104-120
Architecture and Components
The ACP architecture consists of several key components working together to abstract the complexities of different AI agent CLIs.
ACP Client
The AcpClient acts as the primary interface for sending commands to an agent and receiving processed results. It leverages a runner mechanism to execute the specific shell commands associated with an agent.
The diagram above shows the relationship between the Manager, the Client, and the underlying Runner.
Sources: crates/agent/src/acp_client/client.rs, crates/agent/src/manager.rs
Agent Manager
The AgentManager is responsible for the high-level orchestration of agent sessions. It maintains a registry of active clients and handles the instantiation of agents based on predefined presets.
| Component | Responsibility |
|---|---|
AgentManager | Manages agent lifecycles and session registry. |
AcpClient | Handles protocol-level messaging and command wrapping. |
AcpRunner | Executes the physical process/command in the host environment. |
Sources: crates/agent/src/manager.rs, crates/agent/src/acp_client/runner.rs
Data Flow and Execution
The execution flow of the ACP begins when a higher-level system (like the Wiki Tab Integration) requests a task. The request is routed through the AgentManager, which prepares the environment and executes the command via the AcpClient.
The sequence above illustrates how a task requested from the UI is propagated through the ACP layers to the external agent.
Sources: specs/tech/project-wiki.md:195-225, crates/agent/src/acp_client/runner.rs
Agent Presets and Safety
To ensure security and reliability, the protocol restricts execution to controlled agent presets during initial phases. This prevents raw, unvalidated shell command execution.
Supported Agent Presets
| Agent | Command Mapping Template |
|---|---|
| Claude Code | claude {prompt} |
| Codex | codex {prompt} |
| Aider | aider --message {prompt} |
These presets use a shellQuote utility to sanitize all interpolated values (such as file paths) before they are passed to the shell, ensuring that absolute paths or sensitive characters do not cause security vulnerabilities.
Sources: specs/tech/project-wiki.md:110-120, specs/tech/project-wiki.md:133-138
Integration with Terminal Orchestration
The ACP is tightly integrated with the system's terminal grid. When an agent is spawned for a complex task, a dedicated terminal tab (e.g., named "Project Wiki") is created to show the execution in real-time.
- Session Creation: The
AgentManagerrequests a new terminal pane. - Command Dispatch: The
TerminalGridHandlesends the ACP-formatted command to the pane once the session is ready. - Execution: The user can switch to the Terminal tab to monitor the agent's progress.
Sources: specs/tech/project-wiki.md:121-132, crates/agent/src/manager.rs
Conclusion
The Agent Communication Protocol (ACP) provides a standardized, safe, and extensible way for Atmos to leverage the power of external AI agents. By abstracting agent-specific CLI details and enforcing strict preset-based execution, it enables complex automated tasks like codebase research and wiki generation while maintaining system security.