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

acp_sdk-0.5.0/PKG-INFO

@@ -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.5.0/README.md

@@ -0,0 +1,44 @@
+# 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.5.0/docs/_sidebar.md

@@ -0,0 +1,7 @@
+- [Python](/python/)
+
+- Modules
+
+  - [Client](client.md)
+  - [Server](server.md)
+  - [Models](models.md)

acp_sdk-0.5.0/docs/client.md

@@ -0,0 +1,99 @@
+# Client
+
+<!-- TOC -->
+## Table of Contents
+- [Client](#client)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Usage](#usage)
+    - [Setting up a client](#setting-up-a-client)
+    - [Performing discovery](#performing-discovery)
+    - [Running an agent](#running-an-agent)
+    - [Using sessions](#using-sessions)
+<!-- /TOC -->
+
+---
+
+## Overview
+
+The client module provides a thin ACP client that can be integrated into any application that needs to communicate with ACP agents. It provides the following advantages over raw HTTP client:
+
+- Strong typing
+- Error handling
+- Stream decoding
+- Session management
+- Instrumentation
+
+> [!NOTE]
+>
+> Location within the sdk: [client](/python/src/acp_sdk/client)
+
+## Usage
+
+The client is based on the [httpx.AsyncClient](https://www.python-httpx.org/async/). The usage is very similar as demonstrated below.
+
+### Setting up a client
+
+To set up a simple client, simply provide an URL:
+
+```py
+async with Client(base_url="http://localhost:8000") as client:
+  ...
+```
+
+To use advanced HTTP configuration, provide `httpx` async client:
+
+```py
+async with Client(
+  client=httpx.AsyncClient(
+    base_url="http://localhost:8000",
+    headers={"token": "foobar"})
+  ) as client:
+  ...
+```
+
+### Performing discovery
+
+To discover available agents:
+
+```py
+async with Client(base_url="http://localhost:8000") as client:
+  async for agent in client.agents():
+    ...
+```
+
+### Running an agent
+
+Agent run can be invoked in three modes:
+
+```py
+async with Client(base_url="http://localhost:8000") as client:
+  message = Message(parts=[MessagePart(content="Hello")])
+
+  # Async
+  run = await client.run_async(agent_name="agent", inputs=[message])
+  print(run.status)
+
+  # Sync - waits for completion, failure, cancellation or await
+  run = await client.run_sync(agent_name="agent", inputs=[message])
+  print(run.outputs)
+  
+  # Stream - as sync but also receives events
+  async for event in client.run_stream(agent_name="agent", inputs=[message])
+    print(event)
+```
+
+### Using sessions
+
+Sessions are a mechanism to have multi-turn conversations with agents.
+
+To enter a session, create one from the client:
+
+```py
+async with Client(base_url="http://localhost:8000" as client:
+    agents = [agent async for agent in client.agents()]
+
+    async with client.session() as session:
+        for agent in agents:
+            await session.run_sync(agent_name=agent.name, inputs=[Message(parts=[MessagePart(content="Hello!")])])
+```

acp_sdk-0.5.0/docs/index.html

@@ -0,0 +1,104 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>ACP Docs</title>
+    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+    <meta name="description" content="Description" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0" />
+    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css" />
+    <link
+      rel="stylesheet"
+      title="docsify-darklight-theme"
+      href="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/style.min.css"
+    />
+    <style>
+      aside.sidebar {
+        padding-top: 0;
+      }
+      .app-name-link img {
+        filter: invert(var(--docs-logo-color-invert));
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script>
+      function fixLinkFactory() {
+        var main = "https://github.com/i-am-bee/acp/tree/main";
+        var exampleRegex = /^[\/]{0,1}examples\/(.*)/;
+        var srcRegex = /^[\/]{0,1}src\/(.*)/;
+        var docsMatch = /^[\/]{0,1}docs\/(.*)/;
+
+        return function (url) {
+          if (url === "LICENSE") {
+            return main.concat("/LICENSE");
+          }
+          if (url.substring(0, 2) === "./") {
+            url = url.substring(2);
+          }
+          if (url.match(docsMatch)) {
+            url = url.replace(docsMatch, "$1");
+          }
+          if (url.match(exampleRegex) || url.match(srcRegex) || url === "/package.json") {
+            url = main.concat(url);
+          }
+          return url;
+        };
+      }
+
+      var fixLink = fixLinkFactory();
+      var basePath = window.location.pathname.replace(/index.html/gi, "").replace("/#/", "") || "/";
+
+      window.$docsify = {
+        "name": "ACP",
+        "basePath": basePath,
+        "darklightTheme": {
+          "defaultTheme": 'dark',
+          "light": {
+            'docs-logo-color-invert': 0,
+          },
+          "dark": {
+            'docs-logo-color-invert': 1,
+          }
+        },
+        "repo": "i-am-bee/acp",
+        "loadSidebar": true,
+        "subMaxLevel": 2,
+        "auto2top": true,
+        "search": {
+          depth: 6,
+          namespace: "acp",
+        },
+        "flexible-alerts": {
+          important: {
+            label: "Important",
+            icon: "icon-note",
+            className: "note",
+          },
+        },
+        "markdown": {
+          smartypants: true,
+          renderer: {
+            link: function (link, renderer, text) {
+              return this.origin.link.apply(this, [fixLink(link), renderer, text]);
+            },
+            html: function (html) {
+              var regex = /(src|href|srcset)\s*=\s*(['"])[\.]{0,1}\/docs\/(.+?)\2/gi;
+              html = html.replace(regex, "$1=$2" + basePath + "$3$2");
+              return html;
+            },
+          },
+        },
+      };
+    </script>
+    <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+    <script src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/index.min.js"></script>
+    <script src="https://unpkg.com/docsify-plugin-flexible-alerts"></script>
+    <script src="https://unpkg.com/docsify-copy-code@3"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-python.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-sql.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
+  </body>
+</html>

acp_sdk-0.5.0/docs/models.md

@@ -0,0 +1,45 @@
+# Models
+
+<!-- TOC -->
+## Table of Contents
+- [Models](#models)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Core](#core)
+  - [Schemas](#schemas)
+  - [Errors](#errors)
+<!-- /TOC -->
+
+---
+
+## Overview
+
+The models module provides `pydantic` models describing ACP data structures.
+
+> [!NOTE]
+>
+> Location within the sdk: [models](/python/src/acp_sdk/models)
+
+## Core
+
+Core models are used directly by the SDK consumers. They describe ACP structures like `Message`, `MessagePart` or `Run`. 
+
+> [!NOTE]
+>
+> Location within the sdk: [models.models](/python/src/acp_sdk/models/models.py)
+
+## Schemas
+
+Schema models are used by client and server implementations. They describe payloads of HTTP requests and responses.
+
+> [!NOTE]
+>
+> Location within the sdk: [models.schemas](/python/src/acp_sdk/models/schemas.py)
+
+## Errors
+
+Error model describes errors within the system. SDK consumers can encounter errors in various places, during a stream, as part of the `Run` model or raised inside the `ACPError` exception.
+
+> [!NOTE]
+>
+> Location within the sdk: [models.errors](/python/src/acp_sdk/models/errors.py)

acp_sdk-0.5.0/docs/server.md

@@ -0,0 +1,103 @@
+# Server
+
+<!-- TOC -->
+## Table of Contents
+- [Server](#server)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Usage](#usage)
+    - [Running a server](#running-a-server)
+    - [Standalone application](#standalone-application)
+<!-- /TOC -->
+
+---
+
+## Overview
+
+The server module aims to expose arbitrary agents over the Agent Commucation Protocol. Consumers can use this module to avoid protocol-specific technicalities and focus on the agent itself. The modules provides Agent abstractions, FastAPI application factory and Uvicorn-based server.
+
+> [!NOTE]
+>
+> Location within the sdk: [server](/python/src/acp_sdk/server).
+
+## Usage
+
+The SDK provides `Agent` abstract class and `agent` decorator. Arbitrary agent can be created in by either inheritance from the class or by using the decorator on a generator, coroutine or a regular function.
+
+> [!NOTE]
+>
+> Location within the sdk: [server.agent](/python/src/acp_sdk/server/agent.py).
+
+### Running a server
+
+The SDK provides `Server` class as a convenience for developers to easily serve agents over ACP. The server allows to easily create and register agents. It sets up logging and optionally telemetry exporters.
+
+<!-- embedme python/examples/servers/echo.py -->
+
+```py
+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 everything"}
+        await asyncio.sleep(0.5)
+        yield message
+
+
+server.run()
+```
+
+> [!NOTE]
+>
+> Location within the sdk: [server.server](/python/src/acp_sdk/server/server.py).
+
+### Standalone application
+
+The SDK provides `create_app` factory that turns agents into `FastAPI` application. The application implements route handlers, error handlers, unified execution environment and more. The application can be served with arbitrary ASGI compatible server.
+
+<!-- embedme python/examples/servers/standalone.py -->
+
+```py
+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
+#   ...
+
+```
+
+> [!NOTE]
+>
+> Location within the sdk: [server.app](/python/src/acp_sdk/server/app.py).

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

@@ -1,6 +1,6 @@
 [project]
 name = "acp-sdk"
-version = "0.3.3"
+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.3.3 → 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.3.3 → 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)