databricks-agentbricks 0.2.0__py3-none-any.whl

databricks_agentkit/runtime/README.md

@@ -0,0 +1,184 @@
+# Managed agent deployment and runtime
+
+Agent Bricks CLI takes your agent code from a local project to a hosted endpoint on Databricks. Start with a
+LangGraph or OpenAI Agents template, or bring an existing agent.
+
+- **Deployment:** Scaffold a project, run it locally, and deploy it to Databricks Apps. The CLI
+  provisions the stores declared in your project, grants the app access, and configures tracing.
+- **Runtime:** `DurableAgentServer` provides synchronous, streaming, and background execution, with persistent
+  results and automatic crash recovery on deployment. Request-user authentication is attached only
+  to the active first attempt and is never persisted.
+
+## Choose your server
+
+**Managed server (`server = "agentbricks"`).** Register your agent with `DurableAgentServer` to use the managed
+invocation API. This existing `server` value identifies the managed server in `agent.toml`. Deployed
+managed servers receive a Lakebase-backed Runtime Store. Register a recovery handler so the runtime
+can restart interrupted app-auth work and mark interrupted request-user work failed.
+`DurableAgentServer` is a FastAPI application: you can add custom endpoints alongside the invocation API.
+
+If any configured tool uses `auth = "user"`, trusted Databricks Apps ingress headers supply a
+process-local credential for the first execution attempt. Synchronous, streaming, and background
+requests continue through the normal Runtime queue and Runtime Store. The store contains token-free
+request state, events, and results; it never contains the forwarded credential. A replacement
+attempt after failure recovery stops before agent code runs because the original credential is no
+longer available.
+
+**Your own server (`server = "custom"`).** Keep your existing HTTP server, or scaffold a minimal
+FastAPI server with `ab init --server custom`. You own the endpoints, request and response
+formats, and execution behavior. `ab dev` and `ab deploy` still run and deploy the project;
+the managed runtime does not provision a Runtime Store for it.
+
+## From a new agent to a deployed endpoint
+
+```bash
+ab init my-agent --framework langgraph --server agentbricks --profile <profile>
+cd my-agent
+ab dev
+# Stop the local server when ready to deploy.
+ab --profile <profile> deploy my-agent
+```
+
+Use `--framework openai` for OpenAI Agents. Managed-server templates include a chat UI and tests;
+pass `--disable-chat-app` for an API-only project.
+
+1. **Initialize:** `ab init` generates the agent code and runtime adapter separately. It records
+   the server choice and default `my-agent-memory` / `my-agent-session` bindings in `agent.toml`.
+2. **Develop:** Edit your model, prompts, and tools in `agent/`. `ab dev` runs the project locally.
+   Synchronous, streaming, and background requests use the same Runtime for both authorization
+   policies.
+3. **Deploy:** `ab deploy` creates or reuses the declared Session and Memory Stores, grants the
+   app's service principal access, configures tracing, and deploys the app. For a managed server,
+   it also creates or reuses the deployment's Runtime Store.
+
+The generated configuration starts with:
+
+```toml
+schema_version = 1
+
+[agent]
+framework = "langgraph"
+server = "agentbricks"
+
+[memory_store]
+name = "my-agent-memory"
+
+[session_store]
+name = "my-agent-session"
+
+[tracing]
+experiment_name = "/Shared/agentbricks_traces/my-agent"
+```
+
+Override store names at initialization with `--memory-store` and `--session-store`, or later with
+`ab memory bind <name>` and `ab sessions bind <name>`. Custom-server templates declare these
+stores only when explicitly requested. Tracing is bound by experiment **name** (its presence turns
+tracing on); rebind or clear it with `ab tracing bind --experiment-name <path>` / `ab tracing
+unbind`.
+
+Use `ab deployments list`, `get`, `logs`, `start`, `stop`, and `delete` to manage deployed apps.
+See the [CLI documentation](../../../README.md#commands) for command options.
+
+## Connect your agent to the runtime
+
+Keep framework code in `agent/` and HTTP setup and event translation in `runtime/`. The generated
+[LangGraph](../../databricks_agentbricks/templates/agent-langgraph/runtime/adapter.py) and
+[OpenAI Agents](../../databricks_agentbricks/templates/agent-openai/runtime/adapter.py) adapters show how to
+connect framework-native agent loops to the managed runtime.
+
+- **`@app.invoke`:** Register an async handler that receives the request's `input` and an
+  `InvocationContext`. Return a JSON-serializable result.
+- **`await context.emit(event)`:** Publish a JSON event from the handler or adapter. The Runtime
+  stores and delivers events through its streaming API.
+- **`@app.recover`:** Register the handler the runtime calls for a replacement attempt after interrupted
+  execution. It receives the original input and a recovery context. Restore a framework checkpoint
+  from the Session Store, or replay the input if that is safe for your agent. Request-user recovery
+  stops with `MCP_USER_AUTH_RECOVERY_UNSUPPORTED` before this handler runs.
+
+The client chooses `background` and `stream` on each request; separate agent handlers are not
+needed. Registering a recovery hook enables automatic recovery when the Runtime uses a persistent
+store.
+
+For an existing agent, retain its framework code and add the runtime adapter and `DurableAgentServer`
+entrypoint. Set `[agent].server = "agentbricks"` and have `app.yaml` start that entrypoint. Keep the
+existing `agentbricks` value for projects that use the managed server. Changing the configuration field
+alone does not convert a custom HTTP server into `DurableAgentServer`.
+
+Newly generated runtime code imports from `databricks_agentkit`. The AgentKit client uses
+`databricks_agentkit.AgentKitClient`.
+
+## Invoke, stream, and reconnect
+
+An **invocation** is one managed agent run. The client-supplied UUID `id` acts as an idempotency key
+while its Runtime record is retained. Request-user invocation IDs are internally namespaced by the
+forwarded principal so users cannot collide with each other.
+
+- **Synchronous:** Wait for the result in the POST response.
+- **Streaming (`stream: true`):** Receive progress events as Server-Sent Events (SSE).
+- **Background (`background: true`):** Return immediately with `202`, then poll for the result.
+  Add `stream: true` to include an events URL in the response.
+- **Reconnect:** Read stored events with `GET .../events?after=<last-event-id>`.
+
+These examples use an agent that returns `{"answer":"Hello"}` and emits `delta` events. The input,
+output, and application event payloads are defined by your agent or framework adapter.
+
+| API endpoint | Request | Response |
+| --- | --- | --- |
+| `POST /api/invocations` | `{"id":"550e8400-e29b-41d4-a716-446655440000","input":{"messages":[{"role":"user","content":"Hello"}]}}` | `200`<br>`{"id":"550e8400-e29b-41d4-a716-446655440000","status":"completed","output":{"answer":"Hello"}}` |
+| `POST /api/invocations` | `{"id":"550e8400-e29b-41d4-a716-446655440000","input":{"messages":[{"role":"user","content":"Hello"}]},"stream":true}` | `200 text/event-stream`<br>`id: 1`<br>`event: run.started`<br>`data: {"type":"run.started"}`<br><br>`id: 2`<br>`event: delta`<br>`data: {"type":"delta","content":"Hello"}`<br><br>`id: 3`<br>`event: run.completed`<br>`data: {"type":"run.completed"}` |
+| `POST /api/invocations` | `{"id":"550e8400-e29b-41d4-a716-446655440000","input":{"messages":[{"role":"user","content":"Hello"}]},"background":true}` | `202`<br>`{"id":"550e8400-e29b-41d4-a716-446655440000","status":"queued","status_url":"/api/invocations/550e8400-e29b-41d4-a716-446655440000"}` |
+| `POST /api/invocations` | `{"id":"550e8400-e29b-41d4-a716-446655440000","input":{"messages":[{"role":"user","content":"Hello"}]},"background":true,"stream":true}` | `202`<br>`{"id":"550e8400-e29b-41d4-a716-446655440000","status":"queued","status_url":"/api/invocations/550e8400-e29b-41d4-a716-446655440000","events_url":"/api/invocations/550e8400-e29b-41d4-a716-446655440000/events"}` |
+| `GET /api/invocations/550e8400-e29b-41d4-a716-446655440000` | — | `200`<br>`{"id":"550e8400-e29b-41d4-a716-446655440000","status":"completed","output":{"answer":"Hello"}}` |
+| `GET /api/invocations/550e8400-e29b-41d4-a716-446655440000/events?after=1` | — | `200 text/event-stream`<br>`id: 2`<br>`event: delta`<br>`data: {"type":"delta","content":"Hello"}`<br><br>`id: 3`<br>`event: run.completed`<br>`data: {"type":"run.completed"}` |
+
+## Execution state and agent state
+
+The state diagram below applies to both authorization policies. Request-user authentication is a
+process-local input to the active first attempt; it is not part of the Runtime Store, Session Store,
+or Memory Store.
+
+```mermaid
+flowchart LR
+    CLIENT[Client] <-->|invoke, poll, stream, reconnect| RUNTIME["Managed Runtime / HTTP server"]
+    RUNTIME -->|invoke or recovery hook| AGENT["Agent loop"]
+    AGENT -->|stream events and result| RUNTIME
+    RUNTIME <--> RUNTIME_STORE[("Runtime Store<br/>requests, status, heartbeats,<br/>events, and results")]
+    AGENT <--> SESSION_STORE[("Session Store<br/>conversation state and checkpoints")]
+```
+
+- **Runtime Store:** Requests, status, heartbeats, events, and results used by the runtime to manage
+  invocations, serve polling and reconnection, and detect interrupted work.
+- **Session Store:** Conversation history and framework checkpoints used by the agent. A recovery
+  handler can use these checkpoints to resume the agent loop.
+- **Memory Store:** Long-term facts and preferences reused across conversations.
+
+### Local development
+
+`ab dev` supports the same invocation APIs with an **In-process Runtime Store**. Run state,
+events, and results are lost when the serving process exits. Interrupted work is not automatically
+restarted. Session and Memory Store persistence is separate from this local execution state.
+
+### Deployed execution
+
+`ab deploy` provisions a dedicated PostgreSQL database for each deployment with `server = "agentbricks"` and
+reuses it on redeployment. Results and events survive worker restarts, and any replica can serve
+polling and stream-reconnection requests. With a recovery handler registered, the runtime detects stale
+heartbeats and starts a replacement attempt on an available worker.
+
+App-auth replacement attempts call the registered recovery handler. Request-user replacement
+attempts fail with `MCP_USER_AUTH_RECOVERY_UNSUPPORTED` before agent code runs because the original
+forwarded credential was intentionally not persisted.
+
+Recovery is **at-least-once**: an interrupted attempt may already have performed external side
+effects before its replacement starts. Make those operations idempotent. Request deduplication
+does not guarantee that agent code or external side effects execute only once.
+
+The managed deployment provisions the Runtime Store's database, schema, and access, so you do not
+create or bind it separately. Session and Memory Stores are independently named resources that
+can be shared intentionally between agents.
+
+Changing the server type of an existing deployment is not supported. Scaffold a new project with
+the desired `ab init --server` option and deploy it under a new name. `agent.toml` remains editable,
+but changing its `server` field does not convert application code or clean up deployment resources.
+
+For runtime contributors, see the [architecture and code map](ARCHITECTURE.md).

databricks_agentkit/runtime/__init__.py

@@ -0,0 +1,69 @@
+"""Framework-neutral runtime helpers for an agent deployed on Databricks (via ``databricks-agentbricks``).
+
+These have no agent-framework dependency — MLflow tracing setup and workspace-routed SDK client
+construction — so they work regardless of which framework an agent is built with. Framework-specific
+helpers (session-store checkpointer, MCP tools, memory tools) live in the per-framework adapter
+package, e.g. :mod:`databricks_agentkit.langgraph`, which re-exports these for a single import point.
+
+``__all__`` is the supported surface. ``tool_manifest`` and ``session_store_client`` are internal and
+reachable by their submodule paths but not re-exported here.
+
+The re-exports below are resolved lazily (PEP 562) so importing a neutral submodule such as
+``databricks_agentkit.runtime.tool_manifest`` does not pull in the tracing module's ``mlflow`` dependency.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from databricks_agentkit.runtime.app import AgentApp, DurableAgentServer
+    from databricks_agentkit.runtime.auth import (
+        AuthError,
+        InvocationAuthPolicy,
+        RequestAuthContext,
+    )
+    from databricks_agentkit.runtime.model_services import list_ai_gateway_model_services
+    from databricks_agentkit.runtime.tracing import configure_tracing, start_trace
+    from databricks_agentkit.runtime.types import InvocationContext
+    from databricks_agentkit.runtime.workspace import workspace_client, workspace_headers
+
+__all__ = [
+    "DurableAgentServer",
+    "AgentApp",
+    "InvocationContext",
+    "AuthError",
+    "InvocationAuthPolicy",
+    "RequestAuthContext",
+    # MLflow tracing — call configure_tracing() once at startup (pass the framework's autolog, or use
+    # a framework adapter that binds it). Wrap each invocation in start_trace() so a trace is recorded
+    # (framework autolog only nests under an active trace); pass session_id= to group traces by session.
+    "configure_tracing",
+    "start_trace",
+    # Workspace SDK client construction (account-host / run-local routing handled).
+    "workspace_client",
+    "workspace_headers",
+    # Unity Catalog AI Gateway discovery (system.ai chat model services, for the demo UI's picker).
+    "list_ai_gateway_model_services",
+]
+
+_MODULE_BY_NAME = {
+    "DurableAgentServer": "app",
+    "AgentApp": "app",
+    "InvocationContext": "types",
+    "AuthError": "auth",
+    "InvocationAuthPolicy": "auth",
+    "RequestAuthContext": "auth",
+    "configure_tracing": "tracing",
+    "start_trace": "tracing",
+    "workspace_client": "workspace",
+    "workspace_headers": "workspace",
+    "list_ai_gateway_model_services": "model_services",
+}
+
+
+def __getattr__(name: str) -> object:
+    module = _MODULE_BY_NAME.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    return getattr(importlib.import_module(f"{__name__}.{module}"), name)

databricks_agentkit/runtime/app.py

@@ -0,0 +1,316 @@
+"""FastAPI adapter for the Agent Bricks agent runtime."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import json
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from uuid import UUID
+
+from fastapi import FastAPI, HTTPException, Request, Response
+from fastapi.responses import JSONResponse, StreamingResponse
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic import JsonValue as PydanticJsonValue
+
+from databricks_agentkit.runtime.auth import AuthError, InvocationAuthPolicy, RequestAuthContext
+from databricks_agentkit.runtime.runtime import Runtime
+from databricks_agentkit.runtime.store import RuntimeStore
+from databricks_agentkit.runtime.types import (
+    Invocation,
+    InvocationAttemptContext,
+    InvocationConflictError,
+    InvocationContext,
+    InvocationFailedError,
+    InvocationHook,
+    InvocationStatus,
+    JsonObject,
+    JsonValue,
+)
+
+logger = logging.getLogger(__name__)
+
+_ROUTING_COOKIE = "__Host-databricks-app-router"
+_API_ROOT = "/api/invocations"
+
+
+class _InvocationRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: UUID
+    input: PydanticJsonValue = Field(default_factory=list)
+    background: bool = False
+    stream: bool = False
+
+
+class DurableAgentServer(FastAPI):
+    """Expose agent handlers through the Agent Bricks invocation HTTP protocol.
+
+    ``ab dev`` selects a process-local Runtime Store. A deployed Agent Bricks server receives a
+    Lakebase-backed Runtime Store, which preserves invocation state and can recover stale work when
+    a handler is registered with :meth:`recover`.
+    """
+
+    def __init__(
+        self,
+        *,
+        runtime_store: RuntimeStore | None = None,
+        auth_policy: InvocationAuthPolicy | None = None,
+    ) -> None:
+        self.auth_policy = (
+            auth_policy
+            if auth_policy is not None
+            else InvocationAuthPolicy.from_manifest(allow_missing=True)
+        )
+        self._invoke_hook: InvocationHook | None = None
+        self._recovery_hook: InvocationHook | None = None
+        self._request_auth: dict[str, RequestAuthContext] = {}
+        if runtime_store is None:
+            self._runtime = Runtime.from_environment(
+                self._execute,
+                recovery_enabled=lambda: self._recovery_hook is not None,
+            )
+        else:
+            self._runtime = Runtime.from_store(
+                self._execute,
+                runtime_store=runtime_store,
+                recovery_enabled=lambda: self._recovery_hook is not None,
+            )
+
+        @asynccontextmanager
+        async def lifespan(_: FastAPI):
+            if self._invoke_hook is None:
+                raise RuntimeError("register an invocation handler with @app.invoke")
+            if self._runtime.is_durable and self._recovery_hook is None:
+                logger.warning(
+                    "No @app.recover handler is registered; automatic crash recovery is disabled."
+                )
+            await self._runtime.start()
+            try:
+                yield
+            finally:
+                await self._runtime.stop()
+                self._close_request_auth()
+
+        super().__init__(
+            title="Databricks Agent Runtime",
+            lifespan=lifespan,
+            docs_url=None,
+            redoc_url=None,
+            openapi_url=None,
+        )
+        self.add_exception_handler(AuthError, self._auth_error)
+        self.middleware("http")(self._bind_session)
+        self.add_api_route(_API_ROOT, self._invoke_request, methods=["POST"])
+        self.add_api_route(f"{_API_ROOT}/{{invocation_id}}", self._get_request, methods=["GET"])
+        self.add_api_route(
+            f"{_API_ROOT}/{{invocation_id}}/events",
+            self._events,
+            methods=["GET"],
+        )
+
+    def invoke(self, function: InvocationHook) -> InvocationHook:
+        """Register the handler for an invocation's first attempt."""
+        if self._invoke_hook is not None:
+            raise ValueError("an invocation handler is already registered")
+        self._invoke_hook = function
+        return function
+
+    def recover(self, function: InvocationHook) -> InvocationHook:
+        """Register the handler used after an interrupted attempt becomes stale."""
+        if self._recovery_hook is not None:
+            raise ValueError("a recovery handler is already registered")
+        self._recovery_hook = function
+        return function
+
+    async def _bind_session(self, request: Request, call_next) -> Response:
+        # TODO: Read the standard session header once Databricks Apps supports one. The Apps proxy
+        # currently consumes its routing cookie before forwarding deployed requests, so the
+        # invocation ID becomes the deterministic session fallback in _invoke_request.
+        request.state.session_id = request.cookies.get(_ROUTING_COOKIE)
+        return await call_next(request)
+
+    async def _execute(
+        self,
+        invocation_request: JsonValue,
+        attempt_context: InvocationAttemptContext,
+    ) -> JsonValue:
+        if not isinstance(invocation_request, dict):
+            raise TypeError("invocation request must be an object")
+        session_id = invocation_request.get("session_id")
+        if not isinstance(session_id, str) or "input" not in invocation_request:
+            raise TypeError("invocation request must contain session_id and input")
+        invocation_id = attempt_context.invocation_id
+        request_auth = None
+        if self.auth_policy.requires_user:
+            request_auth = self._request_auth.pop(attempt_context.invocation_id, None)
+            if attempt_context.is_recovery:
+                if request_auth is not None:
+                    request_auth.close()
+                raise AuthError(
+                    "MCP_USER_AUTH_RECOVERY_UNSUPPORTED",
+                    "Request-user execution does not survive failure recovery yet",
+                    500,
+                )
+            if request_auth is None:
+                raise AuthError(
+                    "MCP_USER_AUTH_RECOVERY_UNSUPPORTED",
+                    "Request-user execution does not survive failure recovery yet",
+                    500,
+                )
+            invocation_id = invocation_request.get("invocation_id")
+            if not isinstance(invocation_id, str):
+                request_auth.close()
+                raise TypeError("request-user invocation must contain invocation_id")
+
+        context = InvocationContext(
+            invocation_id=invocation_id,
+            session_id=session_id,
+            attempt=attempt_context.attempt,
+            _attempt_context=attempt_context,
+            request_auth=request_auth,
+        )
+        function = self._recovery_hook if context.is_recovery else self._invoke_hook
+        try:
+            if function is None:
+                handler = "@app.recover" if context.is_recovery else "@app.invoke"
+                raise RuntimeError(f"no {handler} handler is registered")
+            return await function(copy.deepcopy(invocation_request["input"]), context)
+        finally:
+            if request_auth is not None:
+                request_auth.close()
+
+    async def _invoke_request(self, request: Request, body: _InvocationRequest) -> Response:
+        invocation_id = str(body.id)
+        runtime_invocation_id = invocation_id
+        request_auth = None
+        registered_auth = False
+        execution_owns_auth = False
+        session_id = request.state.session_id or invocation_id
+        if self.auth_policy.requires_user:
+            request_auth = RequestAuthContext.from_headers(request.headers)
+            runtime_invocation_id = request_auth.namespace("invocation", invocation_id)
+            session_id = request_auth.namespace("session", session_id)
+            existing_auth = self._request_auth.setdefault(runtime_invocation_id, request_auth)
+            registered_auth = existing_auth is request_auth
+            if not registered_auth:
+                request_auth.close()
+        invocation_request: JsonObject = {
+            "session_id": session_id,
+            "input": copy.deepcopy(body.input),
+        }
+        if self.auth_policy.requires_user:
+            invocation_request["invocation_id"] = invocation_id
+        try:
+            if body.background:
+                state = await self._runtime.submit(runtime_invocation_id, invocation_request)
+                execution_owns_auth = registered_auth and state.status == InvocationStatus.QUEUED
+                return JSONResponse(
+                    self._accepted_payload(state, stream=body.stream, invocation_id=invocation_id),
+                    status_code=202,
+                )
+            if body.stream:
+                state = await self._runtime.submit(runtime_invocation_id, invocation_request)
+                execution_owns_auth = registered_auth and state.status == InvocationStatus.QUEUED
+                return StreamingResponse(
+                    self._event_stream(runtime_invocation_id),
+                    media_type="text/event-stream",
+                )
+            output = await self._runtime.invoke(runtime_invocation_id, invocation_request)
+            return JSONResponse({"id": invocation_id, "status": "completed", "output": output})
+        except InvocationConflictError as exc:
+            raise HTTPException(409, "id was already used for another request") from exc
+        except InvocationFailedError as exc:
+            raise HTTPException(500, "agent invocation failed") from exc
+        finally:
+            if registered_auth and not execution_owns_auth and request_auth is not None:
+                self._discard_request_auth(runtime_invocation_id, request_auth)
+
+    async def _auth_error(self, request: Request, error: Exception) -> JSONResponse:
+        assert isinstance(error, AuthError)
+        return JSONResponse({"error": error.payload()}, status_code=error.status_code)
+
+    async def _get_request(self, request: Request, invocation_id: UUID) -> JSONResponse:
+        public_invocation_id = str(invocation_id)
+        runtime_invocation_id = self._runtime_invocation_id(request, public_invocation_id)
+        state = await self._runtime.get_invocation(runtime_invocation_id)
+        if state is None:
+            raise HTTPException(404, "invocation not found")
+        return JSONResponse(self._state_payload(state, invocation_id=public_invocation_id))
+
+    async def _events(
+        self, request: Request, invocation_id: UUID, after: int = 0
+    ) -> StreamingResponse:
+        public_invocation_id = str(invocation_id)
+        runtime_invocation_id = self._runtime_invocation_id(request, public_invocation_id)
+        if await self._runtime.get_invocation(runtime_invocation_id) is None:
+            raise HTTPException(404, "invocation not found")
+        return StreamingResponse(
+            self._event_stream(runtime_invocation_id, after),
+            media_type="text/event-stream",
+        )
+
+    async def _event_stream(self, invocation_id: str, after: int = 0) -> AsyncIterator[str]:
+        cursor = after
+        while True:
+            for event in await self._runtime.get_events(invocation_id, after_sequence=cursor):
+                cursor = event.sequence_number
+                event_type = event.event.get("type", "message")
+                yield f"id: {cursor}\nevent: {event_type}\ndata: {json.dumps(event.event)}\n\n"
+
+            state = await self._runtime.get_invocation(invocation_id)
+            if state is None or state.is_terminal:
+                return
+            await asyncio.sleep(self._runtime.poll_seconds)
+
+    @staticmethod
+    def _accepted_payload(
+        state: Invocation, *, stream: bool, invocation_id: str | None = None
+    ) -> JsonObject:
+        invocation_id = invocation_id or state.invocation_id
+        payload: JsonObject = {
+            "id": invocation_id,
+            "status": state.status.value.lower(),
+            "status_url": f"{_API_ROOT}/{invocation_id}",
+        }
+        if stream:
+            payload["events_url"] = f"{_API_ROOT}/{invocation_id}/events"
+        return payload
+
+    @staticmethod
+    def _state_payload(state: Invocation, *, invocation_id: str | None = None) -> JsonObject:
+        payload: JsonObject = {
+            "id": invocation_id or state.invocation_id,
+            "status": state.status.value.lower(),
+        }
+        if state.status == InvocationStatus.COMPLETED:
+            payload["output"] = copy.deepcopy(state.response)
+        elif state.status == InvocationStatus.FAILED:
+            payload["error"] = "agent invocation failed"
+        return payload
+
+    def _runtime_invocation_id(self, request: Request, invocation_id: str) -> str:
+        if not self.auth_policy.requires_user:
+            return invocation_id
+        request_auth = RequestAuthContext.from_headers(request.headers)
+        try:
+            return request_auth.namespace("invocation", invocation_id)
+        finally:
+            request_auth.close()
+
+    def _discard_request_auth(self, invocation_id: str, request_auth: RequestAuthContext) -> None:
+        if self._request_auth.get(invocation_id) is request_auth:
+            self._request_auth.pop(invocation_id)
+        request_auth.close()
+
+    def _close_request_auth(self) -> None:
+        request_auths = list(self._request_auth.values())
+        self._request_auth.clear()
+        for request_auth in request_auths:
+            request_auth.close()
+
+
+# Deprecated compatibility alias. New code should use DurableAgentServer.
+AgentApp = DurableAgentServer