agentabi
Unified interface layer for agentic coding CLIs.
One interface. Any coding agent.
What is agentabi?
agentabi provides a stable, unified interface (an "ABI") for interacting with different agentic coding CLIs. Write your integration once, swap agents with a config change.
Supported Agents
| Agent | Provider | Status |
|---|---|---|
| Claude Code | Anthropic | Implemented |
| Codex | OpenAI | Implemented |
| Antigravity (agy) | Implemented | |
| OpenCode | Community | Implemented (V2 HTTP/SSE + V1 fallback) |
| Pi | Community | Implemented |
| Deprecated (use agy) |
Installation
pip install agentabi
Note: You also need at least one agent CLI installed:
claude,codex,agy,opencode, orpi.
Optional SDK dependencies
pip install agentabi[claude] # Claude Agent SDK
pip install agentabi[codex] # Codex SDK
Quick Start
import asyncio
from agentabi import Session
async def main():
session = Session(agent="claude_code")
result = await session.run(prompt="What is 2+2?")
print(result["result_text"])
asyncio.run(main())
One endpoint setting for every agent
Point any supported CLI at a custom model endpoint through one mapping. Each transport translates it into its own mechanism, so caller code does not change between agents:
session = Session(
agent="codex",
settings={
"base_url": "https://llm.example.com/v1",
"api_key_env": "LLM_API_KEY",
"model_provider": "gateway",
},
)
settings also takes headers, env, args, and a native block for
CLI-specific options. Keys travel in the child environment, never in argv.
An unsupported field raises UnsupportedSettingsError unless
on_unsupported="ignore". See the
settings guide.
Claude subscription quota (PTY transport)
By default Claude Code runs as claude -p. Anthropic classifies that
entrypoint as sdk-cli and counts it at roughly twice the interactive
cli mode's allowance. To drive the real interactive TUI instead:
session = Session(agent="claude_code", prefer="pty")
The PTY provider is opt-in. It uses a POSIX PTY on Linux and macOS and the
Windows pseudoconsole (ConPTY) on Windows; both come from the vendored
ptyx module, so there is no extra dependency. It waits for the TUI
prompt, pastes the message, and tails the session transcript, so it emits
whole messages rather than token deltas. If Claude Code asks to trust the
folder or is not signed in, it returns a clear error instead of changing
your configuration.
The ACP gateway takes the same choice:
agentabi acp --agent claude --prefer pty
OpenCode V2 transport
OpenCode 1.19.0 and later expose a second API: opencode serve with HTTP
commands and a server-sent event stream. agentabi uses it by default and
keeps the opencode run --format json V1 subprocess as a fallback.
session = Session(agent="opencode")
result = await session.run(prompt="Fix the failing test")
- Selection. V2 is used when the
opencodeCLI is at least 1.19.0 or a server URL is configured. Otherwise the V1 provider runs. Force either transport withAGENTABI_OPENCODE_TRANSPORT=v1|v2, or per task withagent_extensions={"opencode": {"transport": "v2"}}. - Server. Without a URL, the provider starts
opencode serveon a free localhost port and reuses that process for later calls. SetOPENCODE_BASE_URL(oragent_extensions={"opencode": {"base_url": ...}}) to use an existingopencode serve, including a remote one withhttp://user:pass@host:port. A configured URL is authoritative: if that server does not answer the V2 API the task fails instead of silently running V1. - Sessions.
session_idwithresume=Truereuses the server session, so multi-turn conversations keep their context. - Permissions. With
permissions={"level": "full_auto"}requests are approved automatically;accept_editsapproves each request once. Any other level fails the turn with a clear error, because the streaming API cannot prompt. Interactive questions are rejected and fail the turn. - Limits. There is no system-prompt hook.
usageandcost_usdare reported per step; a turn with tool calls emits one pair per step. The turn ends atsession.next.step.endedbecause V2 servers do not emitsession.idle.
agentabi acp --agent opencode is unaffected; it keeps using the native ACP
pass-through.
Long-lived peers
Session.run runs one task. A peer keeps a Claude Code, Codex,
OpenCode, Pi, or Antigravity (agy) process alive between turns, so a
coordinator can send follow-up work, steer a running turn, or interrupt
it and keep the conversation:
from agentabi.peers import PeerBroker
async with PeerBroker() as broker:
peer = await broker.spawn("reviewer", cwd="/repo", prompt="Review the diff")
# backend="codex", "opencode", "pi", or "agy" for the other CLIs
# agy cannot steer: a busy send is refused, interrupt is best effort
await peer.send("Also check the tests") # new turn, or steer if busy
turn = await peer.wait(timeout=300)
print(turn.status, turn.text)
peerctl drives the same runtime across processes: spawn, send,
steer, interrupt, wait, inbox, plus attach for a session
another process started and recover after the daemon stops. See the
peers guide.
ACP gateway
Expose agentabi as a single ACP endpoint. The gateway speaks ACP to the client and delegates to each agent's native interface:
pip install agentabi
agentabi acp --agent opencode
The ACP transport is vendored from zerodep (acp + jsonrpc), so no external ACP SDK is required. Current backends: opencode (native ACP); codex-app-server (JSON-RPC to codex app-server); and agy, claude, codex, pi (via the agentabi IR stream). More backends are tracked in the ACP gateway epic.
Any CLI that ships an ACP server can be used without an agentabi provider:
agentabi acp --agent acp --acp-command "npx -y @agentclientprotocol/claude-agent-acp"
The gateway speaks ACP to that process and forwards its session/update payloads unchanged.
Permissions
session/new returns a permission_mode config option (ask, deny,
allow_all). session/set_config_option changes it for the session.
The Claude backend (agentabi acp --agent claude) and ACP pass-through
backends (opencode, --agent acp) can ask: a request reaches the client as
session/request_permission and the answer is written back. Backends without a
permission channel (codex, agy) still get deny and allow_all, which the
gateway enforces with the provider's own flags (codex runs read-only with no
approvals; agy drops its skip-permissions flag). pi has no such flags, so it
gets no option. The gateway never turns a missing channel into an allow.
Use --permission-timeout SECONDS to bound the wait (default 0 waits
forever) and --permission-policy ask|deny|allow_all to choose the initial
policy.
Router mode
One gateway process can serve several agents. Enable more than one with
--router and repeated --agent:
agentabi acp --router --agent claude --agent opencode
The client picks an agent per session with _meta.agent in session/new:
{"jsonrpc": "2.0", "id": 1, "method": "session/new",
"params": {"cwd": "/work", "_meta": {"agent": "opencode"}}}
The first enabled agent is the default when _meta.agent is absent. An
unknown name fails with -32602 (invalid params) and lists the enabled
agents. The selected agent is reported in the session config as an agent
option. That option is informational: ACP config options are returned by
session/new and set afterwards, so they cannot choose an agent at creation
time. Changing it with session/set_config_option returns an error; create a
new session to switch agents.
Capability policy. initialize advertises the intersection of what every
enabled and reachable backend honours, further limited by what the gateway
itself implements: session/load, session/list, session/resume, and
session/delete are never advertised, and authentication is not proxied.
A backend that cannot start is logged and left out of the intersection;
selecting it later returns a clear error. Per-agent capabilities are not
advertised because the agent is chosen after initialize. The negotiated
protocol version is the lowest version any reachable backend reports; IR
backends are told to emit that version, and native ACP backends are
restarted so their downstream negotiates it too.
Permission policy. Deny by default. Router mode fails closed: an inner
backend uses its own session id, which the client does not know, so the router
never claims a permission round trip and answers a downstream
session/request_permission with an explicit cancelled. Run one gateway per
agent (agentabi acp --agent claude) when the client must answer permission
requests.
Audit. Every routed method is recorded with method, agent, session,
duration, and outcome on the agentabi.acp.audit logger.
Lifecycle. One backend instance per agent is shared by its sessions and stopped when its last session closes. A new session starts it again.
Key Features
Unified TaskConfig
All agents accept the same TaskConfig with fields for:
- Agent selection:
agent,model - Reasoning control:
thinking_level("off","low","medium","high","max") - Structured output:
output_schema(JSON Schema) - Session management:
session_id,resume,ephemeral - Workspace:
working_dir,additional_dirs,files - Permissions:
permissions,allowed_tools,disallowed_tools - System prompts:
system_prompt,append_system_prompt - Endpoint and auth:
settings(base_url,api_key_env,model_provider,headers,env,args,native)
Unified IR Events
All agents emit the same streaming events:
session_start/session_end— session lifecyclemessage_start/message_delta/message_end— text streamingcontent_block_start/content_block_end— content block boundariesreasoning_delta— thinking/reasoning text (Claude, Pi)tool_use/tool_result— tool callssubagent_start/subagent_end— a Claude session's own subagent dispatch (observation)usage— token counts (includingreasoning_tokens)error— error reporting
Documentation
License
MIT
Metadata
Release files for agentabi 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentabi-0.5.0.tar.gz | 212.0 kB | With provenance | Details for agentabi-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentabi-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for agentabi-0.5.0-py3-none-any.whl |
Total release size: 465.7 kB
Release files / agentabi-0.5.0.tar.gz
| Download URL | agentabi-0.5.0.tar.gz |
|---|---|
| Size | 212.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f25632c8166b04d3ce793369903e3b1f848631591db8dd5cbc83d9cedcfe049f
|
|
BLAKE2b-256 checksum How to use checksums |
fa0e357aa3a9fd95bc7299c43454849697088b3a06768f48cc416b6c7f21e9cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logRelease files / agentabi-0.5.0-py3-none-any.whl
| Download URL | agentabi-0.5.0-py3-none-any.whl |
|---|---|
| Size | 253.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9f7eb56de89bfe9b48b3a1d7a52ab548a50b5e404462dea0552c1ecb984cbe44
|
|
BLAKE2b-256 checksum How to use checksums |
02f106b599a50a3de9a7baf77b659c9009a2f1e97380cc70ee4437422535f70f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logSecurity for agentabi 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agentabi-0.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.