acp-sdk 0.0.6__tar.gz → 0.1.0__tar.gz

{acp_sdk-0.0.6 → acp_sdk-0.1.0}/.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.0/.python-version

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

acp_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: acp-sdk
+Version: 0.1.0
+Summary: Agent Communication Protocol SDK
+Author: IBM Corp.
+Maintainer-email: Tomas Pilar <thomas7pilar@gmail.com>
+License-Expression: Apache-2.0
+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]
+```
+
+Install to use models only:
+
+```shell
+pip install acp-sdk
+```
+
+## Overview
+
+### Core
+
+The core of the SDK exposes [pydantic](https://docs.pydantic.dev/) data models corresponding to REST API requests, responses, resources, events and errors.
+
+
+### Client
+
+The `client` submodule exposes [httpx](https://www.python-httpx.org/) 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", inputs=[Message(parts=[MessagePart(content="Howdy!")])])
+    print(run)
+
+```
+
+### Server
+
+The `server` submodule exposes `Agent` class and `agent` decorator together with [fastapi](https://fastapi.tiangolo.com/) application factory, making it easy to expose agents over ACP. Additionaly, it exposes [uvicorn](https://www.uvicorn.org/) based server to serve agents with set up logging, [opentelemetry](https://opentelemetry.io/) and more.
+
+```python
+server = Server()
+
+@server.agent()
+async def echo(inputs: list[Message], context: Context) -> AsyncGenerator[RunYield, RunYieldResume]:
+    """Echoes everything"""
+    for message in inputs:
+        yield {"thought": "I should echo everyting"}
+        await asyncio.sleep(0.5)
+        yield message
+
+
+server.run()
+```
+
+➡️ Explore more in our [examples library](/python/examples).
+
+## Architecture
+
+The architecture of the SDK is outlined in the following segment. It focuses on central parts of the SDK without going into much detail.
+
+### Models
+
+The core of the SDK contains pydantic models for requests, responses, resources, events and errors. Users of the SDK are meant to use these models directly or indirectly.
+
+### Server
+
+The server module consists of 3 parts:
+  
+  1. Agent interface
+  2. FastAPI application factory
+  3. Uvicorn based server
+
+Each part builds on top of the previous one. Not all parts need to be used, e.g. users are advised to bring their own ASGI server for production deployments.
+
+### Client
+
+The client module consists of httpx based client with session support. The client is meant to be thin and mimic the REST API. Exception is session management which has been abstracted into a context manager.
+
+
+  

acp_sdk-0.1.0/README.md

@@ -0,0 +1,91 @@
+# 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]
+```
+
+Install to use models only:
+
+```shell
+pip install acp-sdk
+```
+
+## Overview
+
+### Core
+
+The core of the SDK exposes [pydantic](https://docs.pydantic.dev/) data models corresponding to REST API requests, responses, resources, events and errors.
+
+
+### Client
+
+The `client` submodule exposes [httpx](https://www.python-httpx.org/) 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", inputs=[Message(parts=[MessagePart(content="Howdy!")])])
+    print(run)
+
+```
+
+### Server
+
+The `server` submodule exposes `Agent` class and `agent` decorator together with [fastapi](https://fastapi.tiangolo.com/) application factory, making it easy to expose agents over ACP. Additionaly, it exposes [uvicorn](https://www.uvicorn.org/) based server to serve agents with set up logging, [opentelemetry](https://opentelemetry.io/) and more.
+
+```python
+server = Server()
+
+@server.agent()
+async def echo(inputs: list[Message], context: Context) -> AsyncGenerator[RunYield, RunYieldResume]:
+    """Echoes everything"""
+    for message in inputs:
+        yield {"thought": "I should echo everyting"}
+        await asyncio.sleep(0.5)
+        yield message
+
+
+server.run()
+```
+
+➡️ Explore more in our [examples library](/python/examples).
+
+## Architecture
+
+The architecture of the SDK is outlined in the following segment. It focuses on central parts of the SDK without going into much detail.
+
+### Models
+
+The core of the SDK contains pydantic models for requests, responses, resources, events and errors. Users of the SDK are meant to use these models directly or indirectly.
+
+### Server
+
+The server module consists of 3 parts:
+  
+  1. Agent interface
+  2. FastAPI application factory
+  3. Uvicorn based server
+
+Each part builds on top of the previous one. Not all parts need to be used, e.g. users are advised to bring their own ASGI server for production deployments.
+
+### Client
+
+The client module consists of httpx based client with session support. The client is meant to be thin and mimic the REST API. Exception is session management which has been abstracted into a context manager.
+
+
+  

acp_sdk-0.1.0/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, MessagePart
+
+
+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", inputs=[Message(parts=[MessagePart(content="Howdy!")])])
+        print(run)
+
+
+if __name__ == "__main__":
+    asyncio.run(example())

acp_sdk-0.1.0/examples/clients/session.py

@@ -0,0 +1,18 @@
+import asyncio
+
+from acp_sdk.client import Client
+from acp_sdk.models import (
+    Message,
+    MessagePart,
+)
+
+
+async def example() -> None:
+    async with Client(base_url="http://localhost:8000") as client, client.session() as session:
+        run = await session.run_sync(agent="echo", inputs=[Message(parts=[MessagePart(content="Howdy!")])])
+        run = await session.run_sync(agent="echo", inputs=[Message(parts=[MessagePart(content="Howdy again!")])])
+        print(run)
+
+
+if __name__ == "__main__":
+    asyncio.run(example())

acp_sdk-0.1.0/examples/clients/simple.py

@@ -0,0 +1,19 @@
+import asyncio
+
+from acp_sdk.client import Client
+from acp_sdk.models import (
+    Message,
+    MessagePart,
+)
+
+
+async def example() -> None:
+    async with Client(base_url="http://localhost:8000") as client:
+        run = await client.run_sync(
+            agent="echo", inputs=[Message(parts=[MessagePart(content="Howdy!", content_type="text/plain")])]
+        )
+        print(run.outputs)
+
+
+if __name__ == "__main__":
+    asyncio.run(example())

acp_sdk-0.1.0/examples/clients/stream.py

@@ -0,0 +1,16 @@
+import asyncio
+
+from acp_sdk.client import Client
+from acp_sdk.models import Message, MessagePart
+
+
+async def example() -> None:
+    async with Client(base_url="http://localhost:8000") as client:
+        async for event in client.run_stream(
+            agent="echo", inputs=[Message(parts=[MessagePart(content="Howdy!", content_type="text/plain")])]
+        ):
+            print(event)
+
+
+if __name__ == "__main__":
+    asyncio.run(example())

acp_sdk-0.1.0/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,
+    MessagePart,
+)
+from acp_sdk.server import Context, Server
+
+server = Server()
+
+
+@server.agent()
+async def awaiting(inputs: list[Message], context: Context) -> AsyncGenerator[Message | Await | Any, AwaitResume]:
+    """Greets and awaits for more data"""
+    yield Message(parts=[MessagePart(content="Hello!", content_type="text/plain")])
+    data = yield Await()
+    yield Message(parts=[MessagePart(content=f"Thanks for {data}", content_type="text/plain")])
+
+
+server.run()

acp_sdk-0.1.0/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(inputs: list[Message], context: Context) -> AsyncGenerator[RunYield, RunYieldResume]:
+    """Echoes everything"""
+    for message in inputs:
+        await asyncio.sleep(0.5)
+        yield {"thought": "I should echo everyting"}
+        await asyncio.sleep(0.5)
+        yield message
+
+
+server.run()

acp_sdk-0.1.0/examples/servers/standalone.py

@@ -0,0 +1,25 @@
+from collections.abc import AsyncGenerator
+
+from acp_sdk.models import (
+    Message,
+)
+from acp_sdk.server import RunYield, RunYieldResume, agent, create_app
+
+# This example demonstrates how to serve agents with you own server
+
+
+@agent()
+async def echo(inputs: list[Message]) -> AsyncGenerator[RunYield, RunYieldResume]:
+    """Echoes everything"""
+    for message in inputs:
+        yield message
+
+
+app = create_app(echo)
+
+# The app can now be used with any ASGI server
+
+# Run with
+#   1. fastapi run examples/servers/standalone.py
+#   2. uvicorn examples.servers.standalone:app
+#   ...

acp_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "acp-sdk"
+version = "0.1.0"
+description = "Agent Communication Protocol SDK"
+license = "Apache-2.0"
+readme = "README.md"
+authors = [{ name = "IBM Corp." }]
+maintainers = [{ name = "Tomas Pilar", email = "thomas7pilar@gmail.com" }]
+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.0/pytest.ini

@@ -0,0 +1,5 @@
+[pytest]
+testpaths = tests/e2e
+python_files = test_*.py
+python_functions = test_*
+addopts = -v --strict-markers

acp_sdk-0.1.0/src/acp_sdk/__init__.py

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

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

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

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

@@ -0,0 +1,178 @@
+import uuid
+from collections.abc import AsyncGenerator, AsyncIterator
+from contextlib import asynccontextmanager
+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,
+    CreatedEvent,
+    Error,
+    Message,
+    Run,
+    RunCancelResponse,
+    RunCreateRequest,
+    RunCreateResponse,
+    RunEvent,
+    RunId,
+    RunMode,
+    RunResumeRequest,
+    RunResumeResponse,
+    SessionId,
+)
+
+
+class Client:
+    def __init__(
+        self,
+        *,
+        base_url: httpx.URL | str = "",
+        session_id: SessionId | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.base_url = base_url
+        self.session_id = session_id
+
+        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)
+
+    @asynccontextmanager
+    async def session(self, session_id: SessionId | None = None) -> AsyncGenerator[Self]:
+        yield Client(client=self._client, session_id=session_id or uuid.uuid4())
+
+    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, inputs: list[Message]) -> Run:
+        response = await self._client.post(
+            "/runs",
+            content=RunCreateRequest(
+                agent_name=agent,
+                inputs=inputs,
+                mode=RunMode.SYNC,
+                session_id=self.session_id,
+            ).model_dump_json(),
+        )
+        self._raise_error(response)
+        response = RunCreateResponse.model_validate(response.json())
+        self._set_session(response)
+        return response
+
+    async def run_async(self, *, agent: AgentName, inputs: list[Message]) -> Run:
+        response = await self._client.post(
+            "/runs",
+            content=RunCreateRequest(
+                agent_name=agent,
+                inputs=inputs,
+                mode=RunMode.ASYNC,
+                session_id=self.session_id,
+            ).model_dump_json(),
+        )
+        self._raise_error(response)
+        response = RunCreateResponse.model_validate(response.json())
+        self._set_session(response)
+        return response
+
+    async def run_stream(self, *, agent: AgentName, inputs: list[Message]) -> AsyncIterator[RunEvent]:
+        async with aconnect_sse(
+            self._client,
+            "POST",
+            "/runs",
+            content=RunCreateRequest(
+                agent_name=agent,
+                inputs=inputs,
+                mode=RunMode.STREAM,
+                session_id=self.session_id,
+            ).model_dump_json(),
+        ) as event_source:
+            async for event in self._validate_stream(event_source):
+                if isinstance(event, CreatedEvent):
+                    self._set_session(event.run)
+                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()))
+
+    def _set_session(self, run: Run) -> None:
+        self.session_id = run.session_id

acp_sdk-0.1.0/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.0/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)