acp-sdk 0.3.3__py3-none-any.whl → 0.5.0__py3-none-any.whl

acp_sdk/client/client.py

@@ -31,6 +31,9 @@ from acp_sdk.models import (
     RunResumeResponse,
     SessionId,
 )
+from acp_sdk.models.models import MessagePart
+
+Input = list[Message] | Message | list[MessagePart] | MessagePart | list[str] | str
 
 
 class Client:
@@ -79,14 +82,15 @@ class Client:
     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())
+        response = AgentReadResponse.model_validate(response.json())
+        return Agent(**response.model_dump())
 
-    async def run_sync(self, *, agent: AgentName, inputs: list[Message]) -> Run:
+    async def run_sync(self, input: Input, *, agent: AgentName) -> Run:
         response = await self._client.post(
             "/runs",
             content=RunCreateRequest(
                 agent_name=agent,
-                inputs=inputs,
+                inputs=self._unify_inputs(input),
                 mode=RunMode.SYNC,
                 session_id=self._session_id,
             ).model_dump_json(),
@@ -94,14 +98,14 @@ class Client:
         self._raise_error(response)
         response = RunCreateResponse.model_validate(response.json())
         self._set_session(response)
-        return response
+        return Run(**response.model_dump())
 
-    async def run_async(self, *, agent: AgentName, inputs: list[Message]) -> Run:
+    async def run_async(self, input: Input, *, agent: AgentName) -> Run:
         response = await self._client.post(
             "/runs",
             content=RunCreateRequest(
                 agent_name=agent,
-                inputs=inputs,
+                inputs=self._unify_inputs(input),
                 mode=RunMode.ASYNC,
                 session_id=self._session_id,
             ).model_dump_json(),
@@ -109,16 +113,16 @@ class Client:
         self._raise_error(response)
         response = RunCreateResponse.model_validate(response.json())
         self._set_session(response)
-        return response
+        return Run(**response.model_dump())
 
-    async def run_stream(self, *, agent: AgentName, inputs: list[Message]) -> AsyncIterator[Event]:
+    async def run_stream(self, input: Input, *, agent: AgentName) -> AsyncIterator[Event]:
         async with aconnect_sse(
             self._client,
             "POST",
             "/runs",
             content=RunCreateRequest(
                 agent_name=agent,
-                inputs=inputs,
+                inputs=self._unify_inputs(input),
                 mode=RunMode.STREAM,
                 session_id=self._session_id,
             ).model_dump_json(),
@@ -136,25 +140,28 @@ class Client:
     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())
+        response = RunCancelResponse.model_validate(response.json())
+        return Run(**response.model_dump())
 
-    async def run_resume_sync(self, *, run_id: RunId, await_resume: AwaitResume) -> Run:
+    async def run_resume_sync(self, await_resume: AwaitResume, *, run_id: RunId) -> Run:
         response = await self._client.post(
             f"/runs/{run_id}",
             content=RunResumeRequest(await_resume=await_resume, mode=RunMode.SYNC).model_dump_json(),
         )
         self._raise_error(response)
-        return RunResumeResponse.model_validate(response.json())
+        response = RunResumeResponse.model_validate(response.json())
+        return Run(**response.model_dump())
 
-    async def run_resume_async(self, *, run_id: RunId, await_resume: AwaitResume) -> Run:
+    async def run_resume_async(self, await_resume: AwaitResume, *, run_id: RunId) -> Run:
         response = await self._client.post(
             f"/runs/{run_id}",
             content=RunResumeRequest(await_resume=await_resume, mode=RunMode.ASYNC).model_dump_json(),
         )
         self._raise_error(response)
-        return RunResumeResponse.model_validate(response.json())
+        response = RunResumeResponse.model_validate(response.json())
+        return Run(**response.model_dump())
 
-    async def run_resume_stream(self, *, run_id: RunId, await_resume: AwaitResume) -> AsyncIterator[Event]:
+    async def run_resume_stream(self, await_resume: AwaitResume, *, run_id: RunId) -> AsyncIterator[Event]:
         async with aconnect_sse(
             self._client,
             "POST",
@@ -183,3 +190,24 @@ class Client:
 
     def _set_session(self, run: Run) -> None:
         self._session_id = run.session_id
+
+    def _unify_inputs(self, input: Input) -> list[Message]:
+        if isinstance(input, list):
+            if len(input) == 0:
+                return []
+            if all(isinstance(item, Message) for item in input):
+                return input
+            elif all(isinstance(item, MessagePart) for item in input):
+                return [Message(parts=input)]
+            elif all(isinstance(item, str) for item in input):
+                return [Message(parts=[MessagePart(content=content) for content in input])]
+            else:
+                raise RuntimeError("List with mixed types is not supported")
+        else:
+            if isinstance(input, str):
+                input = MessagePart(content=input)
+            if isinstance(input, MessagePart):
+                input = Message(parts=[input])
+            if isinstance(input, Message):
+                input = [input]
+            return input

acp_sdk/server/app.py

@@ -1,8 +1,10 @@
 from collections.abc import AsyncGenerator
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import asynccontextmanager
+from datetime import datetime, timedelta
 from enum import Enum
 
+from cachetools import TTLCache
 from fastapi import FastAPI, HTTPException, status
 from fastapi.encoders import jsonable_encoder
 from fastapi.responses import JSONResponse, StreamingResponse
@@ -45,7 +47,7 @@ class Headers(str, Enum):
     RUN_ID = "Run-ID"
 
 
-def create_app(*agents: Agent) -> FastAPI:
+def create_app(*agents: Agent, run_limit: int = 1000, run_ttl: timedelta = timedelta(hours=1)) -> FastAPI:
     executor: ThreadPoolExecutor
 
     @asynccontextmanager
@@ -60,8 +62,8 @@ def create_app(*agents: Agent) -> FastAPI:
     FastAPIInstrumentor.instrument_app(app)
 
     agents: dict[AgentName, Agent] = {agent.name: agent for agent in agents}
-    runs: dict[RunId, RunBundle] = {}
-    sessions: dict[SessionId, Session] = {}
+    runs: TTLCache[RunId, RunBundle] = TTLCache(maxsize=run_limit, ttl=run_ttl, timer=datetime.now)
+    sessions: TTLCache[SessionId, Session] = TTLCache(maxsize=run_limit, ttl=run_ttl, timer=datetime.now)
 
     app.exception_handler(ACPError)(acp_error_handler)
     app.exception_handler(StarletteHTTPException)(http_exception_handler)

acp_sdk/server/bundle.py

@@ -3,7 +3,7 @@ import logging
 from collections.abc import AsyncGenerator
 from concurrent.futures import ThreadPoolExecutor
 
-from pydantic import ValidationError
+from pydantic import BaseModel, ValidationError
 
 from acp_sdk.instrumentation import get_tracer
 from acp_sdk.models import (
@@ -88,6 +88,13 @@ class RunBundle:
             run_logger = logging.LoggerAdapter(logger, {"run_id": str(self.run.run_id)})
 
             in_message = False
+
+            async def flush_message() -> None:
+                nonlocal in_message
+                if in_message:
+                    await self.emit(MessageCompletedEvent(message=self.run.outputs[-1]))
+                    in_message = False
+
             try:
                 await self.emit(RunCreatedEvent(run=self.run))
 
@@ -103,7 +110,9 @@ class RunBundle:
                 while True:
                     next = await generator.asend(await_resume)
 
-                    if isinstance(next, MessagePart):
+                    if isinstance(next, (MessagePart, str)):
+                        if isinstance(next, str):
+                            next = MessagePart(content=next)
                         if not in_message:
                             self.run.outputs.append(Message(parts=[]))
                             in_message = True
@@ -111,9 +120,7 @@ class RunBundle:
                         self.run.outputs[-1].parts.append(next)
                         await self.emit(MessagePartEvent(part=next))
                     elif isinstance(next, Message):
-                        if in_message:
-                            await self.emit(MessageCompletedEvent(message=self.run.outputs[-1]))
-                            in_message = False
+                        await flush_message()
                         self.run.outputs.append(next)
                         await self.emit(MessageCreatedEvent(message=next))
                         for part in next.parts:
@@ -130,7 +137,9 @@ class RunBundle:
                     elif isinstance(next, Error):
                         raise ACPError(error=next)
                     elif next is None:
-                        pass  # Do nothing
+                        await flush_message()
+                    elif isinstance(next, BaseModel):
+                        await self.emit(GenericEvent(generic=AnyModel(**next.model_dump())))
                     else:
                         try:
                             generic = AnyModel.model_validate(next)
@@ -138,8 +147,7 @@ class RunBundle:
                         except ValidationError:
                             raise TypeError("Invalid yield")
             except StopAsyncIteration:
-                if in_message:
-                    await self.emit(MessageCompletedEvent(message=self.run.outputs[-1]))
+                await flush_message()
                 self.run.status = RunStatus.COMPLETED
                 await self.emit(RunCompletedEvent(run=self.run))
                 run_logger.info("Run completed")

acp_sdk/server/errors.py

@@ -33,7 +33,7 @@ def status_code_to_error_code(status_code: int) -> ErrorCode:
 async def acp_error_handler(request: Request, exc: ACPError, *, status_code: int | None = None) -> JSONResponse:
     error = exc.error
     return JSONResponse(
-        status_code=status_code or error_code_to_status_code(error.code), content=error.model_dump_json()
+        status_code=status_code or error_code_to_status_code(error.code), content=error.model_dump(mode="json")
     )
 
 

acp_sdk/server/server.py

@@ -1,6 +1,7 @@
 import asyncio
 import os
 from collections.abc import Awaitable
+from datetime import timedelta
 from typing import Any, Callable
 
 import uvicorn
@@ -42,6 +43,8 @@ class Server:
         self,
         configure_logger: bool = True,
         configure_telemetry: bool = False,
+        run_limit: int = 1000,
+        run_ttl: timedelta = timedelta(hours=1),
         host: str = "127.0.0.1",
         port: int = 8000,
         uds: str | None = None,
@@ -105,7 +108,7 @@ class Server:
             configure_telemetry_func()
 
         config = uvicorn.Config(
-            create_app(*self._agents),
+            create_app(*self._agents, run_limit=run_limit, run_ttl=run_ttl),
             host,
             port,
             uds,

acp_sdk/server/types.py

@@ -1,6 +1,9 @@
 from typing import Any
 
+from pydantic import BaseModel
+
 from acp_sdk.models import AwaitRequest, AwaitResume, Message
+from acp_sdk.models.models import MessagePart
 
-RunYield = Message | AwaitRequest | dict[str | Any] | None
+RunYield = Message | MessagePart | str | AwaitRequest | BaseModel | dict[str | Any] | None
 RunYieldResume = AwaitResume | None

acp_sdk-0.5.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: acp-sdk
+Version: 0.5.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: cachetools>=5.5.2
+Requires-Dist: fastapi[standard]>=0.115.8
+Requires-Dist: httpx-sse>=0.4.0
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: janus>=2.0.0
+Requires-Dist: opentelemetry-api>=1.31.1
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.31.1
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.52b1
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.52b1
+Requires-Dist: opentelemetry-sdk>=1.31.1
+Requires-Dist: pydantic>=2.11.1
+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 according to your Python package manager:
+
+- `uv add acp-sdk`
+- `pip install acp-sdk`
+- `poetry add acp-sdk`
+- ...
+
+## Quickstart
+
+Register an agent and run the server:
+
+```py
+server = Server()
+
+@server.agent()
+async def echo(inputs: list[Message]):
+    """Echoes everything"""
+    for message in inputs:
+        yield message
+
+server.run(port=8000)
+```
+
+From another process, connect to the server and run the agent:
+
+```py
+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)
+
+```
+
+
+➡️ Explore more in our [examples library](/examples/python).

{acp_sdk-0.3.3.dist-info → acp_sdk-0.5.0.dist-info}/RECORD

@@ -3,23 +3,23 @@ acp_sdk/instrumentation.py,sha256=JqSyvILN3sGAfOZrmckQq4-M_4_5alyPn95DK0o5lfA,16
 acp_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 acp_sdk/version.py,sha256=Niy83rgvigB4hL_rR-O4ySvI7dj6xnqkyOe_JTymi9s,73
 acp_sdk/client/__init__.py,sha256=Bca1DORrswxzZsrR2aUFpATuNG2xNSmYvF1Z2WJaVbc,51
-acp_sdk/client/client.py,sha256=lEUs0Oc7MZbKkTF2E6e8Wn3dTW5cMVj6fD8TbuEOMDk,6584
+acp_sdk/client/client.py,sha256=b8hiX7aymhKXOOgdUnhDXlP43Z_67btJg_gIPh4IaQ4,7893
 acp_sdk/models/__init__.py,sha256=numSDBDT1QHx7n_Y3Deb5VOvKWcUBxbOEaMwQBSRHxc,151
 acp_sdk/models/errors.py,sha256=rEyaMVvQuBi7fwWe_d0PGGySYsD3FZTluQ-SkC0yhAs,444
 acp_sdk/models/models.py,sha256=eOoOfftPKbTaLlqZlE4gE1ZwDkrQ_FdRiDx4wSJILP4,6539
 acp_sdk/models/schemas.py,sha256=Kj7drJSR8d-N3KHzu_qTnLdagrMtAyhid5swluuhHTw,645
 acp_sdk/server/__init__.py,sha256=mxBBBFaZuMEUENRMLwp1XZkuLeT9QghcFmNvjnqvAAU,377
 acp_sdk/server/agent.py,sha256=DhcPDPDL9jpDST40K_bInvDXfpF1cwxIhqXzu8z0blU,6203
-acp_sdk/server/app.py,sha256=3QJzGi05DKoIKyTeYYKKQhcYz4qorQKmVI94_guVkEY,6340
-acp_sdk/server/bundle.py,sha256=6LZnxsP1rawxic9CwDAQCsOV1v31qNI9meKXMty_yWg,6260
+acp_sdk/server/app.py,sha256=YcW5kEwmRER9LKRsLt2vNqFso4_nnbWabdjiN-4_0-0,6601
+acp_sdk/server/bundle.py,sha256=nLxQMUCSVzlmEgSUYRunnpD3jO2yE2w1XVvKW6NOTPE,6564
 acp_sdk/server/context.py,sha256=MgnLV6qcDIhc_0BjW7r4Jj1tHts4ZuwpdTGIBnz2Mgo,1036
-acp_sdk/server/errors.py,sha256=IGtpPpb2ChtYvCac8kf_P-RkcY71gBvX0yq97uZWa-w,2104
+acp_sdk/server/errors.py,sha256=GSO8yYIqEeX8Y4Lz86ks35dMTHiQiXuOrLYYx0eXsbI,2110
 acp_sdk/server/logging.py,sha256=Oc8yZigCsuDnHHPsarRzu0RX3NKaLEgpELM2yovGKDI,411
-acp_sdk/server/server.py,sha256=-eT3fmnEsBUN44Spi2EP2eV0l4RAlKa8bzqxnhz16SM,5399
+acp_sdk/server/server.py,sha256=6mIVyURgJvcZCPad1CV8TcgHC2mqyEFCGgGATGyP34Q,5548
 acp_sdk/server/session.py,sha256=0cDr924HC5x2bBNbK9NSKVHAt5A_mi5dK8P4jP_ugq0,629
 acp_sdk/server/telemetry.py,sha256=1BUxNg-xL_Vqgs27PDWNc3HikrQW2lidAtT_FKlp_Qk,1833
-acp_sdk/server/types.py,sha256=E0_9xWwgGzyvJjxtbeBBmSbIPhbbTSXLpHFL5dZDzxI,182
+acp_sdk/server/types.py,sha256=teBNRWSks8XP1SCQKGEtbNWQahVD3RAOPnysTxcQPxI,292
 acp_sdk/server/utils.py,sha256=EfrF9VCyVk3AM_ao-BIB9EzGbfTrh4V2Bz-VFr6f6Sg,351
-acp_sdk-0.3.3.dist-info/METADATA,sha256=X4iVzszNG3pWp7eOLPHz6cxaGI4rmMN8MrtCx1ICTOI,3120
-acp_sdk-0.3.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-acp_sdk-0.3.3.dist-info/RECORD,,
+acp_sdk-0.5.0.dist-info/METADATA,sha256=0Idz5Cn8GmBGtSnDUzzbLi3kmv-EGE6_vJVzbbP788k,1654
+acp_sdk-0.5.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+acp_sdk-0.5.0.dist-info/RECORD,,

acp_sdk-0.3.3.dist-info/METADATA

@@ -1,99 +0,0 @@
-Metadata-Version: 2.4
-Name: acp-sdk
-Version: 0.3.3
-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: fastapi[standard]>=0.115.8
-Requires-Dist: httpx-sse>=0.4.0
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: janus>=2.0.0
-Requires-Dist: opentelemetry-api>=1.31.1
-Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.31.1
-Requires-Dist: opentelemetry-instrumentation-fastapi>=0.52b1
-Requires-Dist: opentelemetry-instrumentation-httpx>=0.52b1
-Requires-Dist: opentelemetry-sdk>=1.31.1
-Requires-Dist: pydantic>=2.11.1
-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 with:
-
-```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 everything"}
-        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.
-
-
-