ACP agents as providers
Created: 2026-10-30. Last updated: 2026-11-04.
pi can run an external Agent Client Protocol (ACP) agent, such as Kiro CLI or Amp, and show its work in the pi transcript. This page has the acceptance criteria, the design decision, the research with sources, and the user guide. For pi as an ACP server (pi --mode acp), see acp.md.
Acceptance criteria
-
Each enabled entry of
acpAgentsis a provider<id>-acp(or<id>when the ID ends in-acp) in/model, with the APIacp. Selecting the provider opens its ACP session without sending a prompt, so its advertised models are available before the first turn. Thedefaultmodel keeps the agent’s own model choice. -
A request starts the agent command over stdio in the session working directory, sends
initialize(protocol 1,fsandterminalclient capabilities,auth.terminal), thensession/newwith the MCP servers of criterion 13. A later request of the same pi session reuses the ACP session. After a restart of pi,session/loadresumes the ACP session when the agent advertisesloadSession. Otherwise pi sends the earlier conversation as a context resource. -
session/promptgets the user text, images (whenpromptCapabilities.image), and aresource_linkfor each file that the user message names with@. -
session/updategoes into one assistant message:- Message chunks as text.
- Thought chunks as thinking.
- Tool calls as text lines with the kind, title, and status, with diffs as fenced
diffblocks and terminal output when the call ends. - Plans as a checklist.
usage_updateas context use.
Every stream ends with
DoneorErrorthroughMessageBuilder. A compacted transcript keeps the ACP session: pi finds the last reply of the session by its timestamp and sends only what comes after it. -
session/request_permissionshows a dialog with the options of the agent (allow once, allow always, reject once, reject always). Without a UI, pi rejects. A cancel answers open requests withcancelled. -
fs/read_text_file,fs/write_text_file, andterminal/create,terminal/output,terminal/wait_for_exit,terminal/kill,terminal/releasework for paths inside the session working directory. Paths outside it fail. -
Escape sends
session/cancel. The stream ends with stop reasonaborted. -
Modes (
modesor aconfigOptionsselector of categorymode) are selectable with/acp modebefore a prompt. Models (configOptionscategorymodel, ormodels.availableModelsof older agents) are selectable in/model./thinkinguses the agent’s advertised effort choices: pi level names match option IDs or labels without regard to case, and pi sends the exact advertised option ID. Unsupported levels are omitted. Options without categories use known model, permission, and effort IDs, including Kiro’seffortLevel. -
/acpopens a browser with two tabs. Installed lists everyacpAgentsentry of the global and the project settings. A global entry that a project entry replaces is marked and can be edited, enabled, disabled, or removed. The other entries can also be logged in to, set as default, and moved to the other settings file. Add custom agent creates an entry; Edit changes any installed entry while keeping its ID, scope, and install metadata. Registry lists the ACP registry and the built-in entries for Kiro and Amp. Install asks for the global or the project settings. -
Install uses the distribution of the registry entry:
npxanduvxstore the command;binarydownloads the archive for the platform, checks the SHA-256 when the entry has one, and unpacks it under~/.pi/agent/acp/agents/<id>/<version>/. -
Log in shows the
authMethodsof the agent. A terminal method (type: "terminal"or_meta["terminal-auth"]) runs in the terminal while the TUI is stopped. Other methods go toauthenticate. -
Tests use a fake ACP agent and a local mock HTTP server. They cover initialize, prompt streaming, tool call updates, permission requests, fs read and write, cancel, registry fetch, install, and criteria 13 to 17. No test uses the network, a real agent, or a key.
-
session/newandsession/loadget the enabled, not hidden servers ofmcp.json, plus.pi/mcp.jsonin a trusted project:- A stdio server always goes to the agent, with a bare command resolved on PATH.
- An
httporsseserver with its own headers goes to the agent only whenagentCapabilities.mcpCapabilitieshas that transport. - An HTTP server whose login pi holds (OAuth, or
auth.provider) goes throughpi-mcp, a loopback MCP server with a bearer token. The agent lists its tools (in pages of 64 withnextCursor), and pi calls them over its own MCP connection.pi-mcpneedsmcpCapabilities.http. - When the agent cannot take a server, the reply starts with a line that names it.
-
available_commands_updategives the slash commands of the agent. pi keeps them per provider instate.json, and the editor completes them while an ACP model is selected./<name> <input>goes to the agent as prompt text. A name that a pi command uses completes as/acp:<name>, and the provider sends/<name>. -
The
sizeofusage_updateis the context window of the pi model, per provider and model ID. Before an agent sends one, the window andmaxTokensare 0, which means unknown: threshold compaction does not run, and the footer and/contextshow?orunknown. The model input has images unless the agent reportedpromptCapabilities.image: false. -
A request that is not a turn of a live pi session, such as a compaction or branch summary, runs in a new ACP process with a new session. That session gets the system prompt of the request, no MCP servers, and no
session/load. pi rejects its file writes and terminals, cancels its permission requests, and records nothing instate.json. After the reply or a cancel, pi stops the process group of the agent, which includes the processes it started, and waits for the agent to exit. pi stops the group the same way when it drops any agent process. -
/undocovers ACP turns. Before a turn, pi keeps the files of the working directory that.gitignoredoes not exclude (hidden files included,.gitnot). It keeps up to 4 MiB a file and 256 MiB in all. After the turn, pi compares the content and records new, changed, and deleted files.fs/write_text_fileand the files named byedit,delete, andmovetool calls are recorded as reported changes. Other differences are marked as not reported, and/undolists them and asks before restoring them.
Decision: a pi-ai provider
pi runs an ACP agent as a pi-ai provider with the API acp (crates/pi-ai/src/providers/acp/). pi does not add a second session backend.
Reasons:
- The agent runs its own tools, so the pi agent loop only streams. The provider is the smallest surface that does this, and
pi-ai::providers::antigravity_acpalready is an ACP client provider. - The model selector, session files, Escape, retries, and the
MessageBuilderrule work without changes. - A session backend would replace
AgentSessionin the interactive, print, and RPC modes.
Consequences:
- pi does not send its system prompt or its tools to the agent. The agent uses its own.
- The tool calls of the agent are text in the assistant message. A
ToolCallblock would make the pi loop run a pi tool with that name. - The UI work (permission dialogs, the plan widget, the session map for
session/load) goes through theAcpHosthook.pi-coding-agentsets it (src/acp_client/host.rs).
Research
All sources read on 2026-10-30.
Protocol
Source: schema/v1/schema.json, schema release 1.28.0.
- The protocol version is
1. The draftschema/v2removes thefsandterminalmethods. - Auth methods: an agent method
{id, name, description}, ortype: "terminal"withargsandenv. The client runs the agent command with these arguments in a terminal and does not sendauthenticatefor it. Agents show terminal methods only when the client sendsclientCapabilities.auth.terminal: true. amp-acp uses the older_meta["terminal-auth"] = {command, args, label}. - The unstable
modelsfield andsession/set_modelwere removed on 2026-06-01 (commit822ef53cd, #1325). Models come inconfigOptionswithcategory: "model". pi still readsmodels.availableModelsand sendssession/set_modelto agents that do not sendconfigOptions. configOptionscategories:mode,model,model_config,thought_level,_custom.session/set_config_optiontakes{sessionId, configId, value}.- Stop reasons:
end_turn,max_tokens,max_turn_requests,refusal,cancelled. - Read on 2026-10-31 from the same schema:
McpServeris stdio (name,commandas an absolute path,args,envas{name, value}pairs), which every agent must support, ortype: "http"andtype: "sse"(name,url,headers), which an agent takes only withagentCapabilities.mcpCapabilities.httpor.sse. AvailableCommandsUpdatehasavailableCommandsof{name, description, input?: {hint}}. A client runs a command by sending/<name> <input>as prompt text.UsageUpdatehasused(tokens in context) andsize(the context window), both required, and an optional cumulativecost.Diffhaspath,newText, andoldText(nullfor a new file).ToolCallLocationhaspathand an optionalline. Both are hints for the client: they do not have to name every file a tool changes.
Registry
Source: agentclientprotocol/registry, FORMAT.md and AUTHENTICATION.md.
- Index:
https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json, shape{version, agents[], extensions[]}. It listed 43 agents. - Entry:
id,name,version,description,repository,website,authors,license,icon, anddistributionwith one or more of:npx: {package, args, env}, run asnpx <package> <args>;uvx: {package, args}, run asuvx <package> <args>;binary: {<platform>: {archive, sha256, cmd, args, env}}. The platforms aredarwin-aarch64,darwin-x86_64,linux-aarch64,linux-x86_64,windows-aarch64,windows-x86_64. The archive is.zip,.tar.gz,.tgz,.tar.bz2,.tbz2, or a raw binary.cmdis relative to the unpacked archive.
- Agents in the registry support the agent or the terminal auth method.
Kiro
Sources: Kiro CLI V3, ACP migration for V3, Kiro CLI ACP, authentication, registry PR #561.
- “Kiro V3” is Kiro CLI V3, which uses the agent harness of Kiro IDE. It runs next to Kiro CLI 2.x.
- Install:
curl -fsSL https://cli.kiro.dev/install | bash. The program iskiro-cli. - ACP:
kiro-cli acp --agent-engine=v3(V3) orkiro-cli acp(2.x). V3 rejects--agent,--model,--effort,--trust-all-tools, and--trust-tools. - Login:
kiro-cli login(browser or device code).KIRO_API_KEYworks in non-interactive mode. - V3 sends models and the effort level in
configOptions(model,effortLevel) and modes withsession/set_mode. 2.x supportssession/set_model. - The registry does not list Kiro: PR #561 is open. pi has a built-in entry.
Amp
Sources: amp-acp src/server.ts, the registry entry amp-acp, and the Amp manual.
- Adapter: npm
amp-acp0.10.0 (community), run withnpx -y amp-acp. The registry entryamp-acpships binaries.AMP_CLI_PATHselects theampprogram. - The Amp CLI has no ACP mode of its own.
- Login:
amp login, orAMP_API_KEY. The adapter offers the auth methodsetupwith_meta["terminal-auth"](--setup). - Amp sends
configOptions:execution-environmentandpermission(categorymode) andamp-mode(categorymodel, valueslow,medium,high,ultra).
Use an ACP agent
- Run
/acp. The Registry tab lists the agents of the registry, plus Kiro CLI (V3) and Amp. - Select an agent and press Enter. Then choose the global settings (every project) or the project settings (this project only). A project entry replaces a global entry with the same ID.
- If the agent needs a login, select the agent in the Installed tab and choose Log in. For Kiro:
- If
kiro-cliis not on PATH or in~/.local/bin, Install offers to run the official installer (curl -fsSL https://cli.kiro.dev/install | bash) in the terminal after you confirm. - Then log in with
kiro-cli loginor the Log in action. Kiro CLI exits before ACP starts when it has no login, so Log in runskiro-cli loginin the terminal. - The installer and an authenticated Kiro session were not run in the tests.
- If
- Select the model
<provider>/defaultwith/model, or choose Set as default. pi opens that provider’s session, and/modelthen lists its advertised models without a prompt. A selected ACP provider also opens at startup. Other providers are not started just to populate the list. - Run
/acp modeto change an advertised permission mode or another agent setting. Run/thinkingto choose a supported thinking level. These controls open the session when needed. A failed change leaves the local selection unchanged.
The agent edits files and runs commands with its own tools. pi shows its permission requests as dialogs. In print mode (pi -p), pi rejects the requests.
Add a custom agent
On the Installed tab of /acp, select Add custom agent or press Ctrl+N. The form has these fields:
| Field | Value |
|---|---|
| Name | Required. |
| ID | A slug of the name by default. You can edit it before you save. |
| Command | Required. An executable name or path. |
| Arguments | Shell-style words with quotes and backslash escapes. |
| Login command | Optional. Shell-style words, as in Arguments. |
| Description | Optional. |
| Environment | KEY=VALUE pairs, one per line. |
| Scope | Global or project. |
| Enabled | On by default. |
- The ID must use lowercase letters, digits, and dashes, and be unique across global and project settings. The provider is
<id>-acp, or<id>when the ID already ends in-acp. - In Arguments,
acp --agent-engine=v3gives two arguments. - In Environment, Enter adds a line, and multiline paste works. Details mask the values.
| Key | Action |
|---|---|
| Tab, Shift+Tab | Change fields. |
| Enter or Space | Change the scope or the enabled state. |
| Ctrl+S or Save | Save and update the provider list. After an error, the form keeps the input. |
| Escape | Cancel. |
Edit opens the same form with ID and scope read-only. It preserves the source, version, install directory, and unknown fields. To change the scope, use the move action.
Settings
acpAgents is an array in the global or the project settings.json. A project entry replaces a global entry with the same id.
{
"acpAgents": [
{
"id": "kiro",
"name": "Kiro CLI (V3)",
"command": "kiro-cli",
"args": ["acp", "--agent-engine=v3"],
"env": {},
"enabled": true,
"source": "builtin"
}
]
}
| Field | Meaning |
|---|---|
id |
The agent ID. The provider ID is <id>-acp, or <id> when the ID ends in -acp. |
name |
The name in /model, /acp, and dialogs. |
command, args, env |
The command that starts the agent in ACP mode over stdio. |
enabled |
false removes the provider from /model and keeps the entry. |
loginCommand |
The login program for agents that exit before ACP starts without a login, for example ["kiro-cli", "login"]. Log in runs it when the agent does not start. |
description |
Optional description shown in /acp; editable in the form. |
source |
registry, builtin, or custom. Entries added with the form use custom; editing preserves the source. |
version, installDir |
Set by the install. installDir is removed with the entry. |
The acpRegistryUrl setting replaces the registry URL, for example with a mirror. PI_ACP_REGISTRY_URL replaces both.
pi keeps these files in ~/.pi/agent/acp/:
agents/<id>/<version>/: unpacked binary distributions.state.json: the ACP session ID of each pi session (forsession/load), and per agent the models, slash commands, context windows, and image support it advertised.
Limits
/undocannot tell who made a change during an ACP turn. A change that you or another program make in the working directory during the turn is a candidate too. Only changes the agent reported are attributed to it.- pi tracks only the working directory. pi’s
fsandterminalmethods refuse paths outside it, but the agent’s own tools are not confined. Changes outside the working directory are not tracked or undone. - A file that
.gitignoreexcludes is tracked only when the agent names it infs/write_text_fileor in the locations or diff of anedit,delete, ormovetool call before the change. - A file larger than 4 MiB, or a file beyond the 256 MiB total, is found by its size and time only.
/undolists it as not restorable, with the reason. /undorestores a file only while it holds what the turn left. It leaves a file that changed after the turn, and it does not restore a deleted file that came back.- The stdio
cwdof anmcp.jsonserver is not sent: ACP has no field for it. - pi runs the tool calls that come through
pi-mcpwithout its own permission dialog. The agent asks for permission for its MCP tools in its own way. pi-mcplists the tools that are connected when the agent asks. pi updates the list at each turn, but an agent that lists tools only once at the start of a session does not see servers that connect later.- Process group cleanup is for Unix. On Windows, pi stops only the agent process.
- pi compacts its own transcript. The agent keeps its context and compacts it itself.