agent-client-protocol 0.11.0__tar.gz → 0.12.0__tar.gz

{agent_client_protocol-0.11.0 → agent_client_protocol-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: agent-client-protocol
-Version: 0.11.0
+Version: 0.12.0
 Summary: A Python implement of Agent Client Protocol (ACP, by Zed Industries)
 Keywords: python
 Author-Email: Chojan Shang <psiace@apache.org>, Frost Ming <me@frostming.com>
@@ -21,6 +21,9 @@ Requires-Dist: pydantic>=2.7
 Provides-Extra: logfire
 Requires-Dist: logfire>=0.14; extra == "logfire"
 Requires-Dist: opentelemetry-sdk>=1.28.0; extra == "logfire"
+Provides-Extra: http
+Requires-Dist: httpx[http2]>=0.27; extra == "http"
+Requires-Dist: websockets>=12.0; extra == "http"
 Description-Content-Type: text/markdown
 
 <a href="https://agentclientprotocol.com/">

agent_client_protocol-0.12.0/examples/http_client.py

@@ -0,0 +1,54 @@
+# /// script
+# requires-python = ">=3.10,<3.15"
+# dependencies = [
+#     "agent-client-protocol[http]",
+# ]
+# ///
+"""Connect to a remote ACP agent over Streamable HTTP (experimental).
+
+Start the server first (``uv run examples/http_server.py``), then run this.
+"""
+
+import asyncio
+from typing import Any
+
+from acp import connect_to_agent, text_block
+from acp.http import create_http_stream
+from acp.interfaces import Client
+
+
+class ExampleClient(Client):
+    async def request_permission(self, session_id: str, tool_call: Any, options: Any, **kwargs: Any) -> Any:
+        # Auto-allow the first option.
+        return {"outcome": {"outcome": "selected", "optionId": options[0]["optionId"]}}
+
+    async def session_update(self, session_id: str, update: Any, **kwargs: Any) -> None:
+        content = getattr(update, "content", None)
+        text = getattr(content, "text", None) if content is not None else None
+        if text:
+            print(f"<< {text}")
+
+    async def write_text_file(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+    async def read_text_file(self, *args: Any, **kwargs: Any) -> Any:
+        return {"content": ""}
+
+
+async def main() -> None:
+    transport = create_http_stream("http://localhost:8000/acp")
+    conn = connect_to_agent(ExampleClient(), transport)
+    try:
+        init = await conn.initialize(protocol_version=1)
+        print(f"initialized (protocol v{init.protocol_version})")
+        session = await conn.new_session(cwd=".", mcp_servers=[])
+        print(f"session: {session.session_id}")
+        result = await conn.prompt(session_id=session.session_id, prompt=[text_block("hello over http")])
+        print(f"stop reason: {result.stop_reason}")
+    finally:
+        await conn.close()
+        await transport.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agent_client_protocol-0.12.0/examples/http_server.py

@@ -0,0 +1,81 @@
+# /// script
+# requires-python = ">=3.10,<3.15"
+# dependencies = [
+#     "agent-client-protocol[http]",
+#     "hypercorn>=0.17",
+# ]
+# ///
+"""Serve an ACP agent over Streamable HTTP + WebSocket (experimental).
+
+Run with an HTTP/2-capable ASGI server for spec-compliant Streamable HTTP.  This
+example uses Hypercorn; Uvicorn works for WebSocket but does not serve HTTP/2.
+
+    uv run examples/http_server.py
+    # then, in another terminal:
+    uv run examples/http_client.py
+    uv run examples/ws_client.py
+"""
+
+import asyncio
+from typing import Any
+from uuid import uuid4
+
+from acp import (
+    Agent,
+    InitializeResponse,
+    NewSessionResponse,
+    PromptResponse,
+    text_block,
+    update_agent_message,
+)
+from acp.http.asgi import create_asgi_app
+from acp.interfaces import Client
+from acp.schema import ClientCapabilities, Implementation
+
+
+class EchoAgent(Agent):
+    _conn: Client
+
+    def on_connect(self, conn: Client) -> None:
+        self._conn = conn
+
+    async def initialize(
+        self,
+        protocol_version: int,
+        client_capabilities: ClientCapabilities | None = None,
+        client_info: Implementation | None = None,
+        **kwargs: Any,
+    ) -> InitializeResponse:
+        return InitializeResponse(protocol_version=protocol_version)
+
+    async def new_session(self, cwd: str = "", **kwargs: Any) -> NewSessionResponse:
+        return NewSessionResponse(session_id=uuid4().hex)
+
+    async def prompt(self, session_id: str, prompt: list[Any], **kwargs: Any) -> PromptResponse:
+        for block in prompt:
+            text = block.get("text", "") if isinstance(block, dict) else getattr(block, "text", "")
+            await self._conn.session_update(
+                session_id=session_id,
+                update=update_agent_message(text_block(f"echo: {text}")),
+            )
+        return PromptResponse(stop_reason="end_turn")
+
+
+# One agent instance per connection.
+app = create_asgi_app(lambda conn: EchoAgent())
+
+
+async def main() -> None:
+    import hypercorn.asyncio
+    from hypercorn.config import Config
+
+    config = Config()
+    config.bind = ["localhost:8000"]
+    # Enable HTTP/2 (Streamable HTTP requires it). Hypercorn negotiates h2c/h2.
+    config.alpn_protocols = ["h2", "http/1.1"]
+    print("Serving ACP agent on http://localhost:8000/acp (HTTP + WS)")
+    await hypercorn.asyncio.serve(app, config)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

agent_client_protocol-0.12.0/examples/ws_client.py

@@ -0,0 +1,53 @@
+# /// script
+# requires-python = ">=3.10,<3.15"
+# dependencies = [
+#     "agent-client-protocol[http]",
+# ]
+# ///
+"""Connect to a remote ACP agent over WebSocket (experimental).
+
+Start the server first (``uv run examples/http_server.py``), then run this.
+"""
+
+import asyncio
+from typing import Any
+
+from acp import connect_to_agent, text_block
+from acp.interfaces import Client
+from acp.ws import create_websocket_stream
+
+
+class ExampleClient(Client):
+    async def request_permission(self, session_id: str, tool_call: Any, options: Any, **kwargs: Any) -> Any:
+        return {"outcome": {"outcome": "selected", "optionId": options[0]["optionId"]}}
+
+    async def session_update(self, session_id: str, update: Any, **kwargs: Any) -> None:
+        content = getattr(update, "content", None)
+        text = getattr(content, "text", None) if content is not None else None
+        if text:
+            print(f"<< {text}")
+
+    async def write_text_file(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+    async def read_text_file(self, *args: Any, **kwargs: Any) -> Any:
+        return {"content": ""}
+
+
+async def main() -> None:
+    transport = await create_websocket_stream("ws://localhost:8000/acp")
+    conn = connect_to_agent(ExampleClient(), transport)
+    try:
+        init = await conn.initialize(protocol_version=1)
+        print(f"initialized (protocol v{init.protocol_version})")
+        session = await conn.new_session(cwd=".", mcp_servers=[])
+        print(f"session: {session.session_id}")
+        result = await conn.prompt(session_id=session.session_id, prompt=[text_block("hello over websocket")])
+        print(f"stop reason: {result.stop_reason}")
+    finally:
+        await conn.close()
+        await transport.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{agent_client_protocol-0.11.0 → agent_client_protocol-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-client-protocol"
-version = "0.11.0"
+version = "0.12.0"
 description = "A Python implement of Agent Client Protocol (ACP, by Zed Industries)"
 authors = [
     { name = "Chojan Shang", email = "psiace@apache.org" },
@@ -36,6 +36,10 @@ logfire = [
     "logfire>=0.14",
     "opentelemetry-sdk>=1.28.0",
 ]
+http = [
+    "httpx[http2]>=0.27",
+    "websockets>=12.0",
+]
 
 [dependency-groups]
 dev = [
@@ -51,6 +55,9 @@ dev = [
     "mkdocstrings[python]>=0.26.1",
     "python-dotenv>=1.1.1",
     "prek>=0.2.17",
+    "httpx[http2]>=0.27",
+    "websockets>=12.0",
+    "uvicorn>=0.30",
 ]
 
 [build-system]
@@ -63,6 +70,7 @@ build-backend = "pdm.backend"
 source-includes = [
     "examples/",
     "tests/",
+    "scripts/",
 ]
 
 [tool.ty.environment]

agent_client_protocol-0.12.0/scripts/__init__.py

@@ -0,0 +1 @@
+"""Utility scripts for generating ACP bindings."""

agent_client_protocol-0.12.0/scripts/gen_all.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.append(str(ROOT))
+
+from scripts import gen_meta, gen_schema, gen_signature  # noqa: E402  pylint: disable=wrong-import-position
+
+SCHEMA_DIR = ROOT / "schema"
+SCHEMA_JSON = SCHEMA_DIR / "schema.json"
+META_JSON = SCHEMA_DIR / "meta.json"
+VERSION_FILE = SCHEMA_DIR / "VERSION"
+
+DEFAULT_REPO = "agentclientprotocol/agent-client-protocol"
+LEGACY_SCHEMA_PATHS = ("schema/schema.unstable.json", "schema/meta.unstable.json")
+V1_SCHEMA_PATHS = ("schema/v1/schema.unstable.json", "schema/v1/meta.unstable.json")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Regenerate schema.py and meta.py from the ACP schema.")
+    parser.add_argument(
+        "--version",
+        "-v",
+        help=(
+            "Git ref (tag/branch) of agentclientprotocol/agent-client-protocol to fetch the schema from. "
+            "If omitted, uses the cached schema files or falls back to 'main' when missing."
+        ),
+    )
+    parser.add_argument(
+        "--repo",
+        default=os.environ.get("ACP_SCHEMA_REPO", DEFAULT_REPO),
+        help="Source repository providing schema.json/meta.json (default: %(default)s)",
+    )
+    parser.add_argument(
+        "--no-download",
+        action="store_true",
+        help="Skip downloading schema files even when a version is provided.",
+    )
+    parser.set_defaults(format_output=True)
+    parser.add_argument(
+        "--no-format",
+        dest="format_output",
+        action="store_false",
+        help="Skip formatting generated Python files after regeneration.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force schema download even if the requested ref is already cached locally.",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+
+    version = args.version or os.environ.get("ACP_SCHEMA_VERSION")
+    repo = args.repo
+    should_download = _should_download(args, version)
+
+    if should_download:
+        ref = resolve_ref(version)
+        download_schema(repo, ref)
+    else:
+        ref = resolve_ref(version) if version else _cached_ref()
+
+    if not (SCHEMA_JSON.exists() and META_JSON.exists()):
+        print("schema/schema.json or schema/meta.json missing; run with --version to fetch them.", file=sys.stderr)
+        sys.exit(1)
+
+    gen_schema.generate_schema()
+    gen_meta.generate_meta()
+    gen_signature.gen_signature(ROOT / "src" / "acp")
+    if args.format_output:
+        format_generated_files()
+
+    if ref:
+        print(f"Generated schema using ref: {ref}")
+    else:
+        print("Generated schema using local schema files")
+
+
+def format_generated_files() -> None:
+    files = [
+        ROOT / "src" / "acp" / "schema.py",
+        ROOT / "src" / "acp" / "meta.py",
+        ROOT / "src" / "acp" / "interfaces.py",
+        ROOT / "src" / "acp" / "agent" / "connection.py",
+        ROOT / "src" / "acp" / "client" / "connection.py",
+    ]
+    subprocess.check_call([sys.executable, "-m", "ruff", "check", "--fix", *(str(path) for path in files)])  # noqa: S603
+    subprocess.check_call([sys.executable, "-m", "ruff", "format", *(str(path) for path in files)])  # noqa: S603
+
+
+def _should_download(args: argparse.Namespace, version: str | None) -> bool:
+    env_override = os.environ.get("ACP_SCHEMA_DOWNLOAD")
+    if env_override is not None:
+        return env_override.lower() in {"1", "true", "yes"}
+    if args.no_download:
+        return False
+    if version:
+        if not SCHEMA_JSON.exists() or not META_JSON.exists():
+            return True
+        cached = _cached_ref()
+        if args.force:
+            return True
+        return cached != resolve_ref(version)
+    return not (SCHEMA_JSON.exists() and META_JSON.exists())
+
+
+def resolve_ref(version: str | None) -> str:
+    if not version:
+        return "refs/heads/main"
+    if version.startswith("refs/"):
+        return version
+    if re.fullmatch(r"schema-v\d+\.\d+\.\d+", version):
+        return f"refs/tags/{version}"
+    if re.fullmatch(r"v?\d+\.\d+\.\d+", version):
+        value = version if version.startswith("v") else f"v{version}"
+        return f"refs/tags/{value}"
+    return f"refs/heads/{version}"
+
+
+def download_schema(repo: str, ref: str) -> None:
+    SCHEMA_DIR.mkdir(parents=True, exist_ok=True)
+    try:
+        schema_data, meta_data = fetch_schema_pair(repo, ref)
+    except RuntimeError as exc:  # pragma: no cover - network error path
+        print(exc, file=sys.stderr)
+        sys.exit(1)
+
+    SCHEMA_JSON.write_text(json.dumps(schema_data, indent=2) + "\n", encoding="utf-8")
+    META_JSON.write_text(json.dumps(meta_data, indent=2) + "\n", encoding="utf-8")
+    VERSION_FILE.write_text(ref + "\n", encoding="utf-8")
+    print(f"Fetched schema and meta from {repo}@{ref}")
+
+
+def fetch_schema_pair(repo: str, ref: str) -> tuple[dict, dict]:
+    errors = []
+    for schema_path, meta_path in schema_source_paths(ref):
+        schema_url = f"https://raw.githubusercontent.com/{repo}/{ref}/{schema_path}"
+        meta_url = f"https://raw.githubusercontent.com/{repo}/{ref}/{meta_path}"
+        try:
+            return fetch_json(schema_url), fetch_json(meta_url)
+        except RuntimeError as exc:
+            errors.append(str(exc))
+
+    attempted = "\n".join(f"- {error}" for error in errors)
+    raise RuntimeError(f"Failed to fetch schema and meta from {repo}@{ref}. Attempts:\n{attempted}")
+
+
+def schema_source_paths(ref: str) -> tuple[tuple[str, str], ...]:
+    if re.fullmatch(r"refs/tags/schema-v\d+\.\d+\.\d+", ref):
+        return (V1_SCHEMA_PATHS, LEGACY_SCHEMA_PATHS)
+    return (LEGACY_SCHEMA_PATHS, V1_SCHEMA_PATHS)
+
+
+def fetch_json(url: str) -> dict:
+    try:
+        with urllib.request.urlopen(url) as response:  # noqa: S310 - trusted source configured by repo
+            return json.loads(response.read().decode("utf-8"))
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"Failed to fetch {url}: {exc}") from exc
+
+
+def _cached_ref() -> str | None:
+    if VERSION_FILE.exists():
+        return VERSION_FILE.read_text(encoding="utf-8").strip() or None
+    return None
+
+
+if __name__ == "__main__":
+    main()

agent_client_protocol-0.12.0/scripts/gen_meta.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SCHEMA_DIR = ROOT / "schema"
+VERSION_FILE = SCHEMA_DIR / "VERSION"
+
+
+def main() -> None:
+    generate_meta()
+
+
+def generate_meta() -> None:
+    meta_json = SCHEMA_DIR / "meta.json"
+    out_py = ROOT / "src" / "acp" / "meta.py"
+    if not meta_json.exists():
+        raise SystemExit("schema/meta.json not found. Run gen_schema.py first.")
+
+    data = json.loads(meta_json.read_text("utf-8"))
+    agent_methods = data.get("agentMethods", {})
+    client_methods = data.get("clientMethods", {})
+    version = data.get("version", 1)
+    header_lines = ["# Generated from schema/meta.json. Do not edit by hand."]
+    if VERSION_FILE.exists():
+        ref = VERSION_FILE.read_text("utf-8").strip()
+        if ref:
+            header_lines.append(f"# Schema ref: {ref}")
+
+    out_py.write_text(
+        "\n".join(header_lines)
+        + "\n"
+        + f"AGENT_METHODS = {agent_methods!r}\n"
+        + f"CLIENT_METHODS = {client_methods!r}\n"
+        + f"PROTOCOL_VERSION = {int(version)}\n",
+        encoding="utf-8",
+    )
+
+
+if __name__ == "__main__":
+    main()