agy-agent-acp

agy-agent-acp is an Agent Client Protocol (ACP) adapter server for Google Antigravity AI agents.

It enables any ACP-compatible client (such as Obsidian, Zed, VS Code, or custom clients) to communicate with Antigravity AI agents over standard I/O (JSON-RPC 2.0).

Execution model

This server drives the Antigravity agy CLI (/usr/bin/agy), which authenticates using your existing Antigravity subscription credentials via the system keyring.

It deliberately does not use the google-antigravity Python SDK. That SDK hard-requires a Gemini API key (AntigravityValidationError: A Gemini API key is required) and cannot authenticate against an Antigravity subscription, so using it would mean separate billing.

Requirements

• agy CLI on PATH (or at /usr/bin/agy), pinned to version 1.1.7. The server relies on --output-format=stream-json, which is undocumented and absent from agy --help; a CLI upgrade could remove or change it without notice.
• An authenticated Antigravity session (agy handles login; the token is read from the keyring).

Transports

AGY_ACP_TRANSPORT selects how turns are executed. Both use the same subscription credentials and emit the same ACP updates.

Value	Behaviour
connect (default)	Holds one agy language server warm and drives it over its local Connect API. Pays bootstrap once (~2.3s), then ~1.3s per turn.
cli	Spawns agy -p per turn. Pays ~3.4s of bootstrap on every turn. The fallback, and the escape hatch if the private API breaks.

Measured on identical prompts:

	cli	connect
Warm second turn	4.16s	1.28s
~900-char answer	12.87s	4.61s
Auto-approved write	6.23s	1.56s
Two concurrent sessions	4.48s	1.53s

connect also gets a genuine per-tool-call permission prompt. On cli, agy reports a tool call only once it is already running, so the server can only ask once per turn for blanket permission ("the agent may create or modify files during this turn"). On connect the call is paused before it runs, so the prompt names the actual action and path ("run write_file on /path/to/note.md"), and an out-of-workspace target is refused outright without consulting the client.

connect rides a private, undocumented API with no stability guarantee. Every failure path degrades to cli automatically, and stickily for the rest of the session, so a breaking agy upgrade costs one slow turn rather than a broken session. To force the subprocess transport:

AGY_ACP_TRANSPORT=cli agy-agent-acp

See docs/connect-transport.md for the protocol map, and tools/extract_agy_protos.py to regenerate the schemas after an agy upgrade.

Installation

pip install .

Or run directly:

python -m agy_agent_acp

Development

pip install -e '.[dev]'
pytest

Licence

Apache-2.0 — see LICENSE.

This project is not affiliated with or endorsed by Google. It talks to the agy CLI you already have installed, using your own Antigravity subscription credentials; it ships no Google code and no credentials of any kind.