Agent Shuttle

Russian version / Русская версия

Agent Shuttle gives Python applications one way to work with Codex, Antigravity, OpenCode, Claude Code, and configured ACP agents. It runs local agent tasks, preserves multi-turn sessions, and exposes the agents through A2A 1.0 JSON-RPC and MCP.

It allows agents and external applications to delegate tasks to peer agents, reuse multi-turn conversations, query live model catalogs and account quotas, and report each runtime's tool permission guarantees—all on local loopback (127.0.0.1) without sharing cloud API keys.

Supported Agent Harnesses

Installation

Agent Shuttle runs on Windows, Linux, and macOS. For the command-line tools and MCP server, install uv first; uv can obtain a compatible Python automatically.

Install the commands and MCP server

uv tool install git+https://github.com/Plartex/agent-shuttle.git
uv tool dir --bin

The package is not published on PyPI yet. The last command shows where uv placed agent-shuttle-mcp (with .exe on Windows); use its absolute path in your MCP client's configuration. To use agent-shuttle directly in a shell, run uv tool update-shell if the command is not on PATH, then open a new shell. After a verified PyPI release, the install command will be uv tool install agent-shuttle.

To check local harness availability, run agent-shuttle discover; it does not authenticate or send a model request. agent-shuttle doctor <agent> --smoke checks a real model turn when needed. MCP already provides ask_agent for supported harnesses and configured profiles.

Use the Python library in another project

uv add git+https://github.com/Plartex/agent-shuttle.git

uv tool install isolates the tool from your project's Python environment. Install Agent Shuttle as a project dependency when your code imports agent_shuttle. After a verified PyPI release, use uv add agent-shuttle.

Install from Local Checkout

You can install Agent Shuttle directly from its repository checkout into your project's virtual environment:

# Create and activate your virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install in standard or editable mode
pip install C:\path\to\agent-shuttle
# or editable mode during development:
# pip install -e C:\path\to\agent-shuttle

Once installed, the CLI tools (agent-shuttle, agent-shuttle-mcp) and Python API (agent_shuttle) are fully accessible inside that virtual environment. The original checkout directory does not need to stay in place for runtime imports. Version 0.6 removes the old agent_bridge Python imports and agent-bridge commands; the agent_bridge.* A2A metadata keys remain part of the wire protocol.

The distribution has one Python package: src/agent_shuttle/. This is the standard src layout; there is no second implementation or compatibility package.

Quickstart

Install the MCP server, then give your MCP client its absolute executable path:

uv tool install git+https://github.com/Plartex/agent-shuttle.git
uv tool dir --bin

Point your MCP client's command at agent-shuttle-mcp in the printed directory. MCP starts a local A2A peer when a request needs one; there is no separate server startup step. See the getting started guide for MCP configuration and harness setup.

For a persistent server, run agent-shuttle serve codex --workspace . --port 8765 (or serve antigravity on port 8766) in a terminal and stop it with Ctrl+C.

Minimal Examples

1. Python API

import asyncio
from pathlib import Path
from agent_shuttle import ShuttleClient, HarnessLaunch, connect_harness

async def main():
    client = ShuttleClient()

    # Query live model catalog and quota information
    info = await client.info("http://127.0.0.1:8766")
    print("Selected model:", info["capabilities"]["selected_model"])

    # One-shot task
    result = await client.ask(
        "http://127.0.0.1:8766",
        "Explain the project structure and list entry points.",
        model="gemini-3.8-flash-medium",
        reasoning_effort="medium",
    )
    print(f"[{result.state}] Task {result.task_id}:\n{result.text}")

    # Persistent multi-turn session (preserves conversation context)
    async with client.session(
        "http://127.0.0.1:8765",
        model="gpt-5.6-terra",
        reasoning_effort="high",
    ) as session:
        step1 = await session.ask("What database migrations are pending?")
        step2 = await session.ask("Generate SQL to apply the first migration.")
        print("Step 2 response:", step2.text)
        print("Step 2 token usage:", step2.usage)

    # Managed peer lifecycle: reuse existing server or start a temporary one
    launch = HarnessLaunch(
        name="antigravity",
        url="http://127.0.0.1:8766",
        workspace=Path.cwd(),
    )
    async with connect_harness(launch) as conn:
        print("Connected to:", conn.url, "(spawned temporary:", conn.started, ")")

asyncio.run(main())

2. Command-Line Interface (CLI)

# Discover locally installed harnesses without starting models
agent-shuttle discover

# Check installation and connection without a model turn
agent-shuttle doctor
agent-shuttle doctor --profile .\examples\opencode-ollama.json

# After fixing a reported issue, verify one real turn (uses model tokens)
agent-shuttle doctor codex --smoke

# Start an A2A server for Codex
agent-shuttle serve codex --workspace . --port 8765

# Start an A2A server for Antigravity (CLI mode)
agent-shuttle serve antigravity --workspace . --port 8766

# Start an A2A server from a profile (OpenCode, Claude Code or ACP)
agent-shuttle serve profile --profile .\examples\opencode-ollama.json --workspace . --port 8767

# Query server capabilities, models, and quota limits
agent-shuttle info http://127.0.0.1:8765

# Send a task from the command line
agent-shuttle ask http://127.0.0.1:8765 "Summarize recent changes" --model gpt-5.6-terra

doctor reports installation, connection and turn verification separately. Its default run checks built-ins and local profiles registered in BRIDGE_AGENTS_JSON; missing optional runtimes are skipped. OpenCode and Claude Code need a JSON profile for connection checks. --json provides the same report for scripts. Exit codes are 0 for passed checks, 1 for a failed target or smoke turn, and 2 for invalid invocation or configuration. --smoke requires one target and uses enforced no_tools (or Codex read_only); ACP smoke is rejected because ACP cannot enforce those restrictions.

Register an ACP agent

Copy examples/acp-worker.json, set command to the installed agent's ACP launch command, and set workspace to the project directory. command is an argument array; it is never run through a shell. provider, default_model, allowed_models, and reasoning_efforts are optional for ACP. Without allowlists, an explicit model or effort may select any variant advertised in the session's ACP config options; configured allowlists narrow those choices.

agent-shuttle discover --profile .\examples\acp-worker.json
agent-shuttle serve profile --profile .\examples\acp-worker.json --port 8768
agent-shuttle info http://127.0.0.1:8768
agent-shuttle ask http://127.0.0.1:8768 "Explain this project" --tool-policy read_only

For MCP managed startup, map an arbitrary ID to the profile in BRIDGE_AGENTS_JSON:

{"my-acp": {"harness": "acp", "profile": "C:/profiles/my-acp.json"}}

ACP discovery checks the command without starting the agent. info performs the ACP handshake and reports negotiated capabilities without sending a model prompt. ACP policies are advisory: results include a warning, and read_only_tools remains false because the agent may use tools outside client permission requests. Use a verified external sandbox when an enforceable restriction is required.

3. Model Context Protocol (MCP)

Start the stdio MCP server:

agent-shuttle-mcp
# or: python -m agent_shuttle.mcp_server

Available MCP tools:

• ask_agent(agent_id, prompt, model?, reasoning_effort?, tool_policy?, workspace?): Reuses a matching local A2A server or starts a temporary one. Built-in IDs are codex, antigravity, opencode, and claude_code; configured ACP IDs require a JSON profile in BRIDGE_AGENTS_JSON.
• get_agent_info(agent_id, workspace?): Fetches live models and quotas, starting a temporary server if needed.
• ask_antigravity(prompt, model?, reasoning_effort?, workspace?, tool_policy?, turn_timeout_seconds=300): Starts an Antigravity server if one is not running.
• ask_codex(prompt, model?, reasoning_effort?, workspace?): Starts a Codex server if one is not running.
• get_antigravity_info(workspace?) & get_codex_info(): Read live capabilities and quota without burning model turns.
• submit_task(agent_id, prompt, model?, reasoning_effort?, tool_policy?, workspace?, request_id?): Start a long task and return its ID immediately.
• check_task(task_id), wait_task(task_id, timeout_seconds?), cancel_task(task_id): Inspect, wait for, or stop a task.
• get_result(task_id, cursor?, limit?), get_transcript(task_id, cursor?, limit?): Read bounded pages of output and history.

Key Concepts

Harness Discovery

Run agent-shuttle discover (or discover_harnesses() in Python) to inspect local executables without launching processes or loading weights. It checks PATH and platform-specific standard installation directories (%LOCALAPPDATA%\agy\bin, npm global directories, etc.). Custom paths can be specified via environment variables (BRIDGE_AGY_COMMAND) or CLI flags (--agy-command, --opencode-command, --claude-command).

Model & Reasoning Selection

Model parameters are passed as A2A metadata keys (agent_bridge.model, agent_bridge.reasoning_effort):

• Antigravity: Reasoning effort is embedded in model IDs (e.g. gemini-3.8-flash-medium). If both --model and --effort are passed, they must match.
• Codex: Model and reasoning effort are configured independently according to the catalog returned by get_codex_info.
• OpenCode & Claude Code: Profiles define allowed_models and optional reasoning_efforts (such as model variants for Ollama or CLI flags).

Workspaces & Session Isolation

• Every server binds to a strictly validated, canonical workspace directory.
• connect_harness() verifies that an existing server's workspace matches the caller's target workspace before reusing it.
• Sessions: BridgeSession maintains a stateful conversation across multiple ask() calls. Conversation settings (model, effort, tool policy) are pinned at session creation and cannot be changed mid-session. Idle sessions are cleaned up automatically after 30 minutes.
• Library task lifecycle: TaskManager runs agents directly from Python, with no A2A or MCP server. It owns task IDs, sessions, a SQLite event journal, cancellation, result paging, preferences, and interruption recovery. A2A projects the same task ID and result through its protocol; MCP continues to reach those tasks through managed A2A peers. See the Python API.
• Remote task lifecycle: ShuttleClient.submit() returns a remote TaskHandle immediately. Use status(), bounded wait(timeout), events(), result_page(), transcript(), result(), or cancel(); reopen a task by ID with client.task(url, task_id). A wait timeout does not stop the agent. An optional UUID request_id deduplicates retried submissions. Standalone servers can persist tasks with --task-db; MCP task tools do this automatically in the workspace's .agent-shuttle directory. Completed results survive restart; interrupted work is marked failed without replay. See the API reference.

Safety & Tool Policies

Agent Shuttle defines four standardized tool policies:

• no_tools: Disables tool invocations entirely.
• read_only: Permits non-mutating search and file reading.
• workspace_write: Allows editing files within the designated workspace.
• full_access: Explicitly unclamps all tool restrictions and approval prompts.

For configured ACP agents, these policies are advisory. Agent Shuttle checks ACP permission requests but cannot prevent an agent from acting outside them. See the permissions guide.

Testing

Agent Shuttle provides a comprehensive offline test suite using fake backends that execute without network access, credentials, or model quota consumption:

GitHub Actions runs this same suite on Windows, Ubuntu Linux, and Apple Silicon macOS (macos-15), each with Python 3.11 and 3.12. The process smoke uses only a local Python worker and checks process-tree cleanup; no agent CLI or account is needed.

python -m unittest discover -s tests -v

Live integration tests against real models are separate, opt-in checks and are not part of the six CI jobs. They can be executed by specifying target environments (e.g. BRIDGE_LIVE_OLLAMA_MODEL=qwen3.5:9b or BRIDGE_LIVE_AGY_FULL_ACCESS=1). See CONTRIBUTING.md for full instructions.

Documentation Index

• Getting Started Guide
• API Reference
• Permissions & Safety Guide
• Architecture & Protocol Design
• Troubleshooting & Diagnostics
• Contributing Guidelines
• Security Policy