acp-sdk 0.10.1__tar.gz → 0.11.0__tar.gz

{acp_sdk-0.10.1 → acp_sdk-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acp-sdk
-Version: 0.10.1
+Version: 0.11.0
 Summary: Agent Communication Protocol SDK
 Author: IBM Corp.
 Maintainer-email: Tomas Pilar <thomas7pilar@gmail.com>
@@ -11,6 +11,7 @@ Requires-Dist: fastapi[standard]>=0.115
 Requires-Dist: httpx-sse>=0.4
 Requires-Dist: httpx>=0.26
 Requires-Dist: janus>=2.0
+Requires-Dist: obstore>=0.6
 Requires-Dist: opentelemetry-api>=1.31
 Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.31
 Requires-Dist: opentelemetry-instrumentation-fastapi>=0.52b1

{acp_sdk-0.10.1 → acp_sdk-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "acp-sdk"
-version = "0.10.1"
+version = "0.11.0"
 description = "Agent Communication Protocol SDK"
 license = "Apache-2.0"
 readme = "README.md"
@@ -21,6 +21,7 @@ dependencies = [
     "cachetools>=5.5",
     "redis>=6.1",
     "psycopg[binary]>=3.2",
+    "obstore>=0.6",
 ]
 
 [build-system]

acp_sdk-0.11.0/src/acp_sdk/client/client.py

@@ -0,0 +1,324 @@
+import asyncio
+import logging
+import ssl
+import typing
+from collections.abc import AsyncIterator
+from types import TracebackType
+from typing import Self
+
+import httpx
+from httpx_sse import EventSource, aconnect_sse
+from pydantic import TypeAdapter
+
+from acp_sdk.client.types import Input
+from acp_sdk.client.utils import input_to_messages
+from acp_sdk.instrumentation import get_tracer
+from acp_sdk.models import (
+    ACPError,
+    AgentManifest,
+    AgentName,
+    AgentReadResponse,
+    AgentsListResponse,
+    AwaitResume,
+    Error,
+    ErrorCode,
+    ErrorEvent,
+    Event,
+    PingResponse,
+    Run,
+    RunCancelResponse,
+    RunCreateRequest,
+    RunCreateResponse,
+    RunEventsListResponse,
+    RunId,
+    RunMode,
+    RunResumeRequest,
+    RunResumeResponse,
+    Session,
+    SessionReadResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class Client:
+    def __init__(
+        self,
+        *,
+        session: Session | None = None,
+        client: httpx.AsyncClient | None = None,
+        manage_client: bool = True,
+        auth: httpx._types.AuthTypes | None = None,
+        params: httpx._types.QueryParamTypes | None = None,
+        headers: httpx._types.HeaderTypes | None = None,
+        cookies: httpx._types.CookieTypes | None = None,
+        timeout: httpx._types.TimeoutTypes = None,
+        verify: ssl.SSLContext | str | bool = True,
+        cert: httpx._types.CertTypes | None = None,
+        http1: bool = True,
+        http2: bool = False,
+        proxy: httpx._types.ProxyTypes | None = None,
+        mounts: None | (typing.Mapping[str, httpx.AsyncBaseTransport | None]) = None,
+        follow_redirects: bool = False,
+        limits: httpx.Limits = httpx._config.DEFAULT_LIMITS,
+        max_redirects: int = httpx._config.DEFAULT_MAX_REDIRECTS,
+        event_hooks: None | (typing.Mapping[str, list[httpx._client.EventHook]]) = None,
+        base_url: httpx.URL | str = "",
+        transport: httpx.AsyncBaseTransport | None = None,
+        trust_env: bool = True,
+    ) -> None:
+        self._session = session
+        self._session_last_refresh_base_url: httpx.URL | None = None
+        self._session_refresh_lock = asyncio.Lock()
+
+        self._client = client or httpx.AsyncClient(
+            auth=auth,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            timeout=timeout,
+            verify=verify,
+            cert=cert,
+            http1=http1,
+            http2=http2,
+            proxy=proxy,
+            mounts=mounts,
+            follow_redirects=follow_redirects,
+            limits=limits,
+            max_redirects=max_redirects,
+            event_hooks=event_hooks,
+            base_url=base_url,
+            transport=transport,
+            trust_env=trust_env,
+        )
+        self._manage_client = manage_client
+
+    @property
+    def client(self) -> httpx.AsyncClient:
+        return self._client
+
+    async def __aenter__(self) -> Self:
+        if self._manage_client:
+            await self._client.__aenter__()
+        self._session_span_manager = (
+            (
+                get_tracer()
+                .start_as_current_span("session", attributes={"acp.session": str(self._session.id)})
+                .__enter__()
+            )
+            if self._session
+            else None
+        )
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None = None,
+        exc_value: BaseException | None = None,
+        traceback: TracebackType | None = None,
+    ) -> None:
+        if self._session_span_manager:
+            self._session_span_manager.__exit__(exc_type, exc_value, traceback)
+        if self._manage_client:
+            await self._client.__aexit__(exc_type, exc_value, traceback)
+
+    def session(self, session: Session | None = None) -> Self:
+        return Client(client=self._client, manage_client=False, session=session or Session())
+
+    async def agents(self, *, base_url: httpx.URL | str | None = None) -> AsyncIterator[AgentManifest]:
+        response = await self._client.get(self._create_url("/agents", base_url=base_url))
+        self._raise_error(response)
+        for agent in AgentsListResponse.model_validate(response.json()).agents:
+            yield agent
+
+    async def agent(self, *, name: AgentName, base_url: httpx.URL | str | None = None) -> AgentManifest:
+        response = await self._client.get(self._create_url(f"/agents/{name}", base_url=base_url))
+        self._raise_error(response)
+        response = AgentReadResponse.model_validate(response.json())
+        return AgentManifest(**response.model_dump())
+
+    async def ping(self, *, base_url: httpx.URL | str | None = None) -> bool:
+        response = await self._client.get(self._create_url("/ping", base_url=base_url))
+        self._raise_error(response)
+        PingResponse.model_validate(response.json())
+        return
+
+    async def run_sync(self, input: Input, *, agent: AgentName, base_url: httpx.URL | str | None = None) -> Run:
+        response = await self._client.post(
+            self._create_url("/runs", base_url=base_url),
+            content=RunCreateRequest(
+                agent_name=agent,
+                input=input_to_messages(input),
+                mode=RunMode.SYNC,
+                **(await self._prepare_session_for_run(base_url=base_url)),
+            ).model_dump_json(),
+        )
+        self._raise_error(response)
+        response = RunCreateResponse.model_validate(response.json())
+        return Run(**response.model_dump())
+
+    async def run_async(self, input: Input, *, agent: AgentName, base_url: httpx.URL | str | None = None) -> Run:
+        response = await self._client.post(
+            self._create_url("/runs", base_url=base_url),
+            content=RunCreateRequest(
+                agent_name=agent,
+                input=input_to_messages(input),
+                mode=RunMode.ASYNC,
+                **(await self._prepare_session_for_run(base_url=base_url)),
+            ).model_dump_json(),
+        )
+        self._raise_error(response)
+        response = RunCreateResponse.model_validate(response.json())
+        return Run(**response.model_dump())
+
+    async def run_stream(
+        self, input: Input, *, agent: AgentName, base_url: httpx.URL | str | None = None
+    ) -> AsyncIterator[Event]:
+        async with aconnect_sse(
+            self._client,
+            "POST",
+            self._create_url("/runs", base_url=base_url),
+            content=RunCreateRequest(
+                agent_name=agent,
+                input=input_to_messages(input),
+                mode=RunMode.STREAM,
+                session=await self._prepare_session_for_run(base_url=base_url),
+            ).model_dump_json(),
+        ) as event_source:
+            async for event in self._validate_stream(event_source):
+                yield event
+
+    async def run_status(self, *, run_id: RunId, base_url: httpx.URL | str | None = None) -> Run:
+        response = await self._client.get(self._create_url(f"/runs/{run_id}", base_url=base_url))
+        self._raise_error(response)
+        return Run.model_validate(response.json())
+
+    async def run_events(self, *, run_id: RunId, base_url: httpx.URL | str | None = None) -> AsyncIterator[Event]:
+        response = await self._client.get(self._create_url(f"/runs/{run_id}/events", base_url=base_url))
+        self._raise_error(response)
+        response = RunEventsListResponse.model_validate(response.json())
+        for event in response.events:
+            yield event
+
+    async def run_cancel(self, *, run_id: RunId, base_url: httpx.URL | str | None = None) -> Run:
+        response = await self._client.post(self._create_url(f"/runs/{run_id}/cancel", base_url=base_url))
+        self._raise_error(response)
+        response = RunCancelResponse.model_validate(response.json())
+        return Run(**response.model_dump())
+
+    async def run_resume_sync(
+        self, await_resume: AwaitResume, *, run_id: RunId, base_url: httpx.URL | str | None = None
+    ) -> Run:
+        response = await self._client.post(
+            self._create_url(f"/runs/{run_id}", base_url=base_url),
+            content=RunResumeRequest(await_resume=await_resume, mode=RunMode.SYNC).model_dump_json(),
+        )
+        self._raise_error(response)
+        response = RunResumeResponse.model_validate(response.json())
+        return Run(**response.model_dump())
+
+    async def run_resume_async(
+        self, await_resume: AwaitResume, *, run_id: RunId, base_url: httpx.URL | str | None = None
+    ) -> Run:
+        response = await self._client.post(
+            self._create_url(f"/runs/{run_id}", base_url=base_url),
+            content=RunResumeRequest(await_resume=await_resume, mode=RunMode.ASYNC).model_dump_json(),
+        )
+        self._raise_error(response)
+        response = RunResumeResponse.model_validate(response.json())
+        return Run(**response.model_dump())
+
+    async def run_resume_stream(
+        self, await_resume: AwaitResume, *, run_id: RunId, base_url: httpx.URL | str | None = None
+    ) -> AsyncIterator[Event]:
+        async with aconnect_sse(
+            self._client,
+            "POST",
+            self._create_url(f"/runs/{run_id}", base_url=base_url),
+            content=RunResumeRequest(await_resume=await_resume, mode=RunMode.STREAM).model_dump_json(),
+        ) as event_source:
+            async for event in self._validate_stream(event_source):
+                yield event
+
+    async def refresh_session(
+        self, *, base_url: httpx.URL | str | None = None, timeout: httpx._types.TimeoutTypes = 5000
+    ) -> Session:
+        if not self._session:
+            raise RuntimeError("Client is not in a session")
+
+        async with self._session_refresh_lock:
+            url = self._create_url(
+                f"/sessions/{self._session.id}",
+                base_url=base_url or self._session_last_refresh_base_url,
+            )
+
+            try:
+                response = await self._client.get(url, timeout=timeout)
+                response = SessionReadResponse.model_validate(response.json())
+                self._session = Session(**response.model_dump())
+            except ACPError as e:
+                if e.error.code == ErrorCode.NOT_FOUND:
+                    pass
+                raise e
+
+            return self._session
+
+    async def _validate_stream(
+        self,
+        event_source: EventSource,
+    ) -> AsyncIterator[Event]:
+        if event_source.response.is_error:
+            await event_source.response.aread()
+            self._raise_error(event_source.response)
+        async for event in event_source.aiter_sse():
+            event: Event = TypeAdapter(Event).validate_json(event.data)
+            if isinstance(event, ErrorEvent):
+                raise ACPError(error=event.error)
+            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()))
+
+    def _create_base_url(self, base_url: httpx.URL | str | None) -> httpx.URL:
+        base_url = httpx.URL(base_url or self._client.base_url)
+        if not base_url.raw_path.endswith(b"/"):
+            base_url = base_url.copy_with(raw_path=base_url.raw_path + b"/")
+        return base_url
+
+    def _create_url(self, endpoint: str, base_url: httpx.URL | str | None) -> httpx.URL:
+        merge_url = httpx.URL(endpoint)
+
+        if not merge_url.is_relative_url:
+            raise ValueError("Endpoint must be a relative URL")
+
+        base_url = self._create_base_url(base_url)
+        merge_raw_path = base_url.raw_path + merge_url.raw_path.lstrip(b"/")
+        return base_url.copy_with(raw_path=merge_raw_path)
+
+    async def _prepare_session_for_run(self, *, base_url: httpx.URL | str | None) -> dict:
+        if not self._session:
+            return {}
+
+        target_base_url = self._create_base_url(base_url=base_url)
+        try:
+            if not self._session_last_refresh_base_url:
+                return {"session": self._session}
+            if self._session_last_refresh_base_url == target_base_url:
+                # Same server, no need to forward session
+                return {"session_id": self._session.id}
+
+            session = await self.refresh_session()
+            return {"session": session}
+        except ACPError as e:
+            if e.error.code == ErrorCode.NOT_FOUND:
+                return {"session": self._session}
+            raise e
+        finally:
+            await self._update_session_refresh_url(target_base_url)
+
+    async def _update_session_refresh_url(self, url: httpx.URL) -> None:
+        async with self._session_refresh_lock:
+            self._session_last_refresh_base_url = url

{acp_sdk-0.10.1 → acp_sdk-0.11.0}/src/acp_sdk/models/__init__.py

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

{acp_sdk-0.10.1 → acp_sdk-0.11.0}/src/acp_sdk/models/models.py

@@ -1,5 +1,6 @@
 import asyncio
 import uuid
+from collections.abc import AsyncIterator
 from datetime import datetime, timezone
 from enum import Enum
 from typing import Any, Literal, Optional, Union
@@ -7,6 +8,8 @@ from typing import Any, Literal, Optional, Union
 from pydantic import AnyUrl, BaseModel, ConfigDict, Field
 
 from acp_sdk.models.errors import ACPError, Error
+from acp_sdk.models.types import AgentName, ResourceId, ResourceUrl, RunId, SessionId
+from acp_sdk.shared import ResourceLoader, ResourceStore
 
 
 class AnyModel(BaseModel):
@@ -74,6 +77,40 @@ class Metadata(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
+class CitationMetadata(BaseModel):
+    """
+    Represents an inline citation, providing info about information source. This
+    is supposed to be rendered as an inline icon, optionally marking a text
+    range it belongs to.
+
+    If CitationMetadata is included together with content in the message part,
+    the citation belongs to that content and renders at the MessagePart position.
+    This way may be used for non-text content, like images and files.
+
+    Alternatively, `start_index` and `end_index` may define a text range,
+    counting characters in the current Message across all MessageParts with
+    content type `text/*`, where the citation will be rendered. If one of
+    `start_index` and `end_index` is missing or their values are equal, the
+    citation renders only as an inline icon at that position.
+
+    If both `start_index` and `end_index` are not present and MessagePart has no
+    content, the citation renders as inline icon only at the MessagePart position.
+
+    Properties:
+    - url: URL of the source document.
+    - title: Title of the source document.
+    - description: Accompanying text, which may be a general description of the
+                   source document, or a specific snippet.
+    """
+
+    kind: Literal["citation"] = "citation"
+    start_index: Optional[int]
+    end_index: Optional[int]
+    url: Optional[str]
+    title: Optional[str]
+    description: Optional[str]
+
+
 class MessagePart(BaseModel):
     name: Optional[str] = None
     content_type: Optional[str] = "text/plain"
@@ -83,9 +120,9 @@ class MessagePart(BaseModel):
 
     model_config = ConfigDict(extra="allow")
 
+    metadata: Optional[CitationMetadata] = Field(discriminator="kind", default=None)
+
     def model_post_init(self, __context: Any) -> None:
-        if self.content is None and self.content_url is None:
-            raise ValueError("Either content or content_url must be provided")
         if self.content is not None and self.content_url is not None:
             raise ValueError("Only one of content or content_url can be provided")
 
@@ -95,6 +132,7 @@ class Artifact(MessagePart):
 
 
 class Message(BaseModel):
+    role: Literal["user"] | Literal["agent"] | str = Field("user", pattern=r"^(user|agent(\/[a-zA-Z0-9_\-]+)?)$")
     parts: list[MessagePart]
     created_at: datetime | None = Field(default_factory=lambda: datetime.now(timezone.utc))
     completed_at: datetime | None = Field(default_factory=lambda: datetime.now(timezone.utc))
@@ -102,7 +140,10 @@ class Message(BaseModel):
     def __add__(self, other: "Message") -> "Message":
         if not isinstance(other, Message):
             raise TypeError(f"Cannot concatenate Message with {type(other).__name__}")
+        if self.role != other.role:
+            raise ValueError("Cannot concatenate messages with different roles")
         return Message(
+            role=self.role,
             parts=self.parts + other.parts,
             created_at=min(self.created_at, other.created_at) if self.created_at and other.created_at else None,
             completed_at=max(self.completed_at, other.completed_at)
@@ -146,11 +187,6 @@ class Message(BaseModel):
         return Message(parts=parts, created_at=self.created_at, completed_at=self.completed_at)
 
 
-AgentName = str
-SessionId = uuid.UUID
-RunId = uuid.UUID
-
-
 class RunMode(str, Enum):
     SYNC = "sync"
     ASYNC = "async"
@@ -280,11 +316,41 @@ Event = Union[
     RunCancelledEvent,
     RunFailedEvent,
     RunCompletedEvent,
-    MessagePartEvent,
 ]
 
 
-class Agent(BaseModel):
+class AgentManifest(BaseModel):
     name: str
     description: str | None = None
     metadata: Metadata = Metadata()
+
+
+class Session(BaseModel):
+    id: SessionId = Field(default_factory=uuid.uuid4)
+    history: list[ResourceUrl] = Field(default_factory=list)
+    state: ResourceUrl | None = None
+
+    loader: ResourceLoader | None = Field(None, exclude=True)
+    store: ResourceStore | None = Field(None, exclude=True)
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    async def load_history(self, *, loader: ResourceLoader | None = None) -> AsyncIterator[Message]:
+        loader = loader or self.loader or ResourceLoader()
+        for url in self.history:
+            data = await loader.load(url)
+            yield Message.model_validate_json(data)
+
+    async def load_state(self, *, loader: ResourceLoader | None = None) -> bytes:
+        loader = loader or self.loader or ResourceLoader()
+        data = await loader.load(self.state)
+        return data
+
+    async def store_state(self, data: bytes, *, store: ResourceStore | None = None) -> ResourceUrl:
+        store = store or self.store
+        if not store:
+            raise ValueError("Store must be specified")
+
+        id = ResourceId()
+        await store.store(id, data)
+        return await store.url(id)

{acp_sdk-0.10.1 → acp_sdk-0.11.0}/src/acp_sdk/models/schemas.py

@@ -1,6 +1,16 @@
 from pydantic import BaseModel
 
-from acp_sdk.models.models import Agent, AgentName, AwaitResume, Event, Message, Run, RunMode, SessionId
+from acp_sdk.models.models import (
+    AgentManifest,
+    AgentName,
+    AwaitResume,
+    Event,
+    Message,
+    Run,
+    RunMode,
+    Session,
+    SessionId,
+)
 
 
 class PingResponse(BaseModel):
@@ -8,16 +18,17 @@ class PingResponse(BaseModel):
 
 
 class AgentsListResponse(BaseModel):
-    agents: list[Agent]
+    agents: list[AgentManifest]
 
 
-class AgentReadResponse(Agent):
+class AgentReadResponse(AgentManifest):
     pass
 
 
 class RunCreateRequest(BaseModel):
     agent_name: AgentName
     session_id: SessionId | None = None
+    session: Session | None = None
     input: list[Message]
     mode: RunMode = RunMode.SYNC
 
@@ -45,3 +56,7 @@ class RunCancelResponse(Run):
 
 class RunEventsListResponse(BaseModel):
     events: list[Event]
+
+
+class SessionReadResponse(Session):
+    pass

acp_sdk-0.11.0/src/acp_sdk/models/types.py

@@ -0,0 +1,9 @@
+from uuid import UUID
+
+from pydantic import AnyHttpUrl
+
+AgentName = str
+SessionId = UUID
+RunId = UUID
+ResourceUrl = AnyHttpUrl
+ResourceId = UUID

{acp_sdk-0.10.1 → acp_sdk-0.11.0}/src/acp_sdk/server/__init__.py

@@ -1,7 +1,11 @@
-from acp_sdk.server.agent import Agent as Agent
+from acp_sdk.server.agent import AgentManifest as AgentManifest
 from acp_sdk.server.agent import agent as agent
 from acp_sdk.server.app import create_app as create_app
 from acp_sdk.server.context import Context as Context
 from acp_sdk.server.server import Server as Server
+from acp_sdk.server.store import MemoryStore as MemoryStore
+from acp_sdk.server.store import PostgreSQLStore as PostgreSQLStore
+from acp_sdk.server.store import RedisStore as RedisStore
+from acp_sdk.server.store import Store as Store
 from acp_sdk.server.types import RunYield as RunYield
 from acp_sdk.server.types import RunYieldResume as RunYieldResume