| name | pi-acp-agents |
| description | Use when working with the pi-acp-agents package, its ACP tool surface, ACP agent session lifecycle, or ACP configuration and runtime behavior inside pi. |
pi-acp-agents
ACP agent client for pi — spawn and control ACP-compatible agents from within pi.
What it does
This pi extension registers tools that let the pi LLM communicate with external ACP (Agent Client Protocol) compatible agents like Gemini CLI, Claude, or any custom command that speaks ACP over stdio JSON-RPC.
Tools
| Tool | Description |
|---|
acp_prompt | Send a prompt to an ACP agent, get the text response |
acp_status | Show configured agents, active sessions, circuit breaker state |
acp_session_new | Create a new isolated session with an agent |
acp_session_load | Load an existing session by ID |
acp_session_set_model | Change the model for an active session |
acp_session_set_mode | Change the mode (thinking level) for an active session |
acp_cancel | Cancel an ongoing prompt |
acp_delegate | Delegate a task (short-lived session, auto-disposed) |
acp_broadcast | Send same prompt to multiple agents in parallel |
acp_compare | Get responses from multiple agents and compare them |
Configuration
Config file: ~/.pi/acp-agents/config.json
{
"agent_servers": {
"gemini": {
"command": "gemini",
"args": ["--acp"],
"default_model": "gemini-2.5-pro"
}
},
"defaultAgent": "gemini"
}
Fields
| Field | Default | Description |
|---|
agent_servers | { gemini: {...} } | Map of agent name → config |
defaultAgent | "gemini" | Agent used when not specified |
staleTimeoutMs | 3600000 (1 hour) | Session auto-close timeout for stalled-no-response and completed-idle |
healthCheckIntervalMs | 30000 (30s) | Background health polling interval |
circuitBreakerMaxFailures | 3 | Consecutive failures before circuit opens |
circuitBreakerResetMs | 60000 (60s) | Time before circuit half-opens |
stallTimeoutMs | 3600000 (1 hour) | Per-operation timeout |
Per-agent config
| Field | Required | Description |
|---|
command | yes | Executable to spawn |
args | no | Arguments (e.g., ["--acp"]) |
env | no | Extra environment variables |
cwd | no | Working directory override |
default_model | no | Default model ID |
Resilience
- Circuit breaker: Opens after N consecutive failures, auto-recovers after timeout
- Stall timeout: Prompts that receive no activity are auto-cancelled
- Health polling: Background monitor enforces separate
lastResponseAt and completedAt 1-hour auto-close policies
- Busy mutex: Prevents concurrent prompts on same session
- Process safeguards: SIGTERM → SIGKILL escalation, EPIPE error handlers
- Non-blocking: All tool errors return as tool error results, never throw
Architecture
Adapter pattern:
AcpAgentAdapter (abstract base)
├── GeminiAcpAdapter — gemini --acp defaults
└── CustomAcpAdapter — any user-defined ACP command
Client layer:
AcpClient — wraps @agentclientprotocol/sdk ClientSideConnection
Resilience:
AcpCircuitBreaker — wraps all tool execute calls
HealthMonitor — background session health polling
Coordination:
AgentCoordinator — multi-agent delegate/broadcast/compare
Logs
Central logs: ~/.pi/acp-agents/logs/
main.log — general logsession-{id}/trace.jsonl — per-session JSON-RPC traces
Prerequisites
- Gemini CLI installed and authenticated:
gemini --version + gemini (login)
- ACP TypeScript SDK: bundled as dependency
References
