Agents

An agent is an AI process that runs locally on your machine and responds to prompts via the Agent Client Protocol. Braide manages the full lifecycle of agents — from downloading to starting, monitoring, and stopping.

Agent States

Agents can be in one of several states:

State	Description
Off	Agent is not enabled
Downloading	Agent package is being downloaded from the registry
Extracting	Downloaded package is being extracted
Starting	Agent process is launching
Running	Agent is ready to accept sessions
Error	Agent failed to start — check error message for details

Managing Agents

Open Settings (gear icon in the navbar) and go to the Agents section to:

• Enable/disable agents — Toggle agents on or off. Enabling an agent downloads it (if needed) and starts it automatically. Disabling an agent stops it and prevents auto-start.
• View status — See the current state of each agent with color-coded indicators.
• View errors — If an agent fails, the error message is displayed inline.

Agent Distribution

Agents are distributed through registries in several ways:

• npx — Node.js package executed via npx. Requires Node.js (and npm) to be installed on your system.
• uvx — Python package executed via uvx. Requires uv to be installed on your system (see uv installation).
• binary — Pre-compiled binary downloaded directly from the registry. No additional runtime is required.

The distribution method is shown next to each agent in the settings panel. If you enable an agent that uses npx or uvx, make sure the corresponding tool is available in your PATH.

Agent Meta

Each enabled agent has its own JSON metadata blob that Braide attaches as _meta to the newSession request when a session is created on that agent. This is an extensibility point defined by the protocol and is useful for tenant tags, debug flags, or routing hints an agent understands. The meta is edited from the cog icon on the agent card in Settings > Agents; changes are staged until you click Apply, which restarts the agent so active sessions aren't interrupted. See Managing Agents > Additional Settings.

Personas

Rather than selecting agents directly, you can define personas — named roles that bundle a preferred agent with custom instructions, MCP servers, and per-agent config options. By default — with no personas defined — sessions use agent selection mode and the prompt toolbar shows an agent dropdown. Once a project has one or more personas, the toolbar switches to a persona selector; the selector also includes a No persona option so you can skip personas for an individual session and fall back to direct agent selection. See the Personas guide for details.

Registries

Agents are discovered through registries — servers that list available agents. Braide comes with a default registry. You can add custom registries in the ACP Registry section of Settings.

Only one registry can be active at a time. Switching registries updates the available agent list.