acp-sdk 0.4.0__tar.gz → 0.5.0__tar.gz

{acp_sdk-0.4.0 → acp_sdk-0.5.0}/PKG-INFO

@@ -1,14 +1,15 @@
 Metadata-Version: 2.4
 Name: acp-sdk
-Version: 0.4.0
+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.28.1
+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
@@ -28,11 +29,12 @@ Agent Communication Protocol SDK for Python provides allows developers to serve
 
 ## Installation
 
-Install with:
+Install according to your Python package manager:
 
-```shell
-pip install acp-sdk
-```
+- `uv add acp-sdk`
+- `pip install acp-sdk`
+- `poetry add acp-sdk`
+- ...
 
 ## Quickstart
 

{acp_sdk-0.4.0 → acp_sdk-0.5.0}/README.md

@@ -8,11 +8,12 @@ Agent Communication Protocol SDK for Python provides allows developers to serve
 
 ## Installation
 
-Install with:
+Install according to your Python package manager:
 
-```shell
-pip install acp-sdk
-```
+- `uv add acp-sdk`
+- `pip install acp-sdk`
+- `poetry add acp-sdk`
+- ...
 
 ## Quickstart
 

{acp_sdk-0.4.0 → acp_sdk-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "acp-sdk"
-version = "0.4.0"
+version = "0.5.0"
 description = "Agent Communication Protocol SDK"
 license = "Apache-2.0"
 readme = "README.md"
@@ -10,7 +10,7 @@ requires-python = ">=3.11, <4.0"
 dependencies = [
     "opentelemetry-api>=1.31.1",
     "pydantic>=2.11.1",
-    "httpx>=0.28.1",
+    "httpx>=0.26.0",
     "httpx-sse>=0.4.0",
     "opentelemetry-instrumentation-httpx>=0.52b1",
     "fastapi[standard]>=0.115.8",
@@ -18,8 +18,12 @@ dependencies = [
     "opentelemetry-instrumentation-fastapi>=0.52b1",
     "opentelemetry-sdk>=1.31.1",
     "janus>=2.0.0",
+    "cachetools>=5.5.2",
 ]
 
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = ["pytest-httpx>=0.35.0"]

{acp_sdk-0.4.0 → acp_sdk-0.5.0}/src/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-0.4.0 → acp_sdk-0.5.0}/src/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-0.4.0 → acp_sdk-0.5.0}/src/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-0.4.0 → acp_sdk-0.5.0}/src/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-0.5.0/src/acp_sdk/server/types.py

@@ -0,0 +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 | MessagePart | str | AwaitRequest | BaseModel | dict[str | Any] | None
+RunYieldResume = AwaitResume | None

{acp_sdk-0.4.0 → acp_sdk-0.5.0}/tests/e2e/fixtures/server.py

@@ -1,6 +1,7 @@
 import base64
 import time
 from collections.abc import AsyncGenerator, AsyncIterator, Generator
+from datetime import timedelta
 from threading import Thread
 
 import pytest
@@ -10,8 +11,9 @@ from acp_sdk.server import Context, Server
 from e2e.config import Config
 
 
-@pytest.fixture(scope="module")
-def server() -> Generator[None]:
+@pytest.fixture(scope="module", params=[timedelta(minutes=1)])
+def server(request: pytest.FixtureRequest) -> Generator[None]:
+    ttl = request.param
     server = Server()
 
     @server.agent()
@@ -74,7 +76,7 @@ def server() -> Generator[None]:
             content_encoding="base64",
         )
 
-    thread = Thread(target=server.run, kwargs={"port": Config.PORT}, daemon=True)
+    thread = Thread(target=server.run, kwargs={"run_ttl": ttl, "port": Config.PORT}, daemon=True)
     thread.start()
 
     time.sleep(1)

{acp_sdk-0.4.0 → acp_sdk-0.5.0}/tests/e2e/test_suites/test_runs.py

@@ -1,4 +1,6 @@
+import asyncio
 import base64
+from datetime import timedelta
 
 import pytest
 from acp_sdk.client import Client
@@ -14,6 +16,7 @@ from acp_sdk.models import (
     RunInProgressEvent,
     RunStatus,
 )
+from acp_sdk.models.errors import ACPError
 from acp_sdk.server import Server
 
 inputs = [Message(parts=[MessagePart(content="Hello!")])]
@@ -22,27 +25,27 @@ await_resume = MessageAwaitResume(message=Message(parts=[]))
 
 @pytest.mark.asyncio
 async def test_run_sync(server: Server, client: Client) -> None:
-    run = await client.run_sync(agent="echo", inputs=inputs)
+    run = await client.run_sync(agent="echo", input=inputs)
     assert run.status == RunStatus.COMPLETED
     assert run.outputs == inputs
 
 
 @pytest.mark.asyncio
 async def test_run_async(server: Server, client: Client) -> None:
-    run = await client.run_async(agent="echo", inputs=inputs)
+    run = await client.run_async(agent="echo", input=inputs)
     assert run.status == RunStatus.CREATED
 
 
 @pytest.mark.asyncio
 async def test_run_stream(server: Server, client: Client) -> None:
-    event_stream = [event async for event in client.run_stream(agent="echo", inputs=inputs)]
+    event_stream = [event async for event in client.run_stream(agent="echo", input=inputs)]
     assert isinstance(event_stream[0], RunCreatedEvent)
     assert isinstance(event_stream[-1], RunCompletedEvent)
 
 
 @pytest.mark.asyncio
 async def test_run_status(server: Server, client: Client) -> None:
-    run = await client.run_async(agent="echo", inputs=inputs)
+    run = await client.run_async(agent="echo", input=inputs)
     while run.status in (RunStatus.CREATED, RunStatus.IN_PROGRESS):
         run = await client.run_status(run_id=run.run_id)
     assert run.status == RunStatus.COMPLETED
@@ -50,7 +53,7 @@ async def test_run_status(server: Server, client: Client) -> None:
 
 @pytest.mark.asyncio
 async def test_failure(server: Server, client: Client) -> None:
-    run = await client.run_sync(agent="failer", inputs=inputs)
+    run = await client.run_sync(agent="failer", input=inputs)
     assert run.status == RunStatus.FAILED
     assert run.error is not None
     assert run.error.code == ErrorCode.INVALID_INPUT
@@ -58,7 +61,7 @@ async def test_failure(server: Server, client: Client) -> None:
 
 @pytest.mark.asyncio
 async def test_run_cancel(server: Server, client: Client) -> None:
-    run = await client.run_sync(agent="awaiter", inputs=inputs)
+    run = await client.run_sync(agent="awaiter", input=inputs)
     assert run.status == RunStatus.AWAITING
     run = await client.run_cancel(run_id=run.run_id)
     assert run.status == RunStatus.CANCELLING
@@ -66,7 +69,7 @@ async def test_run_cancel(server: Server, client: Client) -> None:
 
 @pytest.mark.asyncio
 async def test_run_resume_sync(server: Server, client: Client) -> None:
-    run = await client.run_sync(agent="awaiter", inputs=inputs)
+    run = await client.run_sync(agent="awaiter", input=inputs)
     assert run.status == RunStatus.AWAITING
     assert run.await_request is not None
 
@@ -76,7 +79,7 @@ async def test_run_resume_sync(server: Server, client: Client) -> None:
 
 @pytest.mark.asyncio
 async def test_run_resume_async(server: Server, client: Client) -> None:
-    run = await client.run_sync(agent="awaiter", inputs=inputs)
+    run = await client.run_sync(agent="awaiter", input=inputs)
     assert run.status == RunStatus.AWAITING
     assert run.await_request is not None
 
@@ -86,7 +89,7 @@ async def test_run_resume_async(server: Server, client: Client) -> None:
 
 @pytest.mark.asyncio
 async def test_run_resume_stream(server: Server, client: Client) -> None:
-    run = await client.run_sync(agent="awaiter", inputs=inputs)
+    run = await client.run_sync(agent="awaiter", input=inputs)
     assert run.status == RunStatus.AWAITING
     assert run.await_request is not None
 
@@ -98,15 +101,15 @@ async def test_run_resume_stream(server: Server, client: Client) -> None:
 @pytest.mark.asyncio
 async def test_run_session(server: Server, client: Client) -> None:
     async with client.session() as session:
-        run = await session.run_sync(agent="echo", inputs=inputs)
+        run = await session.run_sync(agent="echo", input=inputs)
         assert run.outputs == inputs
-        run = await session.run_sync(agent="echo", inputs=inputs)
+        run = await session.run_sync(agent="echo", input=inputs)
         assert run.outputs == inputs + inputs + inputs
 
 
 @pytest.mark.asyncio
 async def test_mime_types(server: Server, client: Client) -> None:
-    run = await client.run_sync(agent="mime_types", inputs=inputs)
+    run = await client.run_sync(agent="mime_types", input=inputs)
     assert run.status == RunStatus.COMPLETED
     assert len(run.outputs) == 1
 
@@ -127,7 +130,7 @@ async def test_mime_types(server: Server, client: Client) -> None:
 
 @pytest.mark.asyncio
 async def test_base64_encoding(server: Server, client: Client) -> None:
-    run = await client.run_sync(agent="base64_encoding", inputs=inputs)
+    run = await client.run_sync(agent="base64_encoding", input=inputs)
     assert run.status == RunStatus.COMPLETED
     assert len(run.outputs) == 1
 
@@ -147,7 +150,7 @@ async def test_base64_encoding(server: Server, client: Client) -> None:
 
 @pytest.mark.asyncio
 async def test_artifacts(server: Server, client: Client) -> None:
-    run = await client.run_sync(agent="artifact_producer", inputs=inputs)
+    run = await client.run_sync(agent="artifact_producer", input=inputs)
     assert run.status == RunStatus.COMPLETED
 
     assert len(run.outputs) == 1
@@ -176,7 +179,7 @@ async def test_artifacts(server: Server, client: Client) -> None:
 
 @pytest.mark.asyncio
 async def test_artifact_streaming(server: Server, client: Client) -> None:
-    events = [event async for event in client.run_stream(agent="artifact_producer", inputs=inputs)]
+    events = [event async for event in client.run_stream(agent="artifact_producer", input=inputs)]
 
     assert isinstance(events[0], RunCreatedEvent)
     assert isinstance(events[-1], RunCompletedEvent)
@@ -193,3 +196,32 @@ async def test_artifact_streaming(server: Server, client: Client) -> None:
     assert "text/plain" in artifact_types
     assert "application/json" in artifact_types
     assert "image/png" in artifact_types
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("server", [timedelta(seconds=5)], indirect=True)
+async def test_run_ttl(server: Server, client: Client) -> None:
+    run = await client.run_async(agent="echo", input=inputs)
+    run = await client.run_status(run_id=run.run_id)
+    await asyncio.sleep(6)
+    try:
+        run = await client.run_status(run_id=run.run_id)
+        raise AssertionError("Error expected")
+    except ACPError as e:
+        if e.error.code == ErrorCode.NOT_FOUND:
+            assert True
+        else:
+            raise AssertionError(f"Unexpected error code {e.error.code}")
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("server", [timedelta(seconds=5)], indirect=True)
+async def test_session_ttl(server: Server, client: Client) -> None:
+    async with client.session() as session:
+        run = await session.run_sync(agent="echo", input=inputs)
+        await asyncio.sleep(3)
+        run = await session.run_sync(agent="echo", input=inputs)
+        assert len(run.outputs) == 3
+        await asyncio.sleep(3)
+        run = await session.run_sync(agent="echo", input=inputs)
+        assert len(run.outputs) == 7  # First run shall be forgotten

acp_sdk-0.5.0/tests/unit/client/test_client.py

@@ -0,0 +1,36 @@
+import pytest
+from acp_sdk.client import Client
+from acp_sdk.models import Message, MessagePart, Run, RunCompletedEvent
+from pytest_httpx import HTTPXMock
+
+mock_run = Run(agent_name="mock", outputs=[Message(parts=[MessagePart(content="Hello!")])])
+
+
+@pytest.mark.asyncio
+async def test_run_sync(httpx_mock: HTTPXMock) -> None:
+    httpx_mock.add_response(content=mock_run.model_dump_json())
+
+    async with Client(base_url="http://localhost:8000") as client:
+        run = await client.run_sync("Howdy!", agent="mock")
+        assert run == mock_run
+
+
+@pytest.mark.asyncio
+async def test_run_async(httpx_mock: HTTPXMock) -> None:
+    httpx_mock.add_response(content=mock_run.model_dump_json())
+
+    async with Client(base_url="http://localhost:8000") as client:
+        run = await client.run_async("Howdy!", agent="mock")
+        assert run == mock_run
+
+
+@pytest.mark.asyncio
+async def test_run_stream(httpx_mock: HTTPXMock) -> None:
+    mock_event = RunCompletedEvent(run=mock_run)
+    httpx_mock.add_response(
+        headers={"content-type": "text/event-stream"}, content=f"data: {mock_event.model_dump_json()}\n\n"
+    )
+
+    async with Client(base_url="http://localhost:8000") as client:
+        async for event in client.run_stream("Howdy!", agent="mock"):
+            assert event == mock_event

acp_sdk-0.4.0/src/acp_sdk/server/types.py

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