Handle Errors

The Error extension provides a standardized way to report errors from your agent to the UI. The Agent Stack SDK automatically handles exceptions raised within your agent function and uses the Error extension to report them. No configuration is required for standard error reporting.

Standard Error Reporting

Simply raise exceptions in your agent code. The SDK will catch them and use the extension to format the error message.

# Copyright 2025 © BeeAI a Series of LF Projects, LLC
# SPDX-License-Identifier: Apache-2.0

import os

from a2a.types import Message
from agentstack_sdk.server import Server
from agentstack_sdk.server.context import RunContext

server = Server()


@server.agent()
async def standard_error_reporting_example(input: Message, context: RunContext):
    # ... do some work ...
    raise ValueError("Something went wrong!")


def run():
    server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000)))


if __name__ == "__main__":
    run()

Advanced Configuration

If you want to customize the error reporting, for example to include stack traces, you can inject the extension with custom parameters.

# Copyright 2025 © BeeAI a Series of LF Projects, LLC
# SPDX-License-Identifier: Apache-2.0

import os
from typing import Annotated

from a2a.types import Message
from agentstack_sdk.a2a.extensions import (
    ErrorExtensionParams,
    ErrorExtensionServer,
    ErrorExtensionSpec,
)
from agentstack_sdk.server import Server

server = Server()


@server.agent()
async def advanced_error_reporting_example(
    input: Message,
    # Configure to include stack traces
    error_ext: Annotated[
        ErrorExtensionServer,
        ErrorExtensionSpec(params=ErrorExtensionParams(include_stacktrace=True)),
    ],
):
    """Agent that demonstrates error handling with stack traces"""
    yield "Working..."

    # This exception will be caught and formatted by the extension
    # The stack trace will be included because of the configuration above
    raise ValueError("Something went wrong!")


def run():
    server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000)))


if __name__ == "__main__":
    run()

Import the Error extension

Import ErrorExtensionServer, ErrorExtensionSpec, and ErrorExtensionParams.

Inject and Configure

Inject the extension using Annotated and set include_stacktrace=True.

Enable stack traces during development for easier debugging, but consider disabling them in production to avoid leaking implementation details.

Handling Multiple Errors

The Error extension supports ExceptionGroup to report multiple errors at once. When an ExceptionGroup is raised, it is formatted as a group of errors in the UI.

# Copyright 2025 © BeeAI a Series of LF Projects, LLC
# SPDX-License-Identifier: Apache-2.0

import os

from a2a.types import Message
from agentstack_sdk.server import Server
from agentstack_sdk.server.context import RunContext

server = Server()


@server.agent()
async def multiple_errors_handling_example(input: Message, context: RunContext):
    raise ExceptionGroup("Multiple failures", [ValueError("First error"), TypeError("Second error")])


def run():
    server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000)))


if __name__ == "__main__":
    run()

Adding Context

You can attach arbitrary context to errors by accessing the injected ErrorExtensionServer instance. This context will be included in the error metadata sent to the client.

# Copyright 2025 © BeeAI a Series of LF Projects, LLC
# SPDX-License-Identifier: Apache-2.0

import os
from typing import Annotated, cast

from a2a.types import Message
from agentstack_sdk.a2a.extensions import (
    ErrorExtensionParams,
    ErrorExtensionServer,
    ErrorExtensionSpec,
)
from agentstack_sdk.server import Server
from pydantic import JsonValue

server = Server()


@server.agent()
async def adding_error_context_example(
    input: Message,
    error_ext: Annotated[
        ErrorExtensionServer, ErrorExtensionSpec(params=ErrorExtensionParams(include_stacktrace=False))
    ],
):
    # Add context before an error might occur or in an except block
    ctx = cast(dict[str, JsonValue], error_ext.context)
    ctx["request_id"] = "req-123"
    ctx["user_id"] = 42

    # ... do work ...

    # If an exception is raised, the context is included
    raise ValueError("Something went wrong!")


def run():
    server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000)))


if __name__ == "__main__":
    run()

Examples

For more examples, see:

error_agent.py

Introduction

Deploy Agents

Agent Integration

Reference

Deploy Agent Stack

Custom UI Integration

Experimental

Community

Standard Error Reporting

Advanced Configuration

Handling Multiple Errors

Adding Context

Examples

​Standard Error Reporting

​Advanced Configuration

​Handling Multiple Errors

​Adding Context

​Examples

Standard Error Reporting

Advanced Configuration

Handling Multiple Errors

Adding Context

Examples