acp-sdk 0.0.5__tar.gz → 0.1.0rc5__tar.gz

{acp_sdk-0.0.5 → acp_sdk-0.1.0rc5}/.gitignore

@@ -1,5 +1,40 @@
+### NextJS template
+# dependencies
+node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
 .DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
 
+### Python template
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -13,6 +48,7 @@ __pycache__/
 build/
 develop-eggs/
 dist/
+dist-py/
 downloads/
 eggs/
 .eggs/
@@ -161,7 +197,7 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
 
-# vscode
-.vscode/
+# Mise
+mise.local.toml

acp_sdk-0.1.0rc5/.python-version

@@ -0,0 +1 @@
+3.11

acp_sdk-0.1.0rc5/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: acp-sdk
+Version: 0.1.0rc5
+Summary: Agent Communication Protocol SDK
+Requires-Python: <4.0,>=3.11
+Requires-Dist: opentelemetry-api>=1.31.1
+Requires-Dist: pydantic>=2.11.1
+Provides-Extra: client
+Requires-Dist: httpx-sse>=0.4.0; extra == 'client'
+Requires-Dist: httpx>=0.28.1; extra == 'client'
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.52b1; extra == 'client'
+Provides-Extra: server
+Requires-Dist: fastapi[standard]>=0.115.8; extra == 'server'
+Requires-Dist: janus>=2.0.0; extra == 'server'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.31.1; extra == 'server'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.52b1; extra == 'server'
+Requires-Dist: opentelemetry-sdk>=1.31.1; extra == 'server'
+Description-Content-Type: text/markdown
+
+# Agent Communication Protocol SDK for Python
+
+Agent Communication Protocol SDK for Python provides allows developers to serve and consume agents over the Agent Communication Protocol.
+
+## Prerequisites
+
+✅ Python >= 3.11
+
+## Installation
+
+Install to use client:
+
+```shell
+pip install acp-sdk[client]
+```
+
+Install to use server:
+
+```shell
+pip install acp-sdk[server]
+```
+
+## Overview
+
+### Client
+
+The `client` submodule exposes [httpx]() based client with simple methods for communication over ACP.
+
+```python
+async with Client(base_url="http://localhost:8000") as client:
+    run = await client.run_sync(agent="echo", input=Message(TextMessagePart(content="Howdy!")))
+    print(run.output)
+```
+
+### Server
+
+The `server` submodule exposes [fastapi] application factory that makes it easy to expose any agent over ACP.
+
+```python
+class EchoAgent(Agent):
+    @property
+    def name(self) -> str:
+        return "echo"
+
+    @property
+    def description(self) -> str:
+        return "Echoes everything"
+
+    async def run(self, input: Message, *, context: Context) -> AsyncGenerator[Message | Await, AwaitResume]:
+        for part in input:
+            await asyncio.sleep(0.5)
+            yield {"thought": "I should echo everyting"}
+            yield Message(part)
+
+
+serve(EchoAgent())
+```
+
+➡️ Explore more in our [examples library](/python/examples).

acp_sdk-0.1.0rc5/README.md

@@ -0,0 +1,59 @@
+# Agent Communication Protocol SDK for Python
+
+Agent Communication Protocol SDK for Python provides allows developers to serve and consume agents over the Agent Communication Protocol.
+
+## Prerequisites
+
+✅ Python >= 3.11
+
+## Installation
+
+Install to use client:
+
+```shell
+pip install acp-sdk[client]
+```
+
+Install to use server:
+
+```shell
+pip install acp-sdk[server]
+```
+
+## Overview
+
+### Client
+
+The `client` submodule exposes [httpx]() based client with simple methods for communication over ACP.
+
+```python
+async with Client(base_url="http://localhost:8000") as client:
+    run = await client.run_sync(agent="echo", input=Message(TextMessagePart(content="Howdy!")))
+    print(run.output)
+```
+
+### Server
+
+The `server` submodule exposes [fastapi] application factory that makes it easy to expose any agent over ACP.
+
+```python
+class EchoAgent(Agent):
+    @property
+    def name(self) -> str:
+        return "echo"
+
+    @property
+    def description(self) -> str:
+        return "Echoes everything"
+
+    async def run(self, input: Message, *, context: Context) -> AsyncGenerator[Message | Await, AwaitResume]:
+        for part in input:
+            await asyncio.sleep(0.5)
+            yield {"thought": "I should echo everyting"}
+            yield Message(part)
+
+
+serve(EchoAgent())
+```
+
+➡️ Explore more in our [examples library](/python/examples).

acp_sdk-0.1.0rc5/examples/clients/advanced.py

@@ -0,0 +1,21 @@
+import asyncio
+
+import httpx
+from acp_sdk.client.client import Client
+from acp_sdk.models import Message, TextMessagePart
+
+
+async def example() -> None:
+    async with Client(
+        client=httpx.AsyncClient(
+            base_url="http://localhost:8000",
+            auth=httpx.BasicAuth(username="username", password="password"),
+            # Additional client configuration
+        )
+    ) as client:
+        run = await client.run_sync(agent="echo", input=Message(TextMessagePart(content="Howdy!")))
+        print(run.output)
+
+
+if __name__ == "__main__":
+    asyncio.run(example())

acp_sdk-0.1.0rc5/examples/clients/simple.py

@@ -0,0 +1,17 @@
+import asyncio
+
+from acp_sdk.client import Client
+from acp_sdk.models import (
+    Message,
+    TextMessagePart,
+)
+
+
+async def example() -> None:
+    async with Client(base_url="http://localhost:8000") as client:
+        run = await client.run_sync(agent="echo", input=Message(TextMessagePart(content="Howdy!")))
+        print(run.output)
+
+
+if __name__ == "__main__":
+    asyncio.run(example())

acp_sdk-0.1.0rc5/examples/clients/stream.py

@@ -0,0 +1,14 @@
+import asyncio
+
+from acp_sdk.client import Client
+from acp_sdk.models import Message, TextMessagePart
+
+
+async def example() -> None:
+    async with Client(base_url="http://localhost:8000") as client:
+        async for event in client.run_stream(agent="echo", input=Message(TextMessagePart(content="Howdy!"))):
+            print(event)
+
+
+if __name__ == "__main__":
+    asyncio.run(example())

acp_sdk-0.1.0rc5/examples/servers/awaiting.py

@@ -0,0 +1,23 @@
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from acp_sdk.models import (
+    Await,
+    AwaitResume,
+    Message,
+    TextMessagePart,
+)
+from acp_sdk.server import Context, Server
+
+server = Server()
+
+
+@server.agent()
+async def awaiting(input: Message, context: Context) -> AsyncGenerator[Message | Await | Any, AwaitResume]:
+    """Greets and awaits for more data"""
+    yield Message(TextMessagePart(content="Hello!"))
+    data = yield Await()
+    yield Message(TextMessagePart(content=f"Thanks for {data}"))
+
+
+server.run()

acp_sdk-0.1.0rc5/examples/servers/echo.py

@@ -0,0 +1,22 @@
+import asyncio
+from collections.abc import AsyncGenerator
+
+from acp_sdk.models import (
+    Message,
+)
+from acp_sdk.server import Context, RunYield, RunYieldResume, Server
+
+server = Server()
+
+
+@server.agent()
+async def echo(input: Message, context: Context) -> AsyncGenerator[RunYield, RunYieldResume]:
+    """Echoes everything"""
+    for part in input:
+        await asyncio.sleep(0.5)
+        yield {"thought": "I should echo everyting"}
+        await asyncio.sleep(0.5)
+        yield Message(part)
+
+
+server.run()

acp_sdk-0.1.0rc5/examples/servers/multi-echo.py

@@ -0,0 +1,59 @@
+from collections.abc import AsyncGenerator, Generator
+
+from acp_sdk.models import (
+    Message,
+)
+from acp_sdk.server import Agent, Context, RunYield, RunYieldResume, Server
+
+# This example showcases several ways to create echo agent using decoratos.
+
+server = Server()
+
+
+@server.agent()
+async def async_gen_echo(input: Message, context: Context) -> AsyncGenerator[RunYield, RunYieldResume]:
+    """Echoes everything"""
+    yield {"thought": "I should echo everyting"}
+    yield input
+
+
+@server.agent()
+async def async_echo(input: Message, context: Context) -> RunYield:
+    """Echoes everything"""
+    await context.yield_async({"thought": "I should echo everyting"})
+    return input
+
+
+@server.agent()
+def gen_echo(input: Message, context: Context) -> Generator[RunYield, RunYieldResume]:
+    """Echoes everything"""
+    yield {"thought": "I should echo everyting"}
+    return input
+
+
+@server.agent()
+def sync_echo(input: Message, context: Context) -> RunYield:
+    """Echoes everything"""
+    context.yield_sync({"thought": "I should echo everyting"})
+    return input
+
+
+class EchoAgent(Agent):
+    @property
+    def name(self) -> str:
+        return "class_echo"
+
+    @property
+    def description(self) -> str:
+        return "Echoes everything"
+
+    async def run(self, input: Message, context: Context) -> AsyncGenerator[RunYield, RunYieldResume]:
+        """Echoes everything"""
+        yield {"thought": "I should echo everyting"}
+        yield input
+
+
+server.register(EchoAgent())
+
+
+server.run()

acp_sdk-0.1.0rc5/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "acp-sdk"
+version = "0.1.0rc5"
+description = "Agent Communication Protocol SDK"
+readme = "README.md"
+authors = []
+requires-python = ">=3.11, <4.0"
+dependencies = ["opentelemetry-api>=1.31.1", "pydantic>=2.11.1"]
+
+[project.optional-dependencies]
+client = [
+    "httpx>=0.28.1",
+    "httpx-sse>=0.4.0",
+    "opentelemetry-instrumentation-httpx>=0.52b1",
+]
+server = [
+    "fastapi[standard]>=0.115.8",
+    "opentelemetry-exporter-otlp-proto-http>=1.31.1",
+    "opentelemetry-instrumentation-fastapi>=0.52b1",
+    "opentelemetry-sdk>=1.31.1",
+    "janus>=2.0.0",
+]
+
+[tool.uv]
+dev-dependencies = [
+    "httpx>=0.28.1",
+    "httpx-sse>=0.4.0",
+    "opentelemetry-instrumentation-httpx>=0.52b1",
+    "fastapi[standard]>=0.115.8",
+    "opentelemetry-exporter-otlp-proto-http>=1.31.1",
+    "opentelemetry-instrumentation-fastapi>=0.52b1",
+    "opentelemetry-sdk>=1.31.1",
+    "janus>=2.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

acp_sdk-0.1.0rc5/src/acp_sdk/__init__.py

@@ -0,0 +1 @@
+from acp_sdk.models import *  # noqa: F403

acp_sdk-0.1.0rc5/src/acp_sdk/client/__init__.py

@@ -0,0 +1 @@
+from acp_sdk.client.client import Client as Client

acp_sdk-0.1.0rc5/src/acp_sdk/client/client.py

@@ -0,0 +1,139 @@
+from collections.abc import AsyncIterator
+from types import TracebackType
+from typing import Self
+
+import httpx
+from httpx_sse import EventSource, aconnect_sse
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+from pydantic import TypeAdapter
+
+from acp_sdk.models import (
+    ACPError,
+    Agent,
+    AgentName,
+    AgentReadResponse,
+    AgentsListResponse,
+    AwaitResume,
+    Error,
+    Message,
+    Run,
+    RunCancelResponse,
+    RunCreateRequest,
+    RunCreateResponse,
+    RunEvent,
+    RunId,
+    RunMode,
+    RunResumeRequest,
+    RunResumeResponse,
+)
+
+
+class Client:
+    def __init__(self, *, base_url: httpx.URL | str = "", client: httpx.AsyncClient | None = None) -> None:
+        self.base_url = base_url
+
+        self._client = self._init_client(client)
+
+    def _init_client(self, client: httpx.AsyncClient | None = None) -> httpx.AsyncClient:
+        client = client or httpx.AsyncClient(base_url=self.base_url)
+        HTTPXClientInstrumentor.instrument_client(client)
+        return client
+
+    async def __aenter__(self) -> Self:
+        await self._client.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None = None,
+        exc_value: BaseException | None = None,
+        traceback: TracebackType | None = None,
+    ) -> None:
+        await self._client.__aexit__(exc_type, exc_value, traceback)
+
+    async def agents(self) -> AsyncIterator[Agent]:
+        response = await self._client.get("/agents")
+        self._raise_error(response)
+        for agent in AgentsListResponse.model_validate(response.json()).agents:
+            yield agent
+
+    async def agent(self, *, name: AgentName) -> Agent:
+        response = await self._client.get(f"/agents/{name}")
+        self._raise_error(response)
+        return AgentReadResponse.model_validate(response.json())
+
+    async def run_sync(self, *, agent: AgentName, input: Message) -> Run:
+        response = await self._client.post(
+            "/runs",
+            json=RunCreateRequest(agent_name=agent, input=input, mode=RunMode.SYNC).model_dump(),
+        )
+        self._raise_error(response)
+        return RunCreateResponse.model_validate(response.json())
+
+    async def run_async(self, *, agent: AgentName, input: Message) -> Run:
+        response = await self._client.post(
+            "/runs",
+            json=RunCreateRequest(agent_name=agent, input=input, mode=RunMode.ASYNC).model_dump(),
+        )
+        self._raise_error(response)
+        return RunCreateResponse.model_validate(response.json())
+
+    async def run_stream(self, *, agent: AgentName, input: Message) -> AsyncIterator[RunEvent]:
+        async with aconnect_sse(
+            self._client,
+            "POST",
+            "/runs",
+            json=RunCreateRequest(agent_name=agent, input=input, mode=RunMode.STREAM).model_dump(),
+        ) as event_source:
+            async for event in self._validate_stream(event_source):
+                yield event
+
+    async def run_status(self, *, run_id: RunId) -> Run:
+        response = await self._client.get(f"/runs/{run_id}")
+        self._raise_error(response)
+        return Run.model_validate(response.json())
+
+    async def run_cancel(self, *, run_id: RunId) -> Run:
+        response = await self._client.post(f"/runs/{run_id}/cancel")
+        self._raise_error(response)
+        return RunCancelResponse.model_validate(response.json())
+
+    async def run_resume_sync(self, *, run_id: RunId, await_: AwaitResume) -> Run:
+        response = await self._client.post(
+            f"/runs/{run_id}",
+            json=RunResumeRequest(await_=await_, mode=RunMode.SYNC).model_dump(),
+        )
+        self._raise_error(response)
+        return RunResumeResponse.model_validate(response.json())
+
+    async def run_resume_async(self, *, run_id: RunId, await_: AwaitResume) -> Run:
+        response = await self._client.post(
+            f"/runs/{run_id}",
+            json=RunResumeRequest(await_=await_, mode=RunMode.ASYNC).model_dump(),
+        )
+        self._raise_error(response)
+        return RunResumeResponse.model_validate(response.json())
+
+    async def run_resume_stream(self, *, run_id: RunId, await_: AwaitResume) -> AsyncIterator[RunEvent]:
+        async with aconnect_sse(
+            self._client,
+            "POST",
+            f"/runs/{run_id}",
+            json=RunResumeRequest(await_=await_, mode=RunMode.STREAM).model_dump(),
+        ) as event_source:
+            async for event in self._validate_stream(event_source):
+                yield event
+
+    async def _validate_stream(
+        self,
+        event_source: EventSource,
+    ) -> AsyncIterator[RunEvent]:
+        async for event in event_source.aiter_sse():
+            event = TypeAdapter(RunEvent).validate_json(event.data)
+            yield event
+
+    def _raise_error(self, response: httpx.Response) -> None:
+        try:
+            response.raise_for_status()
+        except httpx.HTTPError:
+            raise ACPError(Error.model_validate(response.json()))

acp_sdk-0.1.0rc5/src/acp_sdk/models/__init__.py

@@ -0,0 +1,3 @@
+from acp_sdk.models.errors import *  # noqa: F403
+from acp_sdk.models.models import *  # noqa: F403
+from acp_sdk.models.schemas import *  # noqa: F403

acp_sdk-0.1.0rc5/src/acp_sdk/models/errors.py

@@ -0,0 +1,23 @@
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class ErrorCode(str, Enum):
+    SERVER_ERROR = "server_error"
+    INVALID_INPUT = "invalid_input"
+    NOT_FOUND = "not_found"
+
+
+class Error(BaseModel):
+    code: ErrorCode
+    message: str
+
+
+class ACPError(Exception):
+    def __init__(self, error: Error) -> None:
+        super().__init__()
+        self.error = error
+
+    def __str__(self) -> str:
+        return str(self.error.message)