Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,49 @@ text to the agent.
- 📊 **Observability** - OpenTelemetry tracing: **[Get started](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-get-started.html)**
- 🔐 **Identity** - AWS & third-party auth: **[Get started](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-getting-started.html)**

## Build Warmup Hook

On platform version V2, AgentCore Runtime can call a [build warmup hook](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-lifecycle-hooks.html) while it prepares your agent, before the runtime is `READY`. It sends two `POST` requests, first `memory` (load what every session needs, such as imports, models and caches) and then `disk` (read the files that sessions read at start). Register a handler for either, both or none:

```python
from bedrock_agentcore import BedrockAgentCoreApp, HookConfig, WarmupType

app = BedrockAgentCoreApp(warmup_hook=HookConfig(path="/warmup")) # serves the hook at POST /warmup
MODEL = None

@app.warmup(WarmupType.MEMORY)
def load_model():
global MODEL
MODEL = load_my_model() # runs before the runtime is READY; sessions see what's loaded here

@app.warmup(WarmupType.DISK)
def read_startup_files():
for path in ["/app/config/agent.json"]:
with open(path, "rb") as f:
while f.read(1 << 20):
pass

@app.entrypoint
def invoke(payload):
return MODEL.predict(payload)

app.run()
```

Handlers run off the event loop, so `/ping` keeps answering. A type without a handler returns 200; an exception returns 500, which fails the create or update. The two calls share a 120-second limit. Configure the hook on the runtime:

```python
client.create_agent_runtime(
...,
platformVersion="V2",
hooksConfiguration={"build": {"warmup": {"action": {"httpPost": {"path": "/warmup"}}}}},
)
```

- `HookConfig.path` must equal `hooksConfiguration.build.warmup.action.httpPost.path`. The API requires the path, and the SDK has no default. Without `warmup_hook`, the app adds no warmup route and `@app.warmup` raises `ValueError`.
- Leave `httpPost.port` unset, or set it to the port the app serves on (`app.run(port=...)`, default 8080). The app doesn't serve the hook on a different port, so the hook call fails.
- Serve the hook from one server process. The memory call reaches one process. That process may start child processes (for example a browser or a model server) and keep them, but other worker processes (for example `uvicorn --workers N`) don't receive the call.

## AG-UI Protocol Support

Deploy agents using the [AG-UI protocol](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-agui.html) with zero boilerplate. A single `entrypoint` handler is served over both SSE (`POST /invocations`) and WebSocket (`/ws`).
Expand Down
4 changes: 3 additions & 1 deletion src/bedrock_agentcore/__init__.py
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
"""BedrockAgentCore Runtime SDK - A Python SDK for building and deploying AI agents."""

from .runtime import BedrockAgentCoreApp, BedrockAgentCoreContext, RequestContext
from .runtime.models import PingStatus
from .runtime.models import HookConfig, PingStatus, WarmupType

__all__ = [
"BedrockAgentCoreApp",
"RequestContext",
"BedrockAgentCoreContext",
"PingStatus",
"WarmupType",
"HookConfig",
]
4 changes: 3 additions & 1 deletion src/bedrock_agentcore/runtime/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
from .app import BedrockAgentCoreApp
from .context import BedrockAgentCoreContext, RequestContext
from .local_endpoint import LocalEndpoint
from .models import PingStatus
from .models import HookConfig, PingStatus, WarmupType
from .session_endpoint import (
InvalidSessionEndpointError,
SessionEndpointClient,
Expand Down Expand Up @@ -45,6 +45,8 @@
"ReconnectConfig",
"RequestContext",
"PingStatus",
"WarmupType",
"HookConfig",
"SessionEndpointClient",
"SessionEndpointResponse",
"LocalEndpoint",
Expand Down
131 changes: 127 additions & 4 deletions src/bedrock_agentcore/runtime/app.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,15 @@
import time
import uuid
from collections.abc import Sequence
from dataclasses import dataclass, field
from typing import Any, Callable, Dict, Optional

from starlette.applications import Starlette
from starlette.concurrency import run_in_threadpool
from starlette.exceptions import HTTPException
from starlette.middleware import Middleware
from starlette.responses import JSONResponse, Response, StreamingResponse
from starlette.routing import Route, WebSocketRoute
from starlette.routing import BaseRoute, Route, WebSocketRoute
from starlette.types import Lifespan
from starlette.websockets import WebSocket, WebSocketDisconnect

Expand All @@ -46,7 +47,10 @@
TASK_ACTION_FORCE_HEALTHY,
TASK_ACTION_JOB_STATUS,
TASK_ACTION_PING_STATUS,
WARMUP_TYPE_HEADER,
HookConfig,
PingStatus,
WarmupType,
is_forwardable_header,
)
from .tracing import _ensure_baggage_processor_registered
Expand Down Expand Up @@ -155,6 +159,29 @@ def format(self, record):
return json.dumps(log_entry, ensure_ascii=False)


def _add_route(route: Route, routes: list[BaseRoute]) -> None:
"""Append route to routes, raising ValueError if one of its (method, path) pairs is already served.

Only HTTP routes count: a WebSocketRoute serves WebSocket connections (a GET upgrade), never a POST.
"""
served = {(method, r.path) for r in routes if isinstance(r, Route) for method in r.methods or ()}
clashes = sorted({(method, route.path) for method in route.methods or ()} & served)
if clashes:
raise ValueError(f"Route {', '.join(m for m, _ in clashes)} {route.path} is already served by the app")
routes.append(route)


@dataclass
class _Hook:
"""One lifecycle hook: where it's served, its handlers, and the lock that keeps its calls from overlapping."""

config: HookConfig
handlers: Dict[Any, Callable] = field(default_factory=dict) # warmup: WarmupType -> handler
# One lock per hook, so its calls never overlap. A waiting call awaits the lock rather than
# blocking, so the server keeps answering /ping.
lock: asyncio.Lock = field(default_factory=asyncio.Lock) # used only by this hook's route


class BedrockAgentCoreApp(Starlette):
"""Bedrock AgentCore application class that extends Starlette for AI agent deployment."""

Expand All @@ -163,13 +190,22 @@ def __init__(
debug: bool = False,
lifespan: Optional[Lifespan] = None,
middleware: Sequence[Middleware] | None = None,
*,
warmup_hook: Optional[HookConfig] = None,
):
"""Initialize Bedrock AgentCore application.

Args:
debug: Enable debug actions for task management (default: False)
lifespan: Optional lifespan context manager for startup/shutdown
middleware: Optional sequence of Starlette Middleware objects (or Middleware(...) entries)
warmup_hook: Where to serve the build warmup hook (``POST``), registered with ``@app.warmup``.
``warmup_hook.path`` must equal ``hooksConfiguration.build.warmup.action.httpPost.path``, which
the API requires. The hook is served on the serving port, so leave ``httpPost.port`` unset or

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update this once port is supported: the hook is served on warmup_hook.port when set, otherwise on the serving port.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated in 4ee3750.

set it to the serving port. ``None`` (the default) adds no warmup route.

Raises:
ValueError: If ``warmup_hook.path`` clashes with an existing ``POST`` route such as ``/invocations``.
"""
self.handlers: Dict[str, Callable] = {}
self._ping_handler: Optional[Callable] = None
Expand All @@ -181,6 +217,10 @@ def __init__(
self._worker_loop: Optional[asyncio.AbstractEventLoop] = None
self._worker_thread: Optional[threading.Thread] = None
self._worker_loop_lock: threading.Lock = threading.Lock()
self._hooks: Dict[str, _Hook] = {}
if warmup_hook is not None:
self._hooks["warmup"] = _Hook(warmup_hook)
self.warmup_hook = warmup_hook

# Config bundle client — created lazily on first use.
# _resolve_bundle_config is wrapped with lru_cache(maxsize=30), keyed by
Expand All @@ -192,11 +232,13 @@ def __init__(
self._resolve_bundle_config
)

routes = [
routes: list[BaseRoute] = [
Route("/invocations", self._handle_invocation, methods=["POST"]),
Route("/ping", self._handle_ping, methods=["GET"]),
WebSocketRoute("/ws", self._handle_websocket),
]
if warmup_hook is not None:
_add_route(Route(warmup_hook.path, self._handle_warmup, methods=["POST"]), routes)
super().__init__(routes=routes, lifespan=lifespan, middleware=middleware)
self.debug = debug # Set after super().__init__ to avoid override

Expand Down Expand Up @@ -262,6 +304,53 @@ async def handler(websocket, context):
self._websocket_handler = func
return func

def warmup(self, type: WarmupType | str) -> Callable[[Callable], Callable]:
"""Decorator to register a build warmup handler for one warmup type.

AgentCore Runtime calls the build warmup hook (``POST`` to ``warmup_hook.path``) twice while it prepares
the agent during ``CreateAgentRuntime`` and ``UpdateAgentRuntime``: first ``memory``, then ``disk``.
Register a handler for zero, one or both types. A type without a handler is answered with 200, so
it has nothing to do. The handler takes no arguments and may be sync or async: sync handlers run in a
worker thread and async handlers on a separate event loop, so the server keeps answering ``/ping``
while they run. The response is sent after the handler returns. An exception in the handler returns
500, which fails the create or update. Handlers never run concurrently with each other in one process.

See https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-lifecycle-hooks.html

Args:
type: The warmup type to handle, a ``WarmupType`` or its string value (``"memory"`` or ``"disk"``)

Returns:
A decorator that registers the function and returns it unchanged

Raises:
ValueError: If the app has no ``warmup_hook``, ``type`` isn't a valid warmup type, or a handler is
already registered for it.

Example:
app = BedrockAgentCoreApp(warmup_hook=HookConfig(path="/warmup"))

@app.warmup(WarmupType.MEMORY)
def load_model():
global MODEL
MODEL = load("/opt/model.bin")
"""
if "warmup" not in self._hooks:
raise ValueError(
"@app.warmup needs BedrockAgentCoreApp(warmup_hook=HookConfig(path=...)) matching "
"hooksConfiguration.build.warmup.action.httpPost.path"
)
warmup_type = WarmupType(type)
handlers = self._hooks["warmup"].handlers
if warmup_type in handlers:
raise ValueError(f"A {warmup_type.value} warmup handler is already registered")

def register(func: Callable) -> Callable:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A generator or async-generator handler passes registration, then _dispatch_handler returns a generator that nobody iterates. The route reports completed and the handler body never runs. Can we reject generator functions here with a ValueError and add a test?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 40bbb06. @app.warmup raises ValueError for generator and async-generator functions, including ones wrapped in functools.partial or a callable object's __call__. A handler that returns a generator at call time gets a 500. Tests added.

handlers[warmup_type] = func
return func

return register

def async_task(self, func: Callable) -> Callable:
"""Decorator to track async tasks for ping status.

Expand Down Expand Up @@ -623,6 +712,36 @@ def _handle_ping(self, request):
self.logger.exception("Ping endpoint failed")
return JSONResponse({"status": PingStatus.HEALTHY.value, "time_of_last_update": int(time.time())})

async def _handle_warmup(self, request):
raw_type = request.headers.get(WARMUP_TYPE_HEADER, "").strip().lower()
try:
warmup_type = WarmupType(raw_type)
except ValueError:
self.logger.warning("Warmup request with invalid %s header: %r", WARMUP_TYPE_HEADER, raw_type)
return JSONResponse(
{"error": f"{WARMUP_TYPE_HEADER} must be 'memory' or 'disk', got {raw_type!r}"}, status_code=400

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we return 200 with result: skipped for an unknown but well-formed warmup type, and keep 400 only for a missing header? If the service adds a third type later, every deployed agent on this SDK version would fail the create.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 40bbb06. An unknown, well-formed type returns 200 {"result": "skipped"}; only a missing or empty header returns 400.

)

hook = self._hooks["warmup"]
handler = hook.handlers.get(warmup_type)
if handler is None:
self.logger.info("Warmup (%s): no handler registered, nothing to do", warmup_type.value)
return JSONResponse({"status": "ok", "type": warmup_type.value, "result": "skipped"})

async with hook.lock:
start_time = time.time()
try:
result = await self._dispatch_handler(handler, ())
if inspect.isawaitable(result):
if inspect.iscoroutine(result):
result.close() # never awaited on purpose; close it so Python doesn't warn
raise TypeError("warmup handler returned an awaitable; declare it with async def")
except Exception as e:
self.logger.exception("Warmup (%s) failed (%.3fs)", warmup_type.value, time.time() - start_time)
return JSONResponse({"error": str(e), "type": warmup_type.value}, status_code=500)
self.logger.info("Warmup (%s) completed (%.3fs)", warmup_type.value, time.time() - start_time)
return JSONResponse({"status": "ok", "type": warmup_type.value, "result": "completed"})

async def _handle_websocket(self, websocket: WebSocket):
"""Handle WebSocket connections."""
request_context = self._build_request_context(websocket)
Expand Down Expand Up @@ -806,7 +925,12 @@ def _cancel() -> None:
worker_loop.call_soon_threadsafe(_cancel)

async def _invoke_handler(self, handler: Callable, request_context: Any, takes_context: bool, payload: Any) -> Any:
"""Dispatch handler execution based on handler type.
"""Build the handler arguments, ``(payload[, context])``, and call it through ``_dispatch_handler``."""
args = (payload, request_context) if takes_context else (payload,)
return await self._dispatch_handler(handler, args)

async def _dispatch_handler(self, handler: Callable, args: tuple) -> Any:
"""Call ``handler(*args)`` based on the handler type.

- Async generator functions: bridged through the worker loop as a sync generator
- Regular async functions: run on the dedicated worker event loop
Expand All @@ -816,7 +940,6 @@ async def _invoke_handler(self, handler: Callable, request_context: Any, takes_c
regardless of whether handlers contain blocking operations.
"""
try:
args = (payload, request_context) if takes_context else (payload,)
ctx = contextvars.copy_context()

if _is_async_gen_callable(handler):
Expand Down
61 changes: 61 additions & 0 deletions src/bedrock_agentcore/runtime/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,8 @@
Contains data models and enums used throughout the runtime system.
"""

import re
from dataclasses import dataclass
from enum import Enum


Expand All @@ -13,6 +15,64 @@ class PingStatus(str, Enum):
HEALTHY_BUSY = "HealthyBusy"


class WarmupType(str, Enum):
"""Build warmup call type, sent by AgentCore Runtime in the ``WARMUP_TYPE_HEADER`` header.

AgentCore Runtime calls the build warmup hook twice, first with ``memory`` and then with ``disk``.
See https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-lifecycle-hooks.html
"""

MEMORY = "memory"
DISK = "disk"


# Mirrors the public API constraints for HttpPostLifecycleHookAction.
_LIFECYCLE_HOOK_PATH_MAX_LENGTH = 32
_LIFECYCLE_HOOK_PATH_PATTERN = re.compile(r"^/[A-Za-z0-9._~/-]*$")


@dataclass(frozen=True)
class HookConfig:
"""Where the app serves a lifecycle hook, matching the runtime's ``hooksConfiguration``.

The app serves the hook as ``POST`` on ``path``, on the app's serving port (``app.run(port=...)``, default
8080). Leave ``hooksConfiguration.<hook>.action.httpPost.port`` unset, or set it to the app's serving port.

See https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-lifecycle-hooks.html

Attributes:
path: Path of the hook route. Must equal ``hooksConfiguration.<hook>.action.httpPost.path``, which the
API requires: 1-32 characters, starting with ``/``, from ``A-Z a-z 0-9 . _ ~ / -``, and in canonical
form: no trailing ``/`` (except the path ``/`` itself), no ``//``, and no ``.`` or ``..`` segments.

Raises:
ValueError: If ``path`` doesn't meet the API constraints.
"""

path: str

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add port to HookConfig, matching hooksConfiguration.<hook>.action.httpPost.port (8000-12000) and TS #330? When it differs from the serving port, serve the hook on its own listener. Customers who run their own server on 8080 need the hook on a separate port.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 4ee3750. HookConfig.port (8000-12000) serves the hook on its own listener on 127.0.0.1, in the same process, opened by app.run() before the serving port and closed after it. A port equal to the serving port is served by the main app. The listener is started from the app's lifespan, so a separate port needs app.run(): app.run(lifespan="off") raises ValueError, and other launches (e.g. uvicorn agent:app) fail startup with a message saying so. End-to-end test results will be added to the description.


def __post_init__(self):
"""Validate ``path`` against the API constraints."""
path = self.path
if not isinstance(path, str):
raise ValueError(f"HookConfig.path must be a string, got {path!r}")
if not 1 <= len(path) <= _LIFECYCLE_HOOK_PATH_MAX_LENGTH:
raise ValueError(
f"HookConfig.path must be between 1 and {_LIFECYCLE_HOOK_PATH_MAX_LENGTH} characters, got {path!r}"
)
if not _LIFECYCLE_HOOK_PATH_PATTERN.fullmatch(path):
raise ValueError(
"HookConfig.path must start with '/' and contain only letters, numbers, '.', '_', '~', '/' and '-', "
f"got {path!r}"
)
segments = path[1:].split("/")
if path != "/" and (path.endswith("/") or "//" in path or any(seg in (".", "..") for seg in segments)):
raise ValueError(
"HookConfig.path must be canonical: no trailing '/' (except '/' itself), no '//', "
f"and no '.' or '..' segments, got {path!r}"
)


# Header constants
SESSION_HEADER = "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id"
SHELL_ID_HEADER = "X-Amzn-Bedrock-AgentCore-Shell-Id"
Expand All @@ -22,6 +82,7 @@ class PingStatus(str, Enum):
OAUTH2_CALLBACK_URL_HEADER = "OAuth2CallbackUrl"
AUTHORIZATION_HEADER = "Authorization"
CUSTOM_HEADER_PREFIX = "X-Amzn-Bedrock-AgentCore-Runtime-Custom-"
WARMUP_TYPE_HEADER = "X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type"
AGENTCORE_RUNTIME_URL_ENV = "AGENTCORE_RUNTIME_URL"

# Headers that cannot be forwarded to agent code.
Expand Down
Loading
Loading