Repository navigation
feat(runtime): add @app.warmup decorator for build warmup lifecycle hooks #746
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| 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", | ||
| ] |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 | ||
|
|
||
|
|
@@ -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 | ||
|
|
@@ -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.""" | ||
|
|
||
|
|
@@ -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 | ||
| 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 | ||
|
|
@@ -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 | ||
|
|
@@ -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 | ||
|
|
||
|
|
@@ -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: | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. A generator or async-generator handler passes registration, then
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done in 40bbb06. |
||
| handlers[warmup_type] = func | ||
| return func | ||
|
|
||
| return register | ||
|
|
||
| def async_task(self, func: Callable) -> Callable: | ||
| """Decorator to track async tasks for ping status. | ||
|
|
||
|
|
@@ -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 | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can we return
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done in 40bbb06. An unknown, well-formed type returns 200 |
||
| ) | ||
|
|
||
| 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) | ||
|
|
@@ -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 | ||
|
|
@@ -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): | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,6 +3,8 @@ | |
| Contains data models and enums used throughout the runtime system. | ||
| """ | ||
|
|
||
| import re | ||
| from dataclasses import dataclass | ||
| from enum import Enum | ||
|
|
||
|
|
||
|
|
@@ -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 | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can we add
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Done in 4ee3750. |
||
|
|
||
| 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" | ||
|
|
@@ -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. | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Update this once
portis supported: the hook is served onwarmup_hook.portwhen set, otherwise on the serving port.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated in 4ee3750.