agentstack-sdk 0.4.2rc9__tar.gz → 0.4.3__tar.gz

{agentstack_sdk-0.4.2rc9 → agentstack_sdk-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: agentstack-sdk
-Version: 0.4.2rc9
+Version: 0.4.3
 Summary: Agent Stack SDK
 Author: IBM Corp.
 Requires-Dist: a2a-sdk==0.3.9

{agentstack_sdk-0.4.2rc9 → agentstack_sdk-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentstack-sdk"
-version = "0.4.2-rc9"
+version = "0.4.3"
 description = "Agent Stack SDK"
 readme = "README.md"
 authors = [{ name = "IBM Corp." }]
@@ -26,8 +26,7 @@ dependencies = [
 
 [dependency-groups]
 dev = [
-    "beeai-framework[duckduckgo,wikipedia]>=0.1.68",
-    "ddgs>=9.9.1",
+    "beeai-framework[duckduckgo,wikipedia]>=0.1.70",
     "pyright>=1.1.403",
     "pytest>=8.4.1",
     "pytest-asyncio>=1.1.0",

{agentstack_sdk-0.4.2rc9 → agentstack_sdk-0.4.3}/src/agentstack_sdk/a2a/extensions/__init__.py

@@ -3,4 +3,5 @@
 
 from .auth import *
 from .services import *
+from .tools import *
 from .ui import *

agentstack_sdk-0.4.3/src/agentstack_sdk/a2a/extensions/tools/__init__.py

@@ -0,0 +1,5 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from .call import *
+from .exceptions import *

agentstack_sdk-0.4.3/src/agentstack_sdk/a2a/extensions/tools/call.py

@@ -0,0 +1,114 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import uuid
+from types import NoneType
+from typing import TYPE_CHECKING, Any, Literal
+
+import a2a.types
+from mcp import Tool
+from mcp.types import Implementation
+from pydantic import BaseModel, Field
+
+from agentstack_sdk.a2a.extensions.base import BaseExtensionClient, BaseExtensionServer, BaseExtensionSpec
+from agentstack_sdk.a2a.extensions.tools.exceptions import ToolCallRejectionError
+from agentstack_sdk.a2a.types import AgentMessage, InputRequired
+
+if TYPE_CHECKING:
+    from agentstack_sdk.server.context import RunContext
+
+
+class ToolCallServer(BaseModel):
+    name: str = Field(description="The programmatic name of the server.")
+    title: str | None = Field(description="A human-readable title for the server.")
+    version: str = Field(description="The version of the server.")
+
+
+class ToolCallRequest(BaseModel):
+    name: str = Field(description="The programmatic name of the tool.")
+    title: str | None = Field(None, description="A human-readable title for the tool.")
+    description: str | None = Field(None, description="A human-readable description of the tool.")
+
+    input: dict[str, Any] | None = Field(description="The input for the tool.")
+
+    server: ToolCallServer | None = Field(None, description="The server executing the tool.")
+
+    @staticmethod
+    def from_mcp_tool(
+        tool: Tool, input: dict[str, Any] | None, server: Implementation | None = None
+    ) -> ToolCallRequest:
+        return ToolCallRequest(
+            name=tool.name,
+            title=tool.annotations.title if tool.annotations else None,
+            description=tool.description,
+            input=input,
+            server=ToolCallServer(name=server.name, title=server.title, version=server.version) if server else None,
+        )
+
+
+class ToolCallResponse(BaseModel):
+    action: Literal["accept", "reject"]
+
+
+class ToolCallExtensionParams(BaseModel):
+    pass
+
+
+class ToolCallExtensionSpec(BaseExtensionSpec[ToolCallExtensionParams]):
+    URI: str = "https://a2a-extensions.agentstack.beeai.dev/tools/call/v1"
+
+
+class ToolCallExtensionMetadata(BaseModel):
+    pass
+
+
+class ToolCallExtensionServer(BaseExtensionServer[ToolCallExtensionSpec, ToolCallExtensionMetadata]):
+    def create_request_message(self, *, request: ToolCallRequest):
+        return AgentMessage(
+            text="Tool call approval requested", metadata={self.spec.URI: request.model_dump(mode="json")}
+        )
+
+    def parse_response(self, *, message: a2a.types.Message):
+        if not message or not message.metadata or not (data := message.metadata.get(self.spec.URI)):
+            raise RuntimeError("Invalid mcp response")
+        return ToolCallResponse.model_validate(data)
+
+    async def request_tool_call_approval(
+        self,
+        request: ToolCallRequest,
+        *,
+        context: RunContext,
+    ) -> ToolCallResponse:
+        message = self.create_request_message(request=request)
+        message = await context.yield_async(InputRequired(message=message))
+        if message:
+            result = self.parse_response(message=message)
+            match result.action:
+                case "accept":
+                    return result
+                case "reject":
+                    raise ToolCallRejectionError("User has rejected the tool call")
+
+        else:
+            raise RuntimeError("Yield did not return a message")
+
+
+class ToolCallExtensionClient(BaseExtensionClient[ToolCallExtensionSpec, NoneType]):
+    def create_response_message(self, *, response: ToolCallResponse, task_id: str | None):
+        return a2a.types.Message(
+            message_id=str(uuid.uuid4()),
+            role=a2a.types.Role.user,
+            parts=[],
+            task_id=task_id,
+            metadata={self.spec.URI: response.model_dump(mode="json")},
+        )
+
+    def parse_request(self, *, message: a2a.types.Message):
+        if not message or not message.metadata or not (data := message.metadata.get(self.spec.URI)):
+            raise ValueError("Invalid tool call request")
+        return ToolCallRequest.model_validate(data)
+
+    def metadata(self) -> dict[str, Any]:
+        return {self.spec.URI: ToolCallExtensionMetadata().model_dump(mode="json")}

agentstack_sdk-0.4.3/src/agentstack_sdk/a2a/extensions/tools/exceptions.py

@@ -0,0 +1,6 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+
+class ToolCallRejectionError(RuntimeError):
+    pass

{agentstack_sdk-0.4.2rc9 → agentstack_sdk-0.4.3}/src/agentstack_sdk/a2a/extensions/ui/__init__.py

@@ -3,6 +3,7 @@
 
 from .agent_detail import *
 from .citation import *
+from .error import *
 from .form_request import *
 from .settings import *
 from .trajectory import *

agentstack_sdk-0.4.3/src/agentstack_sdk/a2a/extensions/ui/error.py

@@ -0,0 +1,213 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import contextvars
+import json
+import logging
+import traceback
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from types import NoneType
+from typing import Any
+
+import pydantic
+
+from agentstack_sdk.a2a.extensions.base import (
+    BaseExtensionClient,
+    BaseExtensionServer,
+    BaseExtensionSpec,
+)
+from agentstack_sdk.a2a.types import AgentMessage, JsonDict, Metadata
+
+logger = logging.getLogger(__name__)
+
+
+class Error(pydantic.BaseModel):
+    """
+    Represents error information for displaying exceptions in the UI.
+
+    This extension helps display errors in a user-friendly way with:
+    - A clear error title (exception type)
+    - A descriptive error message
+
+    Visually, this may appear as an error card in the UI.
+
+    Properties:
+    - title: Title of the error (typically the exception class name).
+    - message: The error message describing what went wrong.
+    """
+
+    title: str
+    message: str
+
+
+class ErrorGroup(pydantic.BaseModel):
+    """
+    Represents a group of errors.
+
+    Properties:
+    - message: A message describing the group of errors.
+    - errors: A list of error objects.
+    """
+
+    message: str
+    errors: list[Error]
+
+
+class ErrorMetadata(pydantic.BaseModel):
+    """
+    Metadata containing an error (or group of errors) and an optional stack trace.
+
+    Properties:
+    - error: The error object or group of errors.
+    - stack_trace: Optional formatted stack trace for debugging.
+    - context: Optional context dictionary.
+    """
+
+    error: Error | ErrorGroup
+    stack_trace: str | None = None
+    context: JsonDict | None = None
+
+
+class ErrorExtensionParams(pydantic.BaseModel):
+    """
+    Configuration parameters for the error extension.
+
+    Properties:
+    - include_stacktrace: Whether to include stack traces in error messages (default: False).
+    """
+
+    include_stacktrace: bool = False
+
+
+class ErrorExtensionSpec(BaseExtensionSpec[ErrorExtensionParams]):
+    URI: str = "https://a2a-extensions.agentstack.beeai.dev/ui/error/v1"
+
+
+def _format_stacktrace(exc: BaseException, include_cause: bool = True) -> str:
+    """Format exception with full traceback including nested causes."""
+    return "".join(traceback.format_exception(type(exc), exc, exc.__traceback__, chain=include_cause))
+
+
+def _extract_error(exc: BaseException) -> Error | ErrorGroup:
+    """
+    Extract error information from an exception, handling:
+    - BaseExceptionGroup (returns ErrorGroup)
+    - FrameworkError from beeai_framework (uses .explain() method)
+    """
+    # Handle BaseExceptionGroup by recursively extracting errors from each exception
+    if isinstance(exc, BaseExceptionGroup):
+        errors: list[Error] = []
+        for sub_exc in exc.exceptions:
+            extracted = _extract_error(sub_exc)
+            if isinstance(extracted, ErrorGroup):
+                errors.extend(extracted.errors)
+            else:
+                errors.append(extracted)
+        return ErrorGroup(message=str(exc), errors=errors)
+
+    # Try to handle FrameworkError if beeai_framework is available
+    try:
+        from beeai_framework.errors import FrameworkError
+
+        if isinstance(exc, FrameworkError):
+            # FrameworkError has special .explain() method
+            return Error(title=exc.name(), message=exc.explain())
+    except ImportError:
+        # beeai_framework not installed, continue with standard handling
+        pass
+
+    return Error(title=type(exc).__name__, message=str(exc))
+
+
+class ErrorExtensionServer(BaseExtensionServer[ErrorExtensionSpec, NoneType]):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        # Server-scoped ContextVar for request-scoped error context
+        self._error_context_var: contextvars.ContextVar[JsonDict] = contextvars.ContextVar("error_context")
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        """Set up request-scoped error context using ContextVar."""
+        # Set an empty dict for this request's context
+        token = self._error_context_var.set({})
+
+        try:
+            yield
+        finally:
+            self._error_context_var.reset(token)
+
+    @property
+    def context(self) -> JsonDict:
+        """Get the current request's error context."""
+        try:
+            return self._error_context_var.get()
+        except LookupError:
+            # Fallback for when lifespan hasn't been entered yet
+            logger.warning(
+                "Attempted to use error context when the error extension is not initialized. Make sure to add the ErrorExtensionServer to the agent dependencies."
+            )
+            return {}
+
+    def error_metadata(self, error: BaseException) -> Metadata[str, Any]:
+        """
+        Create metadata for an error.
+
+        Args:
+            error: The exception to convert to metadata
+
+        Returns:
+            Metadata dictionary with error information
+        """
+        error_data = _extract_error(error)
+        stack_trace = _format_stacktrace(error) if self.spec.params.include_stacktrace else None
+        return Metadata(
+            {
+                self.spec.URI: ErrorMetadata(
+                    error=error_data,
+                    stack_trace=stack_trace,
+                    context=self.context or None,
+                ).model_dump(mode="json")
+            }
+        )
+
+    def message(
+        self,
+        error: BaseException,
+    ) -> AgentMessage:
+        """
+        Create an AgentMessage with error metadata and serialized text representation.
+
+        Args:
+            error: The exception to include in the message
+
+        Returns:
+            AgentMessage with error metadata and markdown-formatted text
+        """
+        metadata = self.error_metadata(error)
+        error_metadata = ErrorMetadata.model_validate(metadata[self.spec.URI])
+
+        # Serialize to markdown for display
+        text_lines: list[str] = []
+        if isinstance(error_metadata.error, ErrorGroup):
+            text_lines.append(f"## {error_metadata.error.message}\n")
+            for err in error_metadata.error.errors:
+                text_lines.append(f"### {err.title}\n{err.message}")
+        else:
+            text_lines.append(f"## {error_metadata.error.title}\n{error_metadata.error.message}")
+
+        # Add context if present
+        if error_metadata.context:
+            text_lines.append(f"## Context\n```json\n{json.dumps(error_metadata.context, indent=2)}\n```")
+
+        if error_metadata.stack_trace:
+            text_lines.append(f"## Stack Trace\n```\n{error_metadata.stack_trace}\n```")
+
+        text = "\n\n".join(text_lines)
+
+        return AgentMessage(text=text, metadata=metadata)
+
+
+class ErrorExtensionClient(BaseExtensionClient[ErrorExtensionSpec, ErrorMetadata]): ...

{agentstack_sdk-0.4.2rc9 → agentstack_sdk-0.4.3}/src/agentstack_sdk/a2a/types.py

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 import typing
 import uuid
-from typing import Generic, Literal, TypeAlias
+from typing import Generic, Literal, TypeAlias, TypeAliasType, Union
 
 from a2a.types import (
     Artifact,
@@ -104,3 +104,9 @@ class InputRequired(TaskStatus):
 
 class AuthRequired(InputRequired):
     state: Literal[TaskState.auth_required] = TaskState.auth_required  # pyright: ignore [reportIncompatibleVariableOverride]
+
+
+JsonDict = TypeAliasType(
+    "JsonDict",
+    "Union[dict[str, JsonDict], list[JsonDict], str, int, float, bool, None]",  # pyright: ignore[reportDeprecated]  # noqa: UP007
+)

{agentstack_sdk-0.4.2rc9 → agentstack_sdk-0.4.3}/src/agentstack_sdk/platform/vector_store.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 
 import typing
 import uuid
-from typing import Literal
+from typing import Literal, Self
 
 import pydantic
 
@@ -29,12 +29,24 @@ class VectorStoreDocument(pydantic.BaseModel):
 class VectorStoreItem(pydantic.BaseModel):
     id: str = pydantic.Field(default_factory=lambda: uuid.uuid4().hex)
     document_id: str
-    document_type: typing.Literal["platform_file", "external"] = "platform_file"
+    document_type: typing.Literal["platform_file", "external"] | None = "platform_file"
     model_id: str | typing.Literal["platform"] = "platform"
     text: str
     embedding: list[float]
     metadata: Metadata | None = None
 
+    @pydantic.model_validator(mode="after")
+    def validate_document_id(self) -> Self:
+        """Validate that document_id is a valid UUID when document_type is platform_file."""
+        if self.document_type == "platform_file":
+            try:
+                _ = uuid.UUID(self.document_id)
+            except ValueError as ex:
+                raise ValueError(
+                    f"document_id must be a valid UUID when document_type is platform_file, got: {self.document_id}"
+                ) from ex
+        return self
+
 
 class VectorStoreSearchResult(pydantic.BaseModel):
     item: VectorStoreItem

{agentstack_sdk-0.4.2rc9 → agentstack_sdk-0.4.3}/src/agentstack_sdk/server/agent.py

@@ -3,7 +3,6 @@
 
 import asyncio
 import inspect
-import json
 from asyncio import CancelledError
 from collections.abc import AsyncGenerator, AsyncIterator, Callable, Generator
 from contextlib import AbstractAsyncContextManager, AsyncExitStack, asynccontextmanager
@@ -37,14 +36,14 @@ from a2a.types import (
 )
 
 from agentstack_sdk.a2a.extensions.ui.agent_detail import AgentDetail, AgentDetailExtensionSpec
-from agentstack_sdk.a2a.types import ArtifactChunk, Metadata, RunYield, RunYieldResume
-from agentstack_sdk.server.constants import _IMPLICIT_DEPENDENCY_PREFIX
+from agentstack_sdk.a2a.extensions.ui.error import ErrorExtensionParams, ErrorExtensionServer, ErrorExtensionSpec
+from agentstack_sdk.a2a.types import AgentMessage, ArtifactChunk, Metadata, RunYield, RunYieldResume
+from agentstack_sdk.server.constants import _IMPLICIT_DEPENDENCY_PREFIX, DEFAULT_ERROR_EXTENSION
 from agentstack_sdk.server.context import RunContext
 from agentstack_sdk.server.dependencies import extract_dependencies
 from agentstack_sdk.server.store.context_store import ContextStore
 from agentstack_sdk.server.utils import cancel_task, close_queue
 from agentstack_sdk.util.logging import logger
-from agentstack_sdk.util.utils import extract_messages
 
 AgentFunction: TypeAlias = Callable[[], AsyncGenerator[RunYield, RunYieldResume]]
 AgentFunctionFactory: TypeAlias = Callable[
@@ -124,9 +123,14 @@ def agent(
             resolved_name = name or fn.__name__
             resolved_description = description or fn.__doc__ or ""
 
+            # Check if user has provided an ErrorExtensionServer, if not add default
+            has_error_extension = any(isinstance(ext, ErrorExtensionServer) for ext in sdk_extensions)
+            error_extension_spec = ErrorExtensionSpec(ErrorExtensionParams()) if not has_error_extension else None
+
             capabilities.extensions = [
                 *(capabilities.extensions or []),
                 *(AgentDetailExtensionSpec(detail).to_agent_card_extensions()),
+                *(error_extension_spec.to_agent_card_extensions() if error_extension_spec else []),
                 *(e_card for ext in sdk_extensions for e_card in ext.spec.to_agent_card_extensions()),
             ]
 
@@ -232,6 +236,11 @@ def agent(
                             depends(message, context, dependency_args)
                         )
 
+                    context._error_extension = next(
+                        (ext for ext in dependency_args.values() if isinstance(ext, ErrorExtensionServer)),
+                        DEFAULT_ERROR_EXTENSION,
+                    )
+
                     context._store = await context_store.create(
                         context_id=request_context.context_id,
                         initialized_dependencies=list(dependency_args.values()),
@@ -339,124 +348,133 @@ class Executor(AgentExecutor):
                 deep=True, update={"context_id": task_updater.context_id, "task_id": task_updater.task_id}
             )
 
+        run_context: RunContext | None = None
         try:
-            async with self._agent_executor_span(task_updater, context, context_store) as (execute_fn, _run_context):
-                agent_generator_fn = execute_fn()
-
-                await task_updater.start_work()
-                value: RunYieldResume = None
-                opened_artifacts: set[str] = set()
-                while True:
-                    # update invocation time
-                    self._running_tasks[task_updater.task_id]["last_invocation"] = datetime.now()
-
-                    yielded_value = await agent_generator_fn.asend(value)
-
-                    match yielded_value:
-                        case str(text):
-                            await task_updater.update_status(
-                                TaskState.working,
-                                message=task_updater.new_agent_message(parts=[Part(root=TextPart(text=text))]),
-                            )
-                        case Part(root=part) | (TextPart() | FilePart() | DataPart() as part):
-                            await task_updater.update_status(
-                                TaskState.working,
-                                message=task_updater.new_agent_message(parts=[Part(root=part)]),
-                            )
-                        case FileWithBytes() | FileWithUri() as file:
-                            await task_updater.update_status(
-                                TaskState.working,
-                                message=task_updater.new_agent_message(parts=[Part(root=FilePart(file=file))]),
-                            )
-                        case Message() as message:
-                            await task_updater.update_status(TaskState.working, message=with_context(message))
-                        case ArtifactChunk(
-                            parts=parts,
-                            artifact_id=artifact_id,
-                            name=name,
-                            metadata=metadata,
-                            last_chunk=last_chunk,
-                        ):
-                            await task_updater.add_artifact(
-                                parts=cast(list[Part], parts),
-                                artifact_id=artifact_id,
-                                name=name,
-                                metadata=metadata,
-                                append=artifact_id in opened_artifacts,
-                                last_chunk=last_chunk,
-                            )
-                            opened_artifacts.add(artifact_id)
-                        case Artifact(parts=parts, artifact_id=artifact_id, name=name, metadata=metadata):
-                            await task_updater.add_artifact(
+            async with self._agent_executor_span(task_updater, context, context_store) as (execute_fn, run_context):
+                try:
+                    agent_generator_fn = execute_fn()
+
+                    await task_updater.start_work()
+                    value: RunYieldResume = None
+                    opened_artifacts: set[str] = set()
+                    while True:
+                        # update invocation time
+                        self._running_tasks[task_updater.task_id]["last_invocation"] = datetime.now()
+
+                        yielded_value = await agent_generator_fn.asend(value)
+
+                        match yielded_value:
+                            case str(text):
+                                await task_updater.update_status(
+                                    TaskState.working,
+                                    message=task_updater.new_agent_message(parts=[Part(root=TextPart(text=text))]),
+                                )
+                            case Part(root=part) | (TextPart() | FilePart() | DataPart() as part):
+                                await task_updater.update_status(
+                                    TaskState.working,
+                                    message=task_updater.new_agent_message(parts=[Part(root=part)]),
+                                )
+                            case FileWithBytes() | FileWithUri() as file:
+                                await task_updater.update_status(
+                                    TaskState.working,
+                                    message=task_updater.new_agent_message(parts=[Part(root=FilePart(file=file))]),
+                                )
+                            case Message() as message:
+                                await task_updater.update_status(TaskState.working, message=with_context(message))
+                            case ArtifactChunk(
                                 parts=parts,
                                 artifact_id=artifact_id,
                                 name=name,
                                 metadata=metadata,
-                                last_chunk=True,
-                                append=False,
-                            )
-                        case TaskStatus(state=TaskState.input_required, message=message, timestamp=timestamp):
-                            await task_updater.requires_input(message=with_context(message), final=True)
-                            value = cast(RunYieldResume, await resume_queue.dequeue_event())
-                            resume_queue.task_done()
-                            continue
-                        case TaskStatus(state=TaskState.auth_required, message=message, timestamp=timestamp):
-                            await task_updater.requires_auth(message=with_context(message), final=True)
-                            value = cast(RunYieldResume, await resume_queue.dequeue_event())
-                            resume_queue.task_done()
-                            continue
-                        case TaskStatus(state=state, message=message, timestamp=timestamp):
-                            await task_updater.update_status(
-                                state=state, message=with_context(message), timestamp=timestamp
-                            )
-                        case TaskStatusUpdateEvent(
-                            status=TaskStatus(state=state, message=message, timestamp=timestamp),
-                            final=final,
-                            metadata=metadata,
-                        ):
-                            await task_updater.update_status(
-                                state=state,
-                                message=with_context(message),
-                                timestamp=timestamp,
+                                last_chunk=last_chunk,
+                            ):
+                                await task_updater.add_artifact(
+                                    parts=cast(list[Part], parts),
+                                    artifact_id=artifact_id,
+                                    name=name,
+                                    metadata=metadata,
+                                    append=artifact_id in opened_artifacts,
+                                    last_chunk=last_chunk,
+                                )
+                                opened_artifacts.add(artifact_id)
+                            case Artifact(parts=parts, artifact_id=artifact_id, name=name, metadata=metadata):
+                                await task_updater.add_artifact(
+                                    parts=parts,
+                                    artifact_id=artifact_id,
+                                    name=name,
+                                    metadata=metadata,
+                                    last_chunk=True,
+                                    append=False,
+                                )
+                            case TaskStatus(state=TaskState.input_required, message=message, timestamp=timestamp):
+                                await task_updater.requires_input(message=with_context(message), final=True)
+                                value = cast(RunYieldResume, await resume_queue.dequeue_event())
+                                resume_queue.task_done()
+                                continue
+                            case TaskStatus(state=TaskState.auth_required, message=message, timestamp=timestamp):
+                                await task_updater.requires_auth(message=with_context(message), final=True)
+                                value = cast(RunYieldResume, await resume_queue.dequeue_event())
+                                resume_queue.task_done()
+                                continue
+                            case TaskStatus(state=state, message=message, timestamp=timestamp):
+                                await task_updater.update_status(
+                                    state=state, message=with_context(message), timestamp=timestamp
+                                )
+                            case TaskStatusUpdateEvent(
+                                status=TaskStatus(state=state, message=message, timestamp=timestamp),
                                 final=final,
                                 metadata=metadata,
-                            )
-                        case TaskArtifactUpdateEvent(
-                            artifact=Artifact(artifact_id=artifact_id, name=name, metadata=metadata, parts=parts),
-                            append=append,
-                            last_chunk=last_chunk,
-                        ):
-                            await task_updater.add_artifact(
-                                parts=parts,
-                                artifact_id=artifact_id,
-                                name=name,
-                                metadata=metadata,
+                            ):
+                                await task_updater.update_status(
+                                    state=state,
+                                    message=with_context(message),
+                                    timestamp=timestamp,
+                                    final=final,
+                                    metadata=metadata,
+                                )
+                            case TaskArtifactUpdateEvent(
+                                artifact=Artifact(artifact_id=artifact_id, name=name, metadata=metadata, parts=parts),
                                 append=append,
                                 last_chunk=last_chunk,
-                            )
-                        case Metadata() as metadata:
-                            await task_updater.update_status(
-                                state=TaskState.working,
-                                message=task_updater.new_agent_message(parts=[], metadata=metadata),
-                            )
-                        case dict() as data:
-                            await task_updater.update_status(
-                                state=TaskState.working,
-                                message=task_updater.new_agent_message(parts=[Part(root=DataPart(data=data))]),
-                            )
-                        case Exception() as ex:
-                            raise ex
-                        case _:
-                            raise ValueError(f"Invalid value yielded from agent: {type(yielded_value)}")
-                    value = None
-        except StopAsyncIteration:
-            await task_updater.complete()
-        except CancelledError:
-            await task_updater.cancel()
-        except Exception as ex:
-            logger.error("Error when executing agent", exc_info=ex)
-            msg = json.dumps(extract_messages(ex), indent=2)
-            await task_updater.failed(task_updater.new_agent_message(parts=[Part(root=TextPart(text=msg))]))
+                            ):
+                                await task_updater.add_artifact(
+                                    parts=parts,
+                                    artifact_id=artifact_id,
+                                    name=name,
+                                    metadata=metadata,
+                                    append=append,
+                                    last_chunk=last_chunk,
+                                )
+                            case Metadata() as metadata:
+                                await task_updater.update_status(
+                                    state=TaskState.working,
+                                    message=task_updater.new_agent_message(parts=[], metadata=metadata),
+                                )
+                            case dict() as data:
+                                await task_updater.update_status(
+                                    state=TaskState.working,
+                                    message=task_updater.new_agent_message(parts=[Part(root=DataPart(data=data))]),
+                                )
+                            case Exception() as ex:
+                                raise ex
+                            case _:
+                                raise ValueError(f"Invalid value yielded from agent: {type(yielded_value)}")
+                        value = None
+                except StopAsyncIteration:
+                    await task_updater.complete()
+                except CancelledError:
+                    await task_updater.cancel()
+                except Exception as ex:
+                    logger.error("Error when executing agent", exc_info=ex)
+                    try:
+                        error_extension = run_context._error_extension if run_context else None
+                        error_extension = error_extension if error_extension is not None else DEFAULT_ERROR_EXTENSION
+                        error_msg = error_extension.message(ex)
+                    except Exception as error_exc:
+                        error_msg = AgentMessage(
+                            text=(f"Failed to create error message: {error_exc!s}\noriginal exc: {ex!s}")
+                        )
+                    await task_updater.failed(error_msg)
         finally:  # cleanup
             await cancel_task(cancellation_task)
             is_cancelling = bool(current_task.cancelling())

agentstack_sdk-0.4.3/src/agentstack_sdk/server/constants.py

@@ -0,0 +1,12 @@
+# Copyright 2025 © BeeAI a Series of LF Projects, LLC
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Final
+
+from agentstack_sdk.a2a.extensions.ui.error import ErrorExtensionParams, ErrorExtensionServer, ErrorExtensionSpec
+
+_IMPLICIT_DEPENDENCY_PREFIX: Final = "___server_dep"
+
+DEFAULT_ERROR_EXTENSION: Final = ErrorExtensionServer(ErrorExtensionSpec(ErrorExtensionParams()))
+
+__all__ = []

{agentstack_sdk-0.4.2rc9 → agentstack_sdk-0.4.3}/src/agentstack_sdk/server/context.py

@@ -3,6 +3,7 @@
 
 
 from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING
 
 import janus
 from a2a.server.context import ServerCallContext
@@ -13,6 +14,9 @@ from pydantic import BaseModel, PrivateAttr
 from agentstack_sdk.a2a.types import RunYield, RunYieldResume
 from agentstack_sdk.server.store.context_store import ContextStoreInstance
 
+if TYPE_CHECKING:
+    from agentstack_sdk.a2a.extensions.ui.error import ErrorExtensionServer
+
 
 class RunContext(BaseModel, arbitrary_types_allowed=True):
     configuration: MessageSendConfiguration | None = None
@@ -26,6 +30,7 @@ class RunContext(BaseModel, arbitrary_types_allowed=True):
     _store: ContextStoreInstance | None = PrivateAttr(None)
     _yield_queue: janus.Queue[RunYield] = PrivateAttr(default_factory=janus.Queue)
     _yield_resume_queue: janus.Queue[RunYieldResume] = PrivateAttr(default_factory=janus.Queue)
+    _error_extension: "ErrorExtensionServer | None" = PrivateAttr(None)
 
     async def store(self, data: Message | Artifact):
         if not self._store:

agentstack_sdk-0.4.2rc9/src/agentstack_sdk/server/constants.py

@@ -1,8 +0,0 @@
-# Copyright 2025 © BeeAI a Series of LF Projects, LLC
-# SPDX-License-Identifier: Apache-2.0
-
-from typing import Final
-
-_IMPLICIT_DEPENDENCY_PREFIX: Final = "___server_dep"
-
-__all__ = []