ACP Protocol

The Agent Client Protocol (ACP) is the communication standard that Braide uses to interact with agents. It defines how clients send prompts and receive structured responses.

How It Works

ACP follows a request-response pattern with real-time streaming:

  1. Client sends a prompt — Your text, along with any attached context (files, GitHub issues), is sent to the agent
  2. Agent processes — The agent reads the prompt, decides what actions to take, and begins responding
  3. Events stream back — The agent's response comes as a stream of typed events (messages, tool calls, permission requests)
  4. Session maintains state — The full conversation history is preserved for context in subsequent prompts

Event Types

The protocol defines several event types that appear in your session:

  • Chat events — Text messages from the agent, rendered as markdown
  • Tool use events — The agent calling tools (file reads, code searches, command execution)
  • Tool result events — The output of tool executions
  • Permission events — Requests for your approval before executing certain actions
  • Config events — Updates to session configuration options

Sessions and Agents

Each ACP session is bound to a single agent. The session maintains conversation history so the agent has context from previous exchanges. Multiple sessions can run concurrently with different agents.

Extensibility via _meta

ACP reserves an optional _meta field on every request for out-of-band metadata. It is an object with arbitrary keys — the protocol itself makes no assumptions about the contents, and agents that don't recognise a key must ignore it.

Braide surfaces this as a per-agent JSON blob, configurable from the cog icon on each agent card in Settings > Agents. When set, the blob is attached as _meta to the newSession request — whenever a session is created, reset, probed for config options, or recreated after a failed loadSession. newSession is the natural boundary for session-scoped agent configuration: the agent receives the meta once per session at creation and can propagate it to any internal state it associates with that session.

The meta is not attached to initialize (which is tied to the agent process rather than a session) or to prompt (where repeating it every turn would be redundant). Prompts still carry their own _meta for session-scoped configOptions — those are unrelated to the per-agent blob.

Typical uses are tenant identifiers, debug flags, tracing IDs, or feature toggles that the agent reads but the protocol otherwise has no vocabulary for. See Managing Agents > Additional Settings for how to set the meta from the UI.

Server-Sent Events (SSE)

Braide uses SSE for real-time streaming. When you send a prompt, the app opens an SSE connection to receive events as they're generated by the agent. This provides a smooth, real-time experience without polling.