acp-agent 0.1.0

A CLI tool to browse, search, and run ACP agents

ACP Agent CLI & SDK 🚀

This project provides a friendly and intuitive CLI and SDK for the ACP Registry, enabling developers to quickly browse, search, run, and containerize ACP (Agent Client Protocol) agents.

Motivation 💡

The official ACP Registry provides an extensive list of agents. This project simplifies discovery and integration through three core pillars:

• Interactive Discovery: Browse and fuzzy-search the entire registry directly from your terminal.
• Seamless Execution: Run any agent locally with automatic environment setup, or integrate them into Python apps via the async SDK.
• Production Deployment: Automatically generate optimized Containerfiles to run agents in isolated environments or CI/CD pipelines.

Usage 🚀

There are three ways to use acp-agent:

1. CLI Usage

We recommend using uv to manage and run this project.

# List all agents
uvx acp-agent list

# Search for agents
uvx acp-agent search opencode

# Run an agent locally
uvx acp-agent run opencode

# Run with a specific working directory, environment variables, and extra arguments
# Any arguments after the options are passed directly to the agent
uvx acp-agent run opencode --cwd ./my-project -e DEBUG=true -- --help

Example Search Output

Search Results for 'opencode'
┏━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ID       ┃ Name     ┃ Description                  ┃
┡━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ opencode │ OpenCode │ The open source coding agent │
└──────────┴──────────┴──────────────────────────────┘

2. SDK Usage

You can integrate acp-agent into your Python projects.

import asyncio
from acp_agent import run_local

async def main():
    # Run an agent and attach to its output (stdout/stderr)
    # This will automatically handle downloading and environment setup
    # returns the exit code of the agent
    exit_code = await run_local("opencode", attach=True)
    print(f"Agent exited with code: {exit_code}")

if __name__ == "__main__":
    asyncio.run(main())

3. Container Usage

Generate a Containerfile to run an agent inside ANY container you defined.

import asyncio
from pathlib import Path
from acp_agent import format_containerfile

async def main():
    # Generate Containerfile content for 'opencode'
    # This will inject the agent installation and CMD into your base image
    content = await format_containerfile(
        agent_id="opencode",
        containerfile="FROM python:3.12-slim"
    )
    Path("Dockerfile").write_text(content)

    if __name__ == "__main__":
        asyncio.run(main())

Managing Agent Configuration

For many agents, maintaining configuration and authentication state is crucial. The SDK provides a get_config function that returns the default host paths for an agent's configuration and credentials:

from acp_agent import get_config

if config := get_config("opencode"):
    print(f"Config path: {config.config}") # ~/.config/opencode
    print(f"Credential path: {config.credential}") # ~/.local/share/opencode/auth.json

After starting your container, you can manually copy these files from your host to the container's expected locations (e.g., via docker cp) to fully replicate your host-side environment and authentication state within the isolated container.

License

MIT License