acp-sdk 0.1.0rc8__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.0rc8 → 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", inputs=[Message(TextMessagePart(content="Howdy!"))])
-        print(run.outputs)
+        run = await client.run_sync(agent="echo", inputs=[Message(parts=[MessagePart(content="Howdy!")])])
+        print(run)
 
 
 if __name__ == "__main__":

{acp_sdk-0.1.0rc8 → acp_sdk-0.2.0}/examples/clients/session.py

@@ -3,15 +3,15 @@ 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, client.session() as session:
-        run = await session.run_sync(agent="historian", inputs=[Message(TextMessagePart(content="Howdy!"))])
-        run = await session.run_sync(agent="historian", inputs=[Message(TextMessagePart(content="Howdy again!"))])
-        print(run.outputs)
+        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__":

{acp_sdk-0.1.0rc8 → acp_sdk-0.2.0}/examples/clients/simple.py

@@ -3,13 +3,15 @@ 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", inputs=[Message(TextMessagePart(content="Howdy!"))])
+        run = await client.run_sync(
+            agent="echo", inputs=[Message(parts=[MessagePart(content="Howdy!", content_type="text/plain")])]
+        )
         print(run.outputs)
 
 

{acp_sdk-0.1.0rc8 → 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", inputs=[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.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.0rc8 → acp_sdk-0.2.0}/pyproject.toml

@@ -1,9 +1,11 @@
 [project]
 name = "acp-sdk"
-version = "0.1.0rc8"
+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.1.0rc8 → acp_sdk-0.2.0}/src/acp_sdk/client/client.py

@@ -16,14 +16,14 @@ from acp_sdk.models import (
     AgentReadResponse,
     AgentsListResponse,
     AwaitResume,
-    CreatedEvent,
     Error,
+    Event,
     Message,
     Run,
     RunCancelResponse,
+    RunCreatedEvent,
     RunCreateRequest,
     RunCreateResponse,
-    RunEvent,
     RunId,
     RunMode,
     RunResumeRequest,
@@ -107,7 +107,7 @@ class Client:
         self._set_session(response)
         return response
 
-    async def run_stream(self, *, agent: AgentName, inputs: list[Message]) -> AsyncIterator[RunEvent]:
+    async def run_stream(self, *, agent: AgentName, inputs: list[Message]) -> AsyncIterator[Event]:
         async with aconnect_sse(
             self._client,
             "POST",
@@ -120,7 +120,7 @@ class Client:
             ).model_dump_json(),
         ) as event_source:
             async for event in self._validate_stream(event_source):
-                if isinstance(event, CreatedEvent):
+                if isinstance(event, RunCreatedEvent):
                     self._set_session(event.run)
                 yield event
 
@@ -150,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",
@@ -163,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:

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()

{acp_sdk-0.1.0rc8 → acp_sdk-0.2.0}/src/acp_sdk/server/__init__.py

@@ -1,4 +1,5 @@
 from acp_sdk.server.agent import Agent as Agent
+from acp_sdk.server.agent import agent as agent
 from acp_sdk.server.app import create_app as create_app
 from acp_sdk.server.context import Context as Context
 from acp_sdk.server.server import Server as Server

{acp_sdk-0.1.0rc8 → acp_sdk-0.2.0}/src/acp_sdk/server/agent.py

@@ -3,6 +3,7 @@ import asyncio
 import inspect
 from collections.abc import AsyncGenerator, Coroutine, Generator
 from concurrent.futures import ThreadPoolExecutor
+from typing import Callable
 
 import janus
 
@@ -98,3 +99,80 @@ class Agent(abc.ABC):
             context.yield_sync(self.run(input, context))
         finally:
             context.shutdown()
+
+
+def agent(
+    name: str | None = None,
+    description: str | None = None,
+    *,
+    metadata: Metadata | None = None,
+) -> Callable[[Callable], Agent]:
+    """Decorator to create an agent."""
+
+    def decorator(fn: Callable) -> Agent:
+        signature = inspect.signature(fn)
+        parameters = list(signature.parameters.values())
+
+        if len(parameters) == 0:
+            raise TypeError("The agent function must have at least 'input' argument")
+        if len(parameters) > 2:
+            raise TypeError("The agent function must have only 'input' and 'context' arguments")
+        if len(parameters) == 2 and parameters[1].name != "context":
+            raise TypeError("The second argument of the agent function must be 'context'")
+
+        has_context_param = len(parameters) == 2
+
+        class DecoratorAgentBase(Agent):
+            @property
+            def name(self) -> str:
+                return name or fn.__name__
+
+            @property
+            def description(self) -> str:
+                return description or fn.__doc__ or ""
+
+            @property
+            def metadata(self) -> Metadata:
+                return metadata or Metadata()
+
+        agent: Agent
+        if inspect.isasyncgenfunction(fn):
+
+            class AsyncGenDecoratorAgent(DecoratorAgentBase):
+                async def run(self, input: Message, context: Context) -> AsyncGenerator[RunYield, RunYieldResume]:
+                    try:
+                        gen: AsyncGenerator[RunYield, RunYieldResume] = (
+                            fn(input, context) if has_context_param else fn(input)
+                        )
+                        value = None
+                        while True:
+                            value = yield await gen.asend(value)
+                    except StopAsyncIteration:
+                        pass
+
+            agent = AsyncGenDecoratorAgent()
+        elif inspect.iscoroutinefunction(fn):
+
+            class CoroDecoratorAgent(DecoratorAgentBase):
+                async def run(self, input: Message, context: Context) -> Coroutine[RunYield]:
+                    return await (fn(input, context) if has_context_param else fn(input))
+
+            agent = CoroDecoratorAgent()
+        elif inspect.isgeneratorfunction(fn):
+
+            class GenDecoratorAgent(DecoratorAgentBase):
+                def run(self, input: Message, context: Context) -> Generator[RunYield, RunYieldResume]:
+                    yield from (fn(input, context) if has_context_param else fn(input))
+
+            agent = GenDecoratorAgent()
+        else:
+
+            class FuncDecoratorAgent(DecoratorAgentBase):
+                def run(self, input: Message, context: Context) -> RunYield:
+                    return fn(input, context) if has_context_param else fn(input)
+
+            agent = FuncDecoratorAgent()
+
+        return agent
+
+    return decorator