# How the ACP Enables Direct Peer-to-Peer Agent Messaging in PrimeAgent

> Discover how the Agent Communication Protocol (ACP) facilitates direct peer-to-peer agent messaging using namespaced JSON-RPC events over the AgentSession pipeline. Learn more!

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: internals
- Published: 2026-09-05

---

**The Agent Communication Protocol (ACP) enables direct peer-to-peer messaging by exposing agent-to-agent communication as namespaced JSON-RPC events over the existing AgentSession pipeline, eliminating the need for separate transport layers.**

PrimeAgent's ACP implementation in the `PrimeIntellect-ai/prime-agent` repository provides a lightweight protocol that allows agents to exchange messages directly without intermediaries. By leveraging the core `AgentSession` infrastructure, ACP translates internal message events into a standardized JSON-RPC stream that external clients can consume. This architecture ensures that any agent connected to the same session can instantly receive peer messages through a unified interface.

## How AgentSession Powers the Core Messaging Pipeline

The foundation of peer-to-peer messaging lies in the **`AgentSession`** class located in [`packages/coding-agent/src/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/agent-session.ts). This session acts as the central hub that tracks conversation turns, goals, and inter-agent communication.

When an agent needs to send a direct message to another agent, it invokes the **`sendAgentMessage`** method with a payload containing the message content:

```typescript
await session.sendAgentMessage({ text: "Hello from Agent A!" });

```

Internally, the session emits an **`agentMessage`** event that carries the payload to all registered listeners. This event-based architecture ensures immediate propagation without polling overhead. The session maintains the canonical queue of inbound and outbound messages, making it the single source of truth for all peer-to-peer traffic within the ACP ecosystem.

## Translating Internal Events to ACP Protocol

To bridge the gap between internal session events and external ACP clients, the **`ACPEvents`** module in [`packages/coding-agent/src/modes/acp/acp-events.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/acp/acp-events.ts) handles protocol translation. This component listens for the `agentMessage` event and converts it into a structured JSON-RPC notification.

The translation process nests the message metadata under the **`acp`** namespace to prevent field collisions and ensure forward compatibility. The resulting payload structure follows this schema:

```json
{
  "acp": {
    "type": "agentMessage",
    "payload": { "text": "Hello from Agent A!" }
  }
}

```

By isolating the message content within the `acp.payload` object, the protocol can safely extend with additional metadata—such as timestamps or sender IDs—without breaking existing client implementations. The `ACPEvents` class then pushes these formatted notifications to the **ACP notification stream** (`acpUpdates`), making them available to all connected clients.

## Exposing the Interface via ACP-MCP

External connectivity is managed through **`ACPMCP`** in [`packages/coding-agent/src/modes/acp/acp-mcp.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/acp/acp-mcp.ts), which registers an MCP (Message Communication Provider) server that ACP clients use to interact with the session. This server exposes the **`sendAgentMessage`** RPC method, allowing external agents to inject messages directly into the session's message pipeline.

The registration logic found in the source file operates as follows:

```typescript
export function registerACPServer(session: AgentSession) {
  session.mcp.registerProvider("acp", {
    sendAgentMessage: (payload) => session.sendAgentMessage(payload),
  });
}

```

This design creates a bidirectional bridge: incoming RPC calls from clients route into the session, while outgoing session events stream back to clients via the `acpUpdates` notification channel. The MCP layer handles connection management and serialization, ensuring that the peer-to-peer messaging remains transport-agnostic and robust across network boundaries.

## Step-by-Step Peer-to-Peer Message Flow

Understanding the complete lifecycle of a direct message requires tracing both the outbound and inbound paths:

1. **Outbound initiation**: Agent A calls `session.sendAgentMessage({ text: "Ping" })` from either a kernel script or another agent process.

2. **Session emission**: The `AgentSession` instance emits an internal `agentMessage` event containing the payload and sender metadata.

3. **Event translation**: `ACPEvents` intercepts the emission, wraps the payload in the `acp` namespace with `type: "agentMessage"`, and formats it as a JSON-RPC notification.

4. **Stream distribution**: The formatted message enters the `acpUpdates` stream maintained by `ACPMode`, which broadcasts it to every WebSocket or HTTP client subscribed to that session ID.

5. **Client receipt**: Agent B's ACP client receives the notification, parses the `acp.type` field to identify it as a peer message, and extracts the payload for local processing.

Because the entire flow operates asynchronously over the existing session infrastructure, messages can traverse process boundaries, containers, or remote hosts without requiring additional network protocols.

## Practical Implementation Examples

### Sending Messages from a Kernel Agent

When operating within a PrimeAgent kernel, agents utilize the session API directly:

```typescript
// Inside a kernel-side agent script
async function notifyPeer(message: string) {
  await session.sendAgentMessage({ 
    role: "agent", 
    text: message 
  });
}

await notifyPeer("Task completed by kernel agent");

```

### Receiving Peer Messages in an ACP Client

External clients consuming the ACP stream handle incoming messages through event listeners:

```typescript
import { createACPClient } from "@agentclientprotocol/sdk";

const client = await createACPClient({ sessionId: "session-xyz" });

client.on("acpMessage", (msg) => {
  if (msg.acp?.type === "agentMessage") {
    console.log("Peer message received:", msg.acp.payload.text);
  }
});

```

### Registering the MCP Provider

To enable external clients to send messages back into the session, initialize the ACP server registration:

```typescript
import { registerACPServer } from "./modes/acp/acp-mcp";
import { AgentSession } from "./agent-session";

const session = new AgentSession();
registerACPServer(session);

```

## Summary

- **ACP leverages AgentSession**: The protocol reuses the existing `AgentSession` infrastructure in [`packages/coding-agent/src/agent-session.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/agent-session.ts) rather than implementing a separate transport layer.

- **Namespaced event translation**: `ACPEvents` in [`packages/coding-agent/src/modes/acp/acp-events.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/acp/acp-events.ts) converts internal `agentMessage` events into JSON-RPC notifications wrapped in an `acp` namespace with `type: "agentMessage"`.

- **MCP bridge**: `ACPMCP` located in [`packages/coding-agent/src/modes/acp/acp-mcp.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/acp/acp-mcp.ts) exposes the `sendAgentMessage` RPC method, allowing external clients to participate in peer-to-peer messaging.

- **Direct stream distribution**: Messages flow through the `acpUpdates` stream in `ACPMode`, enabling real-time delivery to all connected ACP clients without intermediaries.

- **Session-scoped isolation**: All peer-to-peer communication remains scoped to the specific `AgentSession`, ensuring that agents only receive messages from peers within their designated collaboration context.

## Frequently Asked Questions

### What is the ACP in PrimeAgent?

The **Agent Communication Protocol (ACP)** is a JSON-RPC interface implemented in the PrimeAgent repository that standardizes how agents exchange messages and coordinate tasks. According to the source code in `packages/coding-agent/src/modes/acp/`, ACP wraps the internal `AgentSession` events in a protocol that external clients can consume via WebSocket or HTTP streams.

### How does ACP differ from standard MCP?

While MCP (Message Communication Provider) provides the underlying transport infrastructure, **ACP operates as a specialized protocol layer** that sits atop MCP. As implemented in [`acp-mcp.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/acp-mcp.ts), ACP registers itself as an MCP provider named "acp" and exposes domain-specific methods like `sendAgentMessage`, whereas raw MCP handles generic connection management and serialization.

### Can agents communicate across different sessions?

No, **peer-to-peer messaging is strictly session-scoped**. The `AgentSession` class maintains isolated message queues, and the ACP implementation in [`acp-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/acp-mode.ts) creates session-specific notification streams. Agents connected to different session IDs cannot exchange messages through ACP, ensuring proper isolation between unrelated agent workflows.

### Where is the message schema defined?

The message schema is implicitly defined in [`packages/coding-agent/src/modes/acp/acp-events.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/acp/acp-events.ts) within the event translation logic. The code explicitly constructs objects with an `acp` property containing `type` and `payload` fields, where `type` is set to `"agentMessage"` for direct peer communications. This schema is tested in [`acp-events.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/acp-events.test.ts) and [`acp-kernel-features.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/acp-kernel-features.test.ts) to ensure consistent formatting across the protocol.