acp-sdk 1.0.0rc2__py3-none-any.whl → 1.0.0rc4__py3-none-any.whl

acp_sdk/__init__.py

@@ -0,0 +1 @@
+from acp_sdk.models import *  # noqa: F403

acp_sdk/client/client.py

@@ -8,11 +8,13 @@ from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
 from pydantic import TypeAdapter
 
 from acp_sdk.models import (
+    ACPError,
     Agent,
     AgentName,
     AgentReadResponse,
     AgentsListResponse,
     AwaitResume,
+    Error,
     Message,
     Run,
     RunCancelResponse,
@@ -32,7 +34,7 @@ class Client:
 
         self._client = self._init_client(client)
 
-    def _init_client(self, client: httpx.AsyncClient | None = None) -> Self:
+    def _init_client(self, client: httpx.AsyncClient | None = None) -> httpx.AsyncClient:
         client = client or httpx.AsyncClient(base_url=self.base_url)
         HTTPXClientInstrumentor.instrument_client(client)
         return client
@@ -51,11 +53,13 @@ class Client:
 
     async def agents(self) -> AsyncIterator[Agent]:
         response = await self._client.get("/agents")
+        self._raise_error(response)
         for agent in AgentsListResponse.model_validate(response.json()).agents:
             yield agent
 
     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())
 
     async def run_sync(self, *, agent: AgentName, input: Message) -> Run:
@@ -63,6 +67,7 @@ class Client:
             "/runs",
             json=RunCreateRequest(agent_name=agent, input=input, mode=RunMode.SYNC).model_dump(),
         )
+        self._raise_error(response)
         return RunCreateResponse.model_validate(response.json())
 
     async def run_async(self, *, agent: AgentName, input: Message) -> Run:
@@ -70,6 +75,7 @@ class Client:
             "/runs",
             json=RunCreateRequest(agent_name=agent, input=input, mode=RunMode.ASYNC).model_dump(),
         )
+        self._raise_error(response)
         return RunCreateResponse.model_validate(response.json())
 
     async def run_stream(self, *, agent: AgentName, input: Message) -> AsyncIterator[RunEvent]:
@@ -84,10 +90,12 @@ class Client:
 
     async def run_status(self, *, run_id: RunId) -> Run:
         response = await self._client.get(f"/runs/{run_id}")
+        self._raise_error(response)
         return Run.model_validate(response.json())
 
     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())
 
     async def run_resume_sync(self, *, run_id: RunId, await_: AwaitResume) -> Run:
@@ -95,6 +103,7 @@ class Client:
             f"/runs/{run_id}",
             json=RunResumeRequest(await_=await_, mode=RunMode.SYNC).model_dump(),
         )
+        self._raise_error(response)
         return RunResumeResponse.model_validate(response.json())
 
     async def run_resume_async(self, *, run_id: RunId, await_: AwaitResume) -> Run:
@@ -102,6 +111,7 @@ class Client:
             f"/runs/{run_id}",
             json=RunResumeRequest(await_=await_, mode=RunMode.ASYNC).model_dump(),
         )
+        self._raise_error(response)
         return RunResumeResponse.model_validate(response.json())
 
     async def run_resume_stream(self, *, run_id: RunId, await_: AwaitResume) -> AsyncIterator[RunEvent]:
@@ -121,3 +131,9 @@ class Client:
         async for event in event_source.aiter_sse():
             event = TypeAdapter(RunEvent).validate_json(event.data)
             yield event
+
+    def _raise_error(self, response: httpx.Response) -> None:
+        try:
+            response.raise_for_status()
+        except httpx.HTTPError:
+            raise ACPError(Error.model_validate(response.json()))

acp_sdk/models/__init__.py

@@ -0,0 +1,3 @@
+from acp_sdk.models.errors import *  # noqa: F403
+from acp_sdk.models.models import *  # noqa: F403
+from acp_sdk.models.schemas import *  # noqa: F403

acp_sdk/models/errors.py

@@ -0,0 +1,23 @@
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class ErrorCode(str, Enum):
+    SERVER_ERROR = "server_error"
+    INVALID_INPUT = "invalid_input"
+    NOT_FOUND = "not_found"
+
+
+class Error(BaseModel):
+    code: ErrorCode
+    message: str
+
+
+class ACPError(Exception):
+    def __init__(self, error: Error) -> None:
+        super().__init__()
+        self.error = error
+
+    def __str__(self) -> str:
+        return str(self.error.message)

acp_sdk/{models.py → models/models.py}

@@ -5,10 +5,11 @@ from typing import Any, Literal, Union
 
 from pydantic import AnyUrl, BaseModel, ConfigDict, Field, RootModel
 
+from acp_sdk.models.errors import Error
 
-class ACPError(BaseModel):
-    code: str
-    message: str
+
+class Metadata(BaseModel):
+    model_config = ConfigDict(extra="allow")
 
 
 class AnyModel(BaseModel):
@@ -97,7 +98,7 @@ class Run(BaseModel):
     status: RunStatus = RunStatus.CREATED
     await_: Await | None = Field(None, alias="await")
     output: Message | None = None
-    error: ACPError | None = None
+    error: Error | None = None
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -174,42 +175,7 @@ RunEvent = Union[
 ]
 
 
-class RunCreateRequest(BaseModel):
-    agent_name: AgentName
-    session_id: SessionId | None = None
-    input: Message
-    mode: RunMode = RunMode.SYNC
-
-
-class RunCreateResponse(Run):
-    pass
-
-
-class RunResumeRequest(BaseModel):
-    await_: AwaitResume = Field(alias="await")
-    mode: RunMode
-
-
-class RunResumeResponse(Run):
-    pass
-
-
-class RunReadResponse(Run):
-    pass
-
-
-class RunCancelResponse(Run):
-    pass
-
-
 class Agent(BaseModel):
     name: str
     description: str | None = None
-
-
-class AgentsListResponse(BaseModel):
-    agents: list[Agent]
-
-
-class AgentReadResponse(Agent):
-    pass
+    metadata: Metadata = Metadata()

acp_sdk/models/schemas.py

@@ -0,0 +1,39 @@
+from pydantic import BaseModel, Field
+
+from acp_sdk.models.models import Agent, AgentName, AwaitResume, Message, Run, RunMode, SessionId
+
+
+class AgentsListResponse(BaseModel):
+    agents: list[Agent]
+
+
+class AgentReadResponse(Agent):
+    pass
+
+
+class RunCreateRequest(BaseModel):
+    agent_name: AgentName
+    session_id: SessionId | None = None
+    input: Message
+    mode: RunMode = RunMode.SYNC
+
+
+class RunCreateResponse(Run):
+    pass
+
+
+class RunResumeRequest(BaseModel):
+    await_: AwaitResume = Field(alias="await")
+    mode: RunMode
+
+
+class RunResumeResponse(Run):
+    pass
+
+
+class RunReadResponse(Run):
+    pass
+
+
+class RunCancelResponse(Run):
+    pass

acp_sdk/server/__init__.py

@@ -1,2 +1,8 @@
 from acp_sdk.server.agent import Agent as Agent
-from acp_sdk.server.server import create_app as create_app
+from acp_sdk.server.agent import SyncAgent as SyncAgent
+from acp_sdk.server.app import create_app as create_app
+from acp_sdk.server.context import Context as Context
+from acp_sdk.server.context import SyncContext as SyncContext
+from acp_sdk.server.server import Server as Server
+from acp_sdk.server.types import RunYield as RunYield
+from acp_sdk.server.types import RunYieldResume as RunYieldResume

acp_sdk/server/agent.py

@@ -1,14 +1,18 @@
 import abc
+import asyncio
 from collections.abc import AsyncGenerator
+from concurrent.futures import ThreadPoolExecutor
+
+import janus
 
 from acp_sdk.models import (
     AgentName,
-    Await,
-    AwaitResume,
     Message,
     SessionId,
 )
-from acp_sdk.server.context import Context
+from acp_sdk.models.models import Metadata
+from acp_sdk.server.context import Context, SyncContext
+from acp_sdk.server.types import RunYield, RunYieldResume
 
 
 class Agent(abc.ABC):
@@ -20,11 +24,51 @@ class Agent(abc.ABC):
     def description(self) -> str:
         return ""
 
+    @property
+    def metadata(self) -> Metadata:
+        return Metadata()
+
     @abc.abstractmethod
-    def run(self, input: Message, *, context: Context) -> AsyncGenerator[Message | Await, AwaitResume]:
+    def run(
+        self, input: Message, context: Context, executor: ThreadPoolExecutor
+    ) -> AsyncGenerator[RunYield, RunYieldResume]:
         pass
 
     async def session(self, session_id: SessionId | None) -> SessionId | None:
         if session_id:
             raise NotImplementedError()
         return None
+
+
+class SyncAgent(Agent):
+    @abc.abstractmethod
+    def run_sync(self, input: Message, context: SyncContext, executor: ThreadPoolExecutor) -> RunYield | None:
+        pass
+
+    async def run(
+        self, input: Message, context: Context, executor: ThreadPoolExecutor
+    ) -> AsyncGenerator[RunYield, RunYieldResume]:
+        yield_queue: janus.Queue[RunYield] = janus.Queue()
+        yield_resume_queue: janus.Queue[RunYieldResume] = janus.Queue()
+
+        run_future = asyncio.get_running_loop().run_in_executor(
+            executor,
+            self.run_sync,
+            input,
+            SyncContext(
+                session_id=context.session_id,
+                yield_queue=yield_queue.sync_q,
+                yield_resume_queue=yield_resume_queue.sync_q,
+            ),
+            executor,
+        )
+
+        while True:
+            yield_task = asyncio.create_task(yield_queue.async_q.get())
+            done, _ = await asyncio.wait([yield_task, run_future], return_when=asyncio.FIRST_COMPLETED)
+            if yield_task in done:
+                resume = yield await yield_task
+                await yield_resume_queue.async_q.put(resume)
+            if run_future in done:
+                yield await run_future
+                break

acp_sdk/server/app.py

@@ -0,0 +1,161 @@
+import asyncio
+from collections.abc import AsyncGenerator
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException, status
+from fastapi.responses import JSONResponse, StreamingResponse
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+
+from acp_sdk.models import (
+    Agent as AgentModel,
+)
+from acp_sdk.models import (
+    AgentName,
+    AgentReadResponse,
+    AgentsListResponse,
+    Run,
+    RunCancelResponse,
+    RunCreateRequest,
+    RunCreateResponse,
+    RunId,
+    RunMode,
+    RunReadResponse,
+    RunResumeRequest,
+    RunResumeResponse,
+    RunStatus,
+)
+from acp_sdk.models.errors import ACPError
+from acp_sdk.server.agent import Agent
+from acp_sdk.server.bundle import RunBundle
+from acp_sdk.server.errors import (
+    RequestValidationError,
+    StarletteHTTPException,
+    acp_error_handler,
+    catch_all_exception_handler,
+    http_exception_handler,
+    validation_exception_handler,
+)
+from acp_sdk.server.utils import stream_sse
+
+
+def create_app(*agents: Agent) -> FastAPI:
+    executor: ThreadPoolExecutor
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
+        nonlocal executor
+        with ThreadPoolExecutor(max_workers=5) as exec:
+            executor = exec
+            yield
+
+    app = FastAPI(lifespan=lifespan)
+
+    FastAPIInstrumentor.instrument_app(app)
+
+    agents: dict[AgentName, Agent] = {agent.name: agent for agent in agents}
+    runs: dict[RunId, RunBundle] = {}
+
+    app.exception_handler(ACPError)(acp_error_handler)
+    app.exception_handler(StarletteHTTPException)(http_exception_handler)
+    app.exception_handler(RequestValidationError)(validation_exception_handler)
+    app.exception_handler(Exception)(catch_all_exception_handler)
+
+    def find_run_bundle(run_id: RunId) -> RunBundle:
+        bundle = runs.get(run_id)
+        if not bundle:
+            raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+        return bundle
+
+    def find_agent(agent_name: AgentName) -> Agent:
+        agent = agents.get(agent_name, None)
+        if not agent:
+            raise HTTPException(status_code=404, detail=f"Agent {agent_name} not found")
+        return agent
+
+    @app.get("/agents")
+    async def list_agents() -> AgentsListResponse:
+        return AgentsListResponse(
+            agents=[
+                AgentModel(name=agent.name, description=agent.description, metadata=agent.metadata)
+                for agent in agents.values()
+            ]
+        )
+
+    @app.get("/agents/{name}")
+    async def read_agent(name: AgentName) -> AgentReadResponse:
+        agent = find_agent(name)
+        return AgentModel(name=agent.name, description=agent.description, metadata=agent.metadata)
+
+    @app.post("/runs")
+    async def create_run(request: RunCreateRequest) -> RunCreateResponse:
+        agent = find_agent(request.agent_name)
+        bundle = RunBundle(
+            agent=agent,
+            run=Run(
+                agent_name=agent.name,
+                session_id=request.session_id,
+            ),
+        )
+
+        nonlocal executor
+        bundle.task = asyncio.create_task(bundle.execute(request.input, executor=executor))
+        runs[bundle.run.run_id] = bundle
+
+        match request.mode:
+            case RunMode.STREAM:
+                return StreamingResponse(
+                    stream_sse(bundle),
+                    media_type="text/event-stream",
+                )
+            case RunMode.SYNC:
+                await bundle.join()
+                return bundle.run
+            case RunMode.ASYNC:
+                return JSONResponse(
+                    status_code=status.HTTP_202_ACCEPTED,
+                    content=bundle.run.model_dump(),
+                )
+            case _:
+                raise NotImplementedError()
+
+    @app.get("/runs/{run_id}")
+    async def read_run(run_id: RunId) -> RunReadResponse:
+        bundle = find_run_bundle(run_id)
+        return bundle.run
+
+    @app.post("/runs/{run_id}")
+    async def resume_run(run_id: RunId, request: RunResumeRequest) -> RunResumeResponse:
+        bundle = find_run_bundle(run_id)
+        bundle.stream_queue = asyncio.Queue()  # TODO improve
+        await bundle.await_queue.put(request.await_)
+        match request.mode:
+            case RunMode.STREAM:
+                return StreamingResponse(
+                    stream_sse(bundle),
+                    media_type="text/event-stream",
+                )
+            case RunMode.SYNC:
+                await bundle.join()
+                return bundle.run
+            case RunMode.ASYNC:
+                return JSONResponse(
+                    status_code=status.HTTP_202_ACCEPTED,
+                    content=bundle.run.model_dump(),
+                )
+            case _:
+                raise NotImplementedError()
+
+    @app.post("/runs/{run_id}/cancel")
+    async def cancel_run(run_id: RunId) -> RunCancelResponse:
+        bundle = find_run_bundle(run_id)
+        if bundle.run.status.is_terminal:
+            raise HTTPException(
+                status_code=403,
+                detail=f"Run with terminal status {bundle.run.status} can't be cancelled",
+            )
+        bundle.task.cancel()
+        bundle.run.status = RunStatus.CANCELLING
+        return JSONResponse(status_code=status.HTTP_202_ACCEPTED, content=bundle.run.model_dump())
+
+    return app

acp_sdk/server/bundle.py

@@ -1,12 +1,12 @@
 import asyncio
 import logging
 from collections.abc import AsyncGenerator
+from concurrent.futures import ThreadPoolExecutor
 
 from opentelemetry import trace
 from pydantic import ValidationError
 
 from acp_sdk.models import (
-    ACPError,
     AnyModel,
     Await,
     AwaitEvent,
@@ -14,6 +14,7 @@ from acp_sdk.models import (
     CancelledEvent,
     CompletedEvent,
     CreatedEvent,
+    Error,
     FailedEvent,
     GenericEvent,
     InProgressEvent,
@@ -23,10 +24,10 @@ from acp_sdk.models import (
     RunEvent,
     RunStatus,
 )
+from acp_sdk.models.errors import ErrorCode
 from acp_sdk.server.agent import Agent
 from acp_sdk.server.context import Context
-
-logger = logging.getLogger("uvicorn.error")
+from acp_sdk.server.logging import logger
 
 
 class RunBundle:
@@ -68,7 +69,7 @@ class RunBundle:
     async def join(self) -> None:
         await self.await_or_terminate_event.wait()
 
-    async def execute(self, input: Message) -> None:
+    async def execute(self, input: Message, *, executor: ThreadPoolExecutor) -> None:
         with trace.get_tracer(__name__).start_as_current_span("execute"):
             run_logger = logging.LoggerAdapter(logger, {"run_id": self.run.run_id})
 
@@ -77,7 +78,9 @@ class RunBundle:
                 self.run.session_id = await self.agent.session(self.run.session_id)
                 run_logger.info("Session loaded")
 
-                generator = self.agent.run(input=input, context=Context(session_id=self.run.session_id))
+                generator = self.agent.run(
+                    input=input, context=Context(session_id=self.run.session_id), executor=executor
+                )
                 run_logger.info("Run started")
 
                 self.run.status = RunStatus.IN_PROGRESS
@@ -122,7 +125,7 @@ class RunBundle:
                 await self.emit(CancelledEvent(run=self.run))
                 run_logger.info("Run cancelled")
             except Exception as e:
-                self.run.error = ACPError(code="unspecified", message=str(e))
+                self.run.error = Error(code=ErrorCode.SERVER_ERROR, message=str(e))
                 self.run.status = RunStatus.FAILED
                 await self.emit(FailedEvent(run=self.run))
                 run_logger.exception("Run failed")

acp_sdk/server/context.py

@@ -1,6 +1,26 @@
+import janus
+
 from acp_sdk.models import SessionId
+from acp_sdk.server.types import RunYield, RunYieldResume
 
 
 class Context:
     def __init__(self, *, session_id: SessionId | None = None) -> None:
         self.session_id = session_id
+
+
+class SyncContext(Context):
+    def __init__(
+        self,
+        *,
+        session_id: SessionId | None = None,
+        yield_queue: janus.SyncQueue[RunYield],
+        yield_resume_queue: janus.SyncQueue[RunYieldResume],
+    ) -> None:
+        super().__init__(session_id=session_id)
+        self._yield_queue = yield_queue
+        self._yield_resume_queue = yield_resume_queue
+
+    def yield_(self, data: RunYield) -> RunYieldResume:
+        self._yield_queue.put(data)
+        return self._yield_resume_queue.get()

acp_sdk/server/errors.py

@@ -0,0 +1,54 @@
+from fastapi import Request, status
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from acp_sdk.models import Error, ErrorCode
+from acp_sdk.models.errors import ACPError
+from acp_sdk.server.logging import logger
+
+
+def error_code_to_status_code(error_code: ErrorCode) -> int:
+    match error_code:
+        case ErrorCode.NOT_FOUND:
+            return status.HTTP_404_NOT_FOUND
+        case ErrorCode.INVALID_INPUT:
+            return status.HTTP_422_UNPROCESSABLE_ENTITY
+        case _:
+            return status.HTTP_500_INTERNAL_SERVER_ERROR
+
+
+def status_code_to_error_code(status_code: int) -> ErrorCode:
+    match status_code:
+        case status.HTTP_400_BAD_REQUEST:
+            return ErrorCode.INVALID_INPUT
+        case status.HTTP_404_NOT_FOUND:
+            return ErrorCode.NOT_FOUND
+        case status.HTTP_422_UNPROCESSABLE_ENTITY:
+            return ErrorCode.INVALID_INPUT
+        case _:
+            return ErrorCode.SERVER_ERROR
+
+
+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())
+
+
+async def http_exception_handler(request: Request, exc: StarletteHTTPException) -> JSONResponse:
+    return await acp_error_handler(
+        request,
+        ACPError(Error(code=status_code_to_error_code(exc.status_code), message=exc.detail)),
+        status_code=exc.status_code,
+    )
+
+
+async def validation_exception_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
+    return await acp_error_handler(request, ACPError(Error(code=ErrorCode.INVALID_INPUT, message=str(exc))))
+
+
+async def catch_all_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    logger.error(exc)
+    return await acp_error_handler(
+        request, ACPError(Error(code=ErrorCode.SERVER_ERROR, message="An unexpected error occurred"))
+    )

acp_sdk/server/logging.py

@@ -0,0 +1,16 @@
+import logging
+
+from uvicorn.logging import DefaultFormatter
+
+logger = logging.getLogger("acp")
+
+
+def configure_logger() -> None:
+    """Utility that configures the root logger"""
+    root_logger = logging.getLogger()
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(DefaultFormatter(fmt="%(levelprefix)s %(message)s"))
+
+    root_logger.addHandler(handler)
+    root_logger.setLevel(logging.INFO)

acp_sdk/server/server.py

@@ -1,133 +1,110 @@
-import asyncio
-
-from fastapi import FastAPI, HTTPException, status
-from fastapi.responses import JSONResponse, StreamingResponse
-from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
-
-from acp_sdk.models import (
-    Agent as AgentModel,
-)
-from acp_sdk.models import (
-    AgentName,
-    AgentReadResponse,
-    AgentsListResponse,
-    Run,
-    RunCancelResponse,
-    RunCreateRequest,
-    RunCreateResponse,
-    RunId,
-    RunMode,
-    RunReadResponse,
-    RunResumeRequest,
-    RunResumeResponse,
-    RunStatus,
-)
-from acp_sdk.server.agent import Agent
-from acp_sdk.server.bundle import RunBundle
-from acp_sdk.server.telemetry import configure_telemetry
-from acp_sdk.server.utils import stream_sse
-
-
-def create_app(*agents: Agent) -> FastAPI:
-    app = FastAPI(title="acp-agents")
-
-    configure_telemetry()
-    FastAPIInstrumentor.instrument_app(app)
-
-    agents: dict[AgentName, Agent] = {agent.name: agent for agent in agents}
-    runs: dict[RunId, RunBundle] = {}
-
-    def find_run_bundle(run_id: RunId) -> RunBundle:
-        bundle = runs.get(run_id)
-        if not bundle:
-            raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
-        return bundle
-
-    def find_agent(agent_name: AgentName) -> Agent:
-        agent = agents.get(agent_name, None)
-        if not agent:
-            raise HTTPException(status_code=404, detail=f"Agent {agent_name} not found")
-        return agent
-
-    @app.get("/agents")
-    async def list_agents() -> AgentsListResponse:
-        return AgentsListResponse(
-            agents=[AgentModel(name=agent.name, description=agent.description) for agent in agents.values()]
-        )
-
-    @app.get("/agents/{name}")
-    async def read_agent(name: AgentName) -> AgentReadResponse:
-        agent = find_agent(name)
-        return AgentModel(name=agent.name, description=agent.description)
-
-    @app.post("/runs")
-    async def create_run(request: RunCreateRequest) -> RunCreateResponse:
-        agent = find_agent(request.agent_name)
-        bundle = RunBundle(
-            agent=agent,
-            run=Run(
-                agent_name=agent.name,
-                session_id=request.session_id,
-            ),
-        )
-
-        bundle.task = asyncio.create_task(bundle.execute(request.input))
-        runs[bundle.run.run_id] = bundle
-
-        match request.mode:
-            case RunMode.STREAM:
-                return StreamingResponse(
-                    stream_sse(bundle),
-                    media_type="text/event-stream",
-                )
-            case RunMode.SYNC:
-                await bundle.join()
-                return bundle.run
-            case RunMode.ASYNC:
-                return JSONResponse(
-                    status_code=status.HTTP_202_ACCEPTED,
-                    content=bundle.run.model_dump(),
-                )
-            case _:
-                raise NotImplementedError()
-
-    @app.get("/runs/{run_id}")
-    async def read_run(run_id: RunId) -> RunReadResponse:
-        bundle = find_run_bundle(run_id)
-        return bundle.run
-
-    @app.post("/runs/{run_id}")
-    async def resume_run(run_id: RunId, request: RunResumeRequest) -> RunResumeResponse:
-        bundle = find_run_bundle(run_id)
-        bundle.stream_queue = asyncio.Queue()  # TODO improve
-        await bundle.await_queue.put(request.await_)
-        match request.mode:
-            case RunMode.STREAM:
-                return StreamingResponse(
-                    stream_sse(bundle),
-                    media_type="text/event-stream",
-                )
-            case RunMode.SYNC:
-                await bundle.join()
-                return bundle.run
-            case RunMode.ASYNC:
-                return JSONResponse(
-                    status_code=status.HTTP_202_ACCEPTED,
-                    content=bundle.run.model_dump(),
-                )
-            case _:
-                raise NotImplementedError()
-
-    @app.post("/runs/{run_id}/cancel")
-    async def cancel_run(run_id: RunId) -> RunCancelResponse:
-        bundle = find_run_bundle(run_id)
-        if bundle.run.status.is_terminal:
-            raise HTTPException(
-                status_code=403,
-                detail=f"Run with terminal status {bundle.run.status} can't be cancelled",
-            )
-        bundle.task.cancel()
-        bundle.run.status = RunStatus.CANCELLING
-        return JSONResponse(status_code=status.HTTP_202_ACCEPTED, content=bundle.run.model_dump())
-
-    return app
+import inspect
+from collections.abc import AsyncGenerator
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable
+
+from acp_sdk.models import Message
+from acp_sdk.server.agent import Agent, SyncAgent
+from acp_sdk.server.app import create_app
+from acp_sdk.server.context import Context
+from acp_sdk.server.logging import configure_logger as configure_logger_func
+from acp_sdk.server.telemetry import configure_telemetry as configure_telemetry_func
+from acp_sdk.server.types import RunYield, RunYieldResume
+
+
+class Server:
+    def __init__(self) -> None:
+        self.agents: list[Agent] = []
+
+    def agent(self, name: str | None = None, description: str | None = None) -> Callable:
+        """Decorator to register an agent."""
+
+        def decorator(fn: Callable) -> Callable:
+            # check agent's function signature
+            signature = inspect.signature(fn)
+            parameters = list(signature.parameters.values())
+
+            # validate agent's function
+            if inspect.isasyncgenfunction(fn):
+                if len(parameters) != 2:
+                    raise TypeError(
+                        "The agent generator function must have one 'input' argument and one 'context' argument"
+                    )
+            else:
+                if len(parameters) != 2:
+                    raise TypeError("The agent function must have one 'input' argument and one 'context' argument")
+
+            agent: Agent
+            if inspect.isasyncgenfunction(fn):
+
+                class DecoratedAgent(Agent):
+                    @property
+                    def name(self) -> str:
+                        return name or fn.__name__
+
+                    @property
+                    def description(self) -> str:
+                        return description or fn.__doc__ or ""
+
+                    async def run(
+                        self, input: Message, context: Context, executor: ThreadPoolExecutor
+                    ) -> AsyncGenerator[RunYield, RunYieldResume]:
+                        gen: AsyncGenerator[RunYield, RunYieldResume] = fn(input, context)
+                        value = None
+                        while True:
+                            try:
+                                value = yield await gen.asend(value)
+                            except StopAsyncIteration:
+                                break
+
+                agent = DecoratedAgent()
+            elif inspect.iscoroutinefunction(fn):
+
+                class DecoratedAgent(Agent):
+                    @property
+                    def name(self) -> str:
+                        return name or fn.__name__
+
+                    @property
+                    def description(self) -> str:
+                        return description or fn.__doc__ or ""
+
+                    async def run(
+                        self, input: Message, context: Context, executor: ThreadPoolExecutor
+                    ) -> AsyncGenerator[RunYield, RunYieldResume]:
+                        yield await fn(input, context)
+
+                agent = DecoratedAgent()
+            else:
+
+                class DecoratedAgent(SyncAgent):
+                    @property
+                    def name(self) -> str:
+                        return name or fn.__name__
+
+                    @property
+                    def description(self) -> str:
+                        return description or fn.__doc__ or ""
+
+                    def run_sync(self, input: Message, context: Context, executor: ThreadPoolExecutor) -> None:
+                        return fn(input, context)
+
+                agent = DecoratedAgent()
+
+            self.register(agent)
+            return fn
+
+        return decorator
+
+    def register(self, *agents: Agent) -> None:
+        self.agents.extend(agents)
+
+    def run(self, configure_logger: bool = True, configure_telemetry: bool = False, **kwargs: dict[str, Any]) -> None:
+        import uvicorn
+
+        if configure_logger:
+            configure_logger_func()
+        if configure_telemetry:
+            configure_telemetry_func()
+
+        uvicorn.run(create_app(*self.agents), **kwargs)

acp_sdk/server/telemetry.py

@@ -1,9 +1,14 @@
 import logging
 from importlib.metadata import version
-from typing import Any
 
-from opentelemetry import trace
+from opentelemetry import metrics, trace
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
 from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
 from opentelemetry.sdk.resources import (
     SERVICE_NAME,
     SERVICE_NAMESPACE,
@@ -11,36 +16,37 @@ from opentelemetry.sdk.resources import (
     Resource,
 )
 from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExportResult
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
 
-logger = logging.getLogger("uvicorn.error")
-
-
-class SilentOTLPSpanExporter(OTLPSpanExporter):
-    def export(self, spans: Any) -> SpanExportResult:
-        try:
-            return super().export(spans)
-        except Exception as e:
-            logger.warning(f"OpenTelemetry Exporter failed silently: {e}")
-            return SpanExportResult.FAILURE
+root_logger = logging.getLogger()
 
 
 def configure_telemetry() -> None:
-    current_provider = trace.get_tracer_provider()
-
-    # Detect default provider and override
-    if isinstance(current_provider, trace.ProxyTracerProvider):
-        provider = TracerProvider(
-            resource=Resource(
-                attributes={
-                    SERVICE_NAME: "acp-server",
-                    SERVICE_NAMESPACE: "acp",
-                    SERVICE_VERSION: version("acp-sdk"),
-                }
-            )
-        )
-
-        processor = BatchSpanProcessor(SilentOTLPSpanExporter())
-        provider.add_span_processor(processor)
-
-        trace.set_tracer_provider(provider)
+    """Utility that configures opentelemetry with OTLP exporter"""
+
+    resource = Resource(
+        attributes={
+            SERVICE_NAME: "acp-server",
+            SERVICE_NAMESPACE: "acp",
+            SERVICE_VERSION: version("acp-sdk"),
+        }
+    )
+
+    # Traces
+    provider = TracerProvider(resource=resource)
+    processor = BatchSpanProcessor(OTLPSpanExporter())
+    provider.add_span_processor(processor)
+    trace.set_tracer_provider(provider)
+
+    # Metrics
+    meter_provider = MeterProvider(
+        resource=resource,
+        metric_readers=[PeriodicExportingMetricReader(OTLPMetricExporter())],
+    )
+    metrics.set_meter_provider(meter_provider)
+
+    # Logs
+    logger_provider = LoggerProvider(resource=resource)
+    processor = BatchLogRecordProcessor(OTLPLogExporter())
+    logger_provider.add_log_record_processor(processor)
+    root_logger.addHandler(LoggingHandler(logger_provider=logger_provider))

acp_sdk/server/types.py

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

acp_sdk-1.0.0rc4.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: acp-sdk
+Version: 1.0.0rc4
+Summary: Agent Communication Protocol SDK
+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]
+```
+
+## Overview
+
+### Client
+
+The `client` submodule exposes [httpx]() 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", input=Message(TextMessagePart(content="Howdy!")))
+    print(run.output)
+```
+
+### Server
+
+The `server` submodule exposes [fastapi] application factory that makes it easy to expose any agent over ACP.
+
+```python
+class EchoAgent(Agent):
+    @property
+    def name(self) -> str:
+        return "echo"
+
+    @property
+    def description(self) -> str:
+        return "Echoes everything"
+
+    async def run(self, input: Message, *, context: Context) -> AsyncGenerator[Message | Await, AwaitResume]:
+        for part in input:
+            await asyncio.sleep(0.5)
+            yield {"thought": "I should echo everyting"}
+            yield Message(part)
+
+
+serve(EchoAgent())
+```
+
+➡️ Explore more in our [examples library](/python/examples).

acp_sdk-1.0.0rc4.dist-info/RECORD

@@ -0,0 +1,22 @@
+acp_sdk/__init__.py,sha256=XlcAbmvJfvJK5tmOFdxXP19aDwxxdG_jygsTCvXtjTk,43
+acp_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+acp_sdk/client/__init__.py,sha256=Bca1DORrswxzZsrR2aUFpATuNG2xNSmYvF1Z2WJaVbc,51
+acp_sdk/client/client.py,sha256=W6iXxH65UUODnvt3tnvgdqT_pP1meZUF2HwJpWCM0BM,5029
+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=ACZPQp-wm43tdlx83hrX7QmdtBRWVXvU5bsotUOidHM,3908
+acp_sdk/models/schemas.py,sha256=a0T29vfy93uVIce3ikbd3GSTdKBokMmfXWNVRJD3Eb8,662
+acp_sdk/server/__init__.py,sha256=Qd0uTLaStTGxRaHvtXQpTWoruGvRGu8L17d8IMoPgu8,447
+acp_sdk/server/agent.py,sha256=pAJkUR0OJn7qzsW7JPk3YIjRoPrSFljcWXcH4kBuRCM,2214
+acp_sdk/server/app.py,sha256=7alacNo9y_f0-BjZI0dm_rzSweW-n5YiuY0hrVtEIR8,5420
+acp_sdk/server/bundle.py,sha256=J-1prwhTHeK29ONjFERbv7gNY3YVSCeVI0p5687y-WQ,5076
+acp_sdk/server/context.py,sha256=DIs4T61nIkangT2Mdk5oEHmK__XzfssqtodQ266CvoQ,758
+acp_sdk/server/errors.py,sha256=fWlgVsQ5hs_AXwzc-wvy6QgoDWEMRUBlSrfJfhHHMyE,2085
+acp_sdk/server/logging.py,sha256=Oc8yZigCsuDnHHPsarRzu0RX3NKaLEgpELM2yovGKDI,411
+acp_sdk/server/server.py,sha256=hhju0fXo0vmkD5QYgT_zbZUDZXnCCFQzF3AZCMSgWko,4120
+acp_sdk/server/telemetry.py,sha256=EwmtUrWMYid7XHiX76V1J6CigJPa2NrzEPOX0fBoY3o,1838
+acp_sdk/server/types.py,sha256=2yJPkfUzjVIhHmc0SegGTMqDROe2uFgycb-7CATvYVw,161
+acp_sdk/server/utils.py,sha256=EfrF9VCyVk3AM_ao-BIB9EzGbfTrh4V2Bz-VFr6f6Sg,351
+acp_sdk-1.0.0rc4.dist-info/METADATA,sha256=qHSrUOETNJflMDnlTh8dWQh1sHNdO0OZOStlOJgzjdk,2147
+acp_sdk-1.0.0rc4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+acp_sdk-1.0.0rc4.dist-info/RECORD,,

acp_sdk-1.0.0rc2.dist-info/METADATA

@@ -1,53 +0,0 @@
-Metadata-Version: 2.4
-Name: acp-sdk
-Version: 1.0.0rc2
-Summary: Agent Communication Protocol SDK
-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: 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
-
-## Prerequisites
-
-✅ Python >= 3.13
-
-## Installation
-
-Install using pip:
-
-```shell
-pip install acp-sdk
-```
-
-## Example
-
-The SDK can be used to implement both clients and servers.
-
-### Server
-
-To run an example server use [FastAPI CLI](https://fastapi.tiangolo.com/fastapi-cli/) or other [deployment strategies](https://fastapi.tiangolo.com/deployment/):
-
-```shell
-fastapi dev examples/servers/echo.py
-```
-
-### Client
-
-To run an example client:
-
-```shell
-python examples/clients/simple.py
-```
-
-➡️ Explore more in our [examples library](/python/examples).

acp_sdk-1.0.0rc2.dist-info/RECORD

@@ -1,15 +0,0 @@
-acp_sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-acp_sdk/models.py,sha256=atSddtsQvNfiEIKHTckMwzahlTaOyyjuX6rrtD1Dft8,4345
-acp_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-acp_sdk/client/__init__.py,sha256=Bca1DORrswxzZsrR2aUFpATuNG2xNSmYvF1Z2WJaVbc,51
-acp_sdk/client/client.py,sha256=os14f1Q4TAMoXuhjpbrh67bBYpQS7KyT4H7a-WFN07Q,4489
-acp_sdk/server/__init__.py,sha256=iClvo3yLpMKLoUTTR9JeL_eR7R9YLFFcHTyFpg4xWfg,107
-acp_sdk/server/agent.py,sha256=yo31fL0H7boaHllICXAiXApHgBLD8fJfs1osJWUheuI,682
-acp_sdk/server/bundle.py,sha256=R3D5cPSoId6CZrs-ag3aUuxiK6sVdLw2EmOdMl3SoGg,4892
-acp_sdk/server/context.py,sha256=oILWXHNTXq3mLX0RM7jiIKMC19dEiw7AYy6X0L6OUXg,163
-acp_sdk/server/server.py,sha256=XvIznmda5UjjOUP37XRHDwKzVf-seKjVwkfshbKRuCo,4446
-acp_sdk/server/telemetry.py,sha256=rM22-0_SXtJn9T_xDmXalATAR1cwV8COJDY6EAg0jeE,1439
-acp_sdk/server/utils.py,sha256=EfrF9VCyVk3AM_ao-BIB9EzGbfTrh4V2Bz-VFr6f6Sg,351
-acp_sdk-1.0.0rc2.dist-info/METADATA,sha256=vGTZlnl6Ucgg4iPLxItlrAu446pJYitlKMLBuYNgEUI,1350
-acp_sdk-1.0.0rc2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-acp_sdk-1.0.0rc2.dist-info/RECORD,,