ACP Protocol

The Agent Client Protocol (ACP) is the open standard that Braide uses to talk to agents. You don't interact with it directly — this page is an overview of what it enables, so you can understand how your prompts reach an agent and how responses come back.

How It Works

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

  1. You send a prompt — Your text, along with any attached context (files, GitHub issues, images), 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.

Authentication

An agent can advertise authentication methods during ACP initialization. When one of those methods matches a flow Braide supports, Braide offers it from the session's authentication error: agent methods use the ACP authenticate flow, while terminal methods open a dedicated login terminal. Braide never exposes credentials in the method chooser or stores them. Methods that Braide cannot run, such as an environment-variable method, remain the agent client's responsibility.

Agent-Specific Metadata

The protocol allows Braide to attach arbitrary metadata when creating a session. This is how per-agent settings like tenant tags, debug flags, or feature toggles are delivered to an agent that knows how to read them.

You configure this metadata from the cog icon on each agent card in Settings > Agents. See Managing Agents > Additional Settings for how to set it from the UI.

Real-Time Streaming

Braide streams agent events to the browser in real time, so you see tool calls, messages, and permission requests appear the moment the agent emits them — no polling or page refresh required.

The same SSE channel also carries Braide-internal events such as queue:added / queue:removed, attachments:image_added / _ready, and session:idle. These are not part of the ACP standard — they're Braide's mechanism for keeping clients in sync with the server-owned queue and attachment state. See Prompt Queue & Attachments for the full event taxonomy.