acp-agent 0.2.2

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 through ACPAgent.

import asyncio
from acp_agent import ACPAgent

async def main():
    agent = ACPAgent("opencode")

    # 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 agent.run(attach=True)
    print(f"Agent exited with code: {exit_code}")

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

The same instance can also generate a Containerfile and provide config paths:

import asyncio
from pathlib import Path
from acp_agent import ACPAgent

async def main():
    agent = ACPAgent("opencode")

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

    if config := agent.config:
        print(f"Config path: {config.config}")
        print(f"Credential path: {config.credential}")

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

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