acp-sdk 0.1.0rc7__tar.gz → 0.2.0__tar.gz

acp_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: acp-sdk
+Version: 0.2.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.2.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.0rc7 → acp_sdk-0.2.0}/examples/clients/advanced.py

@@ -2,7 +2,7 @@ import asyncio
 
 import httpx
 from acp_sdk.client.client import Client
-from acp_sdk.models import Message, TextMessagePart
+from acp_sdk.models import Message, MessagePart
 
 
 async def example() -> None:
@@ -13,8 +13,8 @@ async def example() -> None:
             # Additional client configuration
         )
     ) as client:
-        run = await client.run_sync(agent="echo", input=Message(TextMessagePart(content="Howdy!")))
-        print(run.output)
+        run = await client.run_sync(agent="echo", inputs=[Message(parts=[MessagePart(content="Howdy!")])])
+        print(run)
 
 
 if __name__ == "__main__":

acp_sdk-0.2.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.0rc7 → acp_sdk-0.2.0}/examples/clients/simple.py

@@ -3,14 +3,16 @@ import asyncio
 from acp_sdk.client import Client
 from acp_sdk.models import (
     Message,
-    TextMessagePart,
+    MessagePart,
 )
 
 
 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)
+        run = await client.run_sync(
+            agent="echo", inputs=[Message(parts=[MessagePart(content="Howdy!", content_type="text/plain")])]
+        )
+        print(run.outputs)
 
 
 if __name__ == "__main__":

{acp_sdk-0.1.0rc7 → acp_sdk-0.2.0}/examples/clients/stream.py

@@ -1,12 +1,14 @@
 import asyncio
 
 from acp_sdk.client import Client
-from acp_sdk.models import Message, TextMessagePart
+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", input=Message(TextMessagePart(content="Howdy!"))):
+        async for event in client.run_stream(
+            agent="echo", inputs=[Message(parts=[MessagePart(content="Howdy!", content_type="text/plain")])]
+        ):
             print(event)
 
 

acp_sdk-0.2.0/examples/servers/awaiting.py

@@ -0,0 +1,25 @@
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from acp_sdk.models import (
+    AwaitRequest,
+    AwaitResume,
+    Message,
+    MessagePart,
+)
+from acp_sdk.server import Context, Server
+
+server = Server()
+
+
+@server.agent()
+async def awaiting(
+    inputs: list[Message], context: Context
+) -> AsyncGenerator[Message | AwaitRequest | Any, AwaitResume]:
+    """Greets and awaits for more data"""
+    yield MessagePart(content="Hello!", content_type="text/plain")
+    data = yield AwaitRequest()
+    yield MessagePart(content=f"Thanks for {data}", content_type="text/plain")
+
+
+server.run()

{acp_sdk-0.1.0rc7 → acp_sdk-0.2.0}/examples/servers/echo.py

@@ -10,13 +10,13 @@ server = Server()
 
 
 @server.agent()
-async def echo(input: Message, context: Context) -> AsyncGenerator[RunYield, RunYieldResume]:
+async def echo(inputs: list[Message], context: Context) -> AsyncGenerator[RunYield, RunYieldResume]:
     """Echoes everything"""
-    for part in input:
+    for message in inputs:
         await asyncio.sleep(0.5)
         yield {"thought": "I should echo everyting"}
         await asyncio.sleep(0.5)
-        yield Message(part)
+        yield message
 
 
-server()
+server.run()

acp_sdk-0.2.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.0rc7 → acp_sdk-0.2.0}/pyproject.toml

@@ -1,9 +1,11 @@
 [project]
 name = "acp-sdk"
-version = "0.1.0rc7"
+version = "0.2.0"
 description = "Agent Communication Protocol SDK"
+license = "Apache-2.0"
 readme = "README.md"
-authors = []
+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"]
 

acp_sdk-0.2.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.2.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.0rc7 → acp_sdk-0.2.0}/src/acp_sdk/client/client.py

@@ -1,4 +1,6 @@
-from collections.abc import AsyncIterator
+import uuid
+from collections.abc import AsyncGenerator, AsyncIterator
+from contextlib import asynccontextmanager
 from types import TracebackType
 from typing import Self
 
@@ -15,22 +17,31 @@ from acp_sdk.models import (
     AgentsListResponse,
     AwaitResume,
     Error,
+    Event,
     Message,
     Run,
     RunCancelResponse,
+    RunCreatedEvent,
     RunCreateRequest,
     RunCreateResponse,
-    RunEvent,
     RunId,
     RunMode,
     RunResumeRequest,
     RunResumeResponse,
+    SessionId,
 )
 
 
 class Client:
-    def __init__(self, *, base_url: httpx.URL | str = "", client: httpx.AsyncClient | None = None) -> None:
+    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)
 
@@ -51,6 +62,10 @@ class Client:
     ) -> 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)
@@ -62,30 +77,51 @@ class Client:
         self._raise_error(response)
         return AgentReadResponse.model_validate(response.json())
 
-    async def run_sync(self, *, agent: AgentName, input: Message) -> Run:
+    async def run_sync(self, *, agent: AgentName, inputs: list[Message]) -> Run:
         response = await self._client.post(
             "/runs",
-            json=RunCreateRequest(agent_name=agent, input=input, mode=RunMode.SYNC).model_dump(),
+            content=RunCreateRequest(
+                agent_name=agent,
+                inputs=inputs,
+                mode=RunMode.SYNC,
+                session_id=self.session_id,
+            ).model_dump_json(),
         )
         self._raise_error(response)
-        return RunCreateResponse.model_validate(response.json())
+        response = RunCreateResponse.model_validate(response.json())
+        self._set_session(response)
+        return response
 
-    async def run_async(self, *, agent: AgentName, input: Message) -> Run:
+    async def run_async(self, *, agent: AgentName, inputs: list[Message]) -> Run:
         response = await self._client.post(
             "/runs",
-            json=RunCreateRequest(agent_name=agent, input=input, mode=RunMode.ASYNC).model_dump(),
+            content=RunCreateRequest(
+                agent_name=agent,
+                inputs=inputs,
+                mode=RunMode.ASYNC,
+                session_id=self.session_id,
+            ).model_dump_json(),
         )
         self._raise_error(response)
-        return RunCreateResponse.model_validate(response.json())
+        response = RunCreateResponse.model_validate(response.json())
+        self._set_session(response)
+        return response
 
-    async def run_stream(self, *, agent: AgentName, input: Message) -> AsyncIterator[RunEvent]:
+    async def run_stream(self, *, agent: AgentName, inputs: list[Message]) -> AsyncIterator[Event]:
         async with aconnect_sse(
             self._client,
             "POST",
             "/runs",
-            json=RunCreateRequest(agent_name=agent, input=input, mode=RunMode.STREAM).model_dump(),
+            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, RunCreatedEvent):
+                    self._set_session(event.run)
                 yield event
 
     async def run_status(self, *, run_id: RunId) -> Run:
@@ -114,7 +150,7 @@ class Client:
         self._raise_error(response)
         return RunResumeResponse.model_validate(response.json())
 
-    async def run_resume_stream(self, *, run_id: RunId, await_: AwaitResume) -> AsyncIterator[RunEvent]:
+    async def run_resume_stream(self, *, run_id: RunId, await_: AwaitResume) -> AsyncIterator[Event]:
         async with aconnect_sse(
             self._client,
             "POST",
@@ -127,9 +163,9 @@ class Client:
     async def _validate_stream(
         self,
         event_source: EventSource,
-    ) -> AsyncIterator[RunEvent]:
+    ) -> AsyncIterator[Event]:
         async for event in event_source.aiter_sse():
-            event = TypeAdapter(RunEvent).validate_json(event.data)
+            event = TypeAdapter(Event).validate_json(event.data)
             yield event
 
     def _raise_error(self, response: httpx.Response) -> None:
@@ -137,3 +173,6 @@ class Client:
             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.2.0/src/acp_sdk/models/models.py

@@ -0,0 +1,170 @@
+import uuid
+from enum import Enum
+from typing import Any, Literal, Optional, Union
+
+from pydantic import AnyUrl, BaseModel, ConfigDict, Field
+
+from acp_sdk.models.errors import Error
+
+
+class Metadata(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class AnyModel(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class MessagePart(BaseModel):
+    name: Optional[str] = None
+    content_type: str
+    content: Optional[str] = None
+    content_encoding: Optional[Literal["plain", "base64"]] = "plain"
+    content_url: Optional[AnyUrl] = None
+
+    model_config = ConfigDict(extra="forbid")
+
+    def model_post_init(self, __context: Any) -> None:
+        if self.content is None and self.content_url is None:
+            raise ValueError("Either content or content_url must be provided")
+        if self.content is not None and self.content_url is not None:
+            raise ValueError("Only one of content or content_url can be provided")
+
+
+class Artifact(MessagePart):
+    name: str
+
+
+class Message(BaseModel):
+    parts: list[MessagePart]
+
+    def __add__(self, other: "Message") -> "Message":
+        if not isinstance(other, Message):
+            raise TypeError(f"Cannot concatenate Message with {type(other).__name__}")
+        return Message(*(self.parts + other.parts))
+
+    def __str__(self) -> str:
+        return "".join(
+            part.content for part in self.parts if part.content is not None and part.content_type == "text/plain"
+        )
+
+
+AgentName = str
+SessionId = uuid.UUID
+RunId = uuid.UUID
+
+
+class RunMode(str, Enum):
+    SYNC = "sync"
+    ASYNC = "async"
+    STREAM = "stream"
+
+
+class RunStatus(str, Enum):
+    CREATED = "created"
+    IN_PROGRESS = "in-progress"
+    AWAITING = "awaiting"
+    CANCELLING = "cancelling"
+    CANCELLED = "cancelled"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+    @property
+    def is_terminal(self) -> bool:
+        terminal_states = {RunStatus.COMPLETED, RunStatus.FAILED, RunStatus.CANCELLED}
+        return self in terminal_states
+
+
+class AwaitRequest(BaseModel):
+    type: Literal["placeholder"] = "placeholder"
+
+
+class AwaitResume(BaseModel):
+    pass
+
+
+class Run(BaseModel):
+    run_id: RunId = Field(default_factory=uuid.uuid4)
+    agent_name: AgentName
+    session_id: SessionId | None = None
+    status: RunStatus = RunStatus.CREATED
+    await_request: AwaitRequest | None = None
+    outputs: list[Message] = []
+    error: Error | None = None
+
+
+class MessageCreatedEvent(BaseModel):
+    type: Literal["message.created"] = "message.created"
+    message: Message
+
+
+class MessagePartEvent(BaseModel):
+    type: Literal["message.part"] = "message.part"
+    part: MessagePart
+
+
+class ArtifactEvent(BaseModel):
+    type: Literal["message.part"] = "message.part"
+    part: Artifact
+
+
+class MessageCompletedEvent(BaseModel):
+    type: Literal["message.completed"] = "message.completed"
+    message: Message
+
+
+class AwaitEvent(BaseModel):
+    type: Literal["await"] = "await"
+    await_request: AwaitRequest | None = None
+
+
+class GenericEvent(BaseModel):
+    type: Literal["generic"] = "generic"
+    generic: AnyModel
+
+
+class RunCreatedEvent(BaseModel):
+    type: Literal["run.created"] = "run.created"
+    run: Run
+
+
+class RunInProgressEvent(BaseModel):
+    type: Literal["run.in-progress"] = "run.in-progress"
+    run: Run
+
+
+class RunFailedEvent(BaseModel):
+    type: Literal["run.failed"] = "run.failed"
+    run: Run
+
+
+class RunCancelledEvent(BaseModel):
+    type: Literal["run.cancelled"] = "run.cancelled"
+    run: Run
+
+
+class RunCompletedEvent(BaseModel):
+    type: Literal["run.completed"] = "run.completed"
+    run: Run
+
+
+Event = Union[
+    RunCreatedEvent,
+    RunInProgressEvent,
+    MessageCreatedEvent,
+    ArtifactEvent,
+    MessagePartEvent,
+    MessageCompletedEvent,
+    AwaitEvent,
+    GenericEvent,
+    RunCancelledEvent,
+    RunFailedEvent,
+    RunCompletedEvent,
+    MessagePartEvent,
+]
+
+
+class Agent(BaseModel):
+    name: str
+    description: str | None = None
+    metadata: Metadata = Metadata()