0xmrpeter 362459aa74 docs(gitbook): add cross-references and internal links across all pages
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 18:03:42 +07:00

3.8 KiB

Agents

Agents are the AI processes that OpenACP connects you to. Each agent implements the Agent Client Protocol (ACP) and exposes a prompt interface. OpenACP manages spawning, communication, and lifecycle.

Browsing available agents

Use /agents to see what is installed and what is available to install:

/agents

The response has two sections:

  • Installed — agents ready to use, with a checkmark
  • Available to install — agents from the registry, with install buttons

The available list is paginated (6 per page) with Prev/Next navigation. Agents marked with a warning icon have unmet dependencies — tap the warning to see what is missing.

The registry is fetched from cdn.agentclientprotocol.com and cached locally for 24 hours.

Installing an agent

From the /agents list, tap the install button next to any agent. Or use the command directly:

/install claude
/install gemini
/install codex

Progress updates appear in-line as the installation runs — downloading, extracting, configuring. After success, a button lets you start a session with the new agent immediately.

Some agents require additional setup after installation. Setup steps appear as copyable commands, for example:

Install Claude CLI: npm install -g @anthropic-ai/claude-code
Login: claude login (opens browser)

Uninstalling an agent

Agents can be uninstalled from the CLI (see CLI Commands for the full command reference):

openacp agents uninstall <name>

This removes the agent's binary and configuration from ~/.openacp/agents/. Any existing sessions using that agent are not affected until they end.

Switching agent per session

Pass the agent name to /new to use a specific agent for a session:

/new claude
/new gemini ~/code/my-project

If you have only one agent installed, it is selected automatically.

Default agent

The default agent is used when you create a session without specifying one. Configure it in ~/.openacp/config.json:

{
  "defaultAgent": "claude"
}

Or use /settings to change it in-chat.

Agent types

Agents are distributed in four ways:

Type Description Example
npx Runs via Node.js package runner npx @anthropic-ai/claude-code
uvx Runs via Python package runner (uv) uvx goose
binary Platform-specific binary download codex
custom User-defined command and arguments Any local tool

OpenACP detects which distribution method is appropriate for your platform and handles installation automatically. If a required runtime (node, npx, uv, uvx) is missing, the agent shows as unavailable with an install hint.

Agent Distribution Notes
Claude (claude-code) npx Requires Anthropic API key or Claude login
Gemini CLI npx Requires Google AI API key
Codex CLI binary Requires OpenAI API key
Goose uvx Requires Python / uv

Use /agents for the current full list — the registry is updated independently of OpenACP releases.

Agent capabilities

Some agents declare capabilities that OpenACP uses to enable features:

  • Audio — If an agent supports native audio input, voice attachments are passed directly rather than transcribed
  • Commands — Agents can publish a list of slash commands that appear as skill shortcuts in the session topic

Capabilities are detected automatically when a session starts.

Custom agents

You can add a custom agent directly to your config without going through the registry:

{
  "agents": {
    "my-agent": {
      "command": "node",
      "args": ["/path/to/my-agent.js"],
      "workingDirectory": "~/code",
      "env": {
        "MY_API_KEY": "..."
      }
    }
  }
}

The agent must implement the ACP protocol to communicate with OpenACP.