diff --git a/README.md b/README.md index e3d909a9..ee578512 100644 --- a/README.md +++ b/README.md @@ -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`). diff --git a/src/bedrock_agentcore/__init__.py b/src/bedrock_agentcore/__init__.py index a77472f5..90574c0d 100644 --- a/src/bedrock_agentcore/__init__.py +++ b/src/bedrock_agentcore/__init__.py @@ -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", ] diff --git a/src/bedrock_agentcore/runtime/__init__.py b/src/bedrock_agentcore/runtime/__init__.py index fcd7f66e..08e7e6f1 100644 --- a/src/bedrock_agentcore/runtime/__init__.py +++ b/src/bedrock_agentcore/runtime/__init__.py @@ -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, @@ -45,6 +45,8 @@ "ReconnectConfig", "RequestContext", "PingStatus", + "WarmupType", + "HookConfig", "SessionEndpointClient", "SessionEndpointResponse", "LocalEndpoint", diff --git a/src/bedrock_agentcore/runtime/app.py b/src/bedrock_agentcore/runtime/app.py index c291b255..c1b8164b 100644 --- a/src/bedrock_agentcore/runtime/app.py +++ b/src/bedrock_agentcore/runtime/app.py @@ -16,6 +16,7 @@ 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 @@ -23,7 +24,7 @@ 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,6 +190,8 @@ def __init__( debug: bool = False, lifespan: Optional[Lifespan] = None, middleware: Sequence[Middleware] | None = None, + *, + warmup_hook: Optional[HookConfig] = None, ): """Initialize Bedrock AgentCore application. @@ -170,6 +199,13 @@ def __init__( 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: + 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 + ) + + 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): diff --git a/src/bedrock_agentcore/runtime/models.py b/src/bedrock_agentcore/runtime/models.py index db0cef82..135e1385 100644 --- a/src/bedrock_agentcore/runtime/models.py +++ b/src/bedrock_agentcore/runtime/models.py @@ -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..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..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 + + 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. diff --git a/tests/bedrock_agentcore/runtime/test_app.py b/tests/bedrock_agentcore/runtime/test_app.py index 60169a5a..a60bb59e 100644 --- a/tests/bedrock_agentcore/runtime/test_app.py +++ b/tests/bedrock_agentcore/runtime/test_app.py @@ -2,6 +2,8 @@ import concurrent.futures import contextlib import contextvars +import dataclasses +import inspect import json import os import threading @@ -10,6 +12,7 @@ from decimal import Decimal from unittest.mock import MagicMock, patch +import httpx import pytest from starlette.testclient import TestClient @@ -18,7 +21,7 @@ from bedrock_agentcore.runtime import BedrockAgentCoreApp from bedrock_agentcore.runtime.app import _parse_runtime_arn from bedrock_agentcore.runtime.context import BedrockAgentCoreContext -from bedrock_agentcore.runtime.models import is_forwardable_header +from bedrock_agentcore.runtime.models import HookConfig, WarmupType, is_forwardable_header class TestBedrockAgentCoreApp: @@ -3196,3 +3199,381 @@ async def stalled_stream(): "producer parked in a mid-await was not torn down on disconnect — " "source generator's finally never ran (task leaked)" ) + + +class TestWarmup: + """Tests for the @app.warmup build warmup hook decorator and its POST route.""" + + HEADER = "X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type" + + @staticmethod + def _app(path="/warmup"): + return BedrockAgentCoreApp(warmup_hook=HookConfig(path=path)) + + def _post(self, client, warmup_type=None, path="/warmup"): + headers = {self.HEADER: warmup_type} if warmup_type is not None else {} + return client.post(path, headers=headers) + + @contextlib.asynccontextmanager + async def _async_client(self, app): + async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as client: + yield client + + # --- Route and handler results --- + + def test_warmup_route_registered_with_hook(self): + app = self._app() + assert "/warmup" in [route.path for route in app.routes] # type: ignore + assert app.warmup_hook == HookConfig(path="/warmup") + + def test_memory_only_app(self): + app = self._app() + calls = [] + + @app.warmup(WarmupType.MEMORY) + def load(): + calls.append("memory") + + client = TestClient(app) + memory = self._post(client, "memory") + assert memory.status_code == 200 + assert memory.json() == {"status": "ok", "type": "memory", "result": "completed"} + disk = self._post(client, "disk") + assert disk.status_code == 200 + assert disk.json() == {"status": "ok", "type": "disk", "result": "skipped"} + assert calls == ["memory"] + + def test_both_handlers_run_for_their_type(self): + app = self._app() + calls = [] + + @app.warmup(WarmupType.MEMORY) + def memory(): + calls.append("memory") + + @app.warmup(WarmupType.DISK) + def disk(): + calls.append("disk") + + client = TestClient(app) + assert self._post(client, "memory").json()["result"] == "completed" + assert self._post(client, "disk").json()["result"] == "completed" + assert calls == ["memory", "disk"] + + def test_no_handlers_skips_both(self): + client = TestClient(self._app()) + for warmup_type in ("memory", "disk"): + response = self._post(client, warmup_type) + assert response.status_code == 200 + assert response.json() == {"status": "ok", "type": warmup_type, "result": "skipped"} + + @pytest.mark.parametrize("value", ["Memory", "MEMORY", " memory ", "DiSk"]) + def test_header_is_case_and_whitespace_insensitive(self, value): + app = self._app() + calls = [] + + @app.warmup("memory") + def memory(): + calls.append("memory") + + @app.warmup("disk") + def disk(): + calls.append("disk") + + response = self._post(TestClient(app), value) + assert response.status_code == 200 + assert response.json()["type"] == value.strip().lower() + assert calls == [value.strip().lower()] + + @pytest.mark.parametrize("value", [None, "", "cpu", "memory,disk"]) + def test_missing_or_invalid_header_returns_400(self, value): + app = self._app() + calls = [] + + @app.warmup(WarmupType.MEMORY) + def memory(): + calls.append("memory") + + response = self._post(TestClient(app), value) + assert response.status_code == 400 + assert self.HEADER in response.json()["error"] + assert calls == [] + + @pytest.mark.parametrize("is_async", [False, True], ids=["sync", "async"]) + def test_raising_handler_returns_500(self, is_async): + app = self._app() + + def fail(): + raise RuntimeError("model load failed") + + async def fail_async(): + fail() + + app.warmup(WarmupType.MEMORY)(fail_async if is_async else fail) + response = self._post(TestClient(app), "memory") + assert response.status_code == 500 + assert response.json() == {"error": "model load failed", "type": "memory"} + + def test_sync_handler_returning_coroutine_returns_500(self): + app = self._app() + returned = [] + + async def load(): + pass # pragma: no cover - never awaited + + def handler(): + returned.append(load()) + return returned[0] + + app.warmup(WarmupType.MEMORY)(handler) + response = self._post(TestClient(app), "memory") + assert response.status_code == 500 + assert response.json()["type"] == "memory" + assert "async def" in response.json()["error"] + # Closed, so it never warns "coroutine ... was never awaited" when it's collected. (The warning + # itself fires at garbage collection, which the captured log record's traceback delays past the test.) + assert inspect.getcoroutinestate(returned[0]) == inspect.CORO_CLOSED + + def test_sync_handler_returning_other_awaitable_returns_500(self): + class Awaitable: + def __await__(self): + yield # pragma: no cover - never awaited + + app = self._app() + app.warmup(WarmupType.DISK)(lambda: Awaitable()) + response = self._post(TestClient(app), "disk") + assert response.status_code == 500 + assert "async def" in response.json()["error"] + + # --- Dispatch --- + + def test_sync_handler_runs_in_thread_pool(self): + app = self._app() + seen = {} + + @app.warmup(WarmupType.MEMORY) + def memory(): + seen["thread"] = threading.current_thread().ident + + client = TestClient(app) + assert self._post(client, "memory").status_code == 200 + assert seen["thread"] is not None + assert app._worker_loop is None # sync handlers don't use the worker loop + + def test_async_handler_runs_on_worker_loop(self): + app = self._app() + seen = {} + + @app.warmup(WarmupType.MEMORY) + async def memory(): + seen["loop"] = asyncio.get_running_loop() + + response = self._post(TestClient(app), "memory") + assert response.status_code == 200 + assert response.json()["result"] == "completed" + assert seen["loop"] is app._worker_loop + + def test_ping_stays_healthy_after_warmup(self): + app = self._app() + app.warmup(WarmupType.MEMORY)(lambda: None) + client = TestClient(app) + assert self._post(client, "memory").status_code == 200 + assert client.get("/ping").json()["status"] == "Healthy" + + async def test_blocking_sync_handler_does_not_delay_ping(self): + """A sync warmup handler that blocks must not delay a concurrent GET /ping.""" + app = self._app() + started = threading.Event() + + @app.warmup(WarmupType.MEMORY) + def memory(): + started.set() + time.sleep(1.5) + + async with self._async_client(app) as client: + warmup_task = asyncio.create_task(client.post("/warmup", headers={self.HEADER: "memory"})) + for _ in range(100): + if started.is_set(): + break + await asyncio.sleep(0.01) + assert started.is_set() + + ping_start = time.monotonic() + ping = await client.get("/ping") + ping_duration = time.monotonic() - ping_start + + assert not warmup_task.done() + warmup = await warmup_task + + assert ping.status_code == 200 + assert ping.json()["status"] == "Healthy" # not marked busy during warmup + assert ping_duration < 0.5 + assert warmup.status_code == 200 + assert warmup.json()["result"] == "completed" + + def test_lock_is_per_hook(self): + first, second = self._app(), self._app() + assert isinstance(first._hooks["warmup"].lock, asyncio.Lock) + assert first._hooks["warmup"].lock is not second._hooks["warmup"].lock + + async def test_overlapping_warmups_run_sequentially(self): + app = self._app() + lock = threading.Lock() + state = {"active": 0, "max_active": 0} + intervals = [] + + def _work(name): + with lock: + state["active"] += 1 + state["max_active"] = max(state["max_active"], state["active"]) + start = time.monotonic() + time.sleep(0.3) + end = time.monotonic() + with lock: + state["active"] -= 1 + intervals.append((start, end, name)) + + app.warmup(WarmupType.MEMORY)(lambda: _work("memory")) + app.warmup(WarmupType.DISK)(lambda: _work("disk")) + + async with self._async_client(app) as client: + responses = await asyncio.gather( + client.post("/warmup", headers={self.HEADER: "memory"}), + client.post("/warmup", headers={self.HEADER: "disk"}), + client.post("/warmup", headers={self.HEADER: "memory"}), + ) + + assert [r.status_code for r in responses] == [200, 200, 200] + assert state["max_active"] == 1 + intervals.sort() + for (_, prev_end, _), (next_start, _, _) in zip(intervals, intervals[1:], strict=False): + assert next_start >= prev_end + + # --- Decorator --- + + def test_decorator_returns_function_unchanged(self): + app = self._app() + + def memory(): + return 42 + + assert app.warmup(WarmupType.MEMORY)(memory) is memory + assert memory() == 42 + + def test_duplicate_registration_raises(self): + app = self._app() + + @app.warmup(WarmupType.MEMORY) + def first(): + pass + + with pytest.raises(ValueError, match="already registered"): + + @app.warmup("memory") + def second(): + pass + + assert app._hooks["warmup"].handlers[WarmupType.MEMORY] is first + + @pytest.mark.parametrize("value", ["cpu", "", "Memory", None]) + def test_unknown_type_raises_at_decoration(self, value): + app = self._app() + with pytest.raises(ValueError): + app.warmup(value) # type: ignore[arg-type] + + def test_warmup_type_accepts_string_form(self): + assert WarmupType("memory") is WarmupType.MEMORY + assert WarmupType("disk") is WarmupType.DISK + assert WarmupType.MEMORY == "memory" + app = self._app() + app.warmup("memory")(lambda: None) + app.warmup("disk")(lambda: None) + assert set(app._hooks["warmup"].handlers) == {WarmupType.MEMORY, WarmupType.DISK} + + def test_warmup_type_and_hook_config_exported(self): + import bedrock_agentcore.runtime + + assert bedrock_agentcore.runtime.WarmupType is WarmupType + assert bedrock_agentcore.runtime.HookConfig is HookConfig + + # --- warmup_hook constructor argument --- + + def test_custom_hook_path(self): + app = self._app("/prepare") + calls = [] + + @app.warmup(WarmupType.MEMORY) + def memory(): + calls.append("memory") + + client = TestClient(app) + response = self._post(client, "memory", path="/prepare") + assert response.status_code == 200 + assert response.json()["result"] == "completed" + assert self._post(client, "memory", path="/warmup").status_code in (404, 405) + assert calls == ["memory"] + + def test_post_ping_hook_path_keeps_get_ping(self): + """POST /ping doesn't clash with GET /ping; both must keep working.""" + client = TestClient(self._app("/ping")) + assert self._post(client, "memory", path="/ping").json()["result"] == "skipped" + assert client.get("/ping").json()["status"] == "Healthy" + + def test_post_ws_hook_path_allowed(self): + """The WebSocket route has no HTTP methods, so POST /ws doesn't clash.""" + client = TestClient(self._app("/ws")) + assert self._post(client, "disk", path="/ws").json()["result"] == "skipped" + + def test_invocations_hook_path_conflicts(self): + with pytest.raises(ValueError, match="POST /invocations is already served"): + self._app("/invocations") + + def test_no_warmup_hook_adds_no_route_and_decorator_raises(self): + app = BedrockAgentCoreApp() + assert app.warmup_hook is None + assert self._post(TestClient(app), "memory").status_code in (404, 405) + with pytest.raises(ValueError, match=r"warmup_hook=HookConfig\(path=\.\.\.\)"): + app.warmup(WarmupType.MEMORY) + assert "warmup" not in app._hooks + + def test_existing_positional_args_unchanged(self): + app = BedrockAgentCoreApp(True, None, None) + assert app.debug is True + assert app.warmup_hook is None + + # --- HookConfig validation --- + + @pytest.mark.parametrize("path", ["/", "/warmup", "/a/b-c_d.e~f", "/" + "a" * 31, "/a.b", "/..a"]) + def test_hook_config_valid_paths(self, path): + assert HookConfig(path=path).path == path + + @pytest.mark.parametrize( + ("path", "message"), + [ + (None, "must be a string"), + ("", "must be between 1 and 32"), + ("/" + "a" * 32, "must be between 1 and 32"), + ("warmup", "must start with '/'"), + ("/bad path", "must start with '/'"), + ("/a?b", "must start with '/'"), + ("/warmup/", "must be canonical"), + ("//warmup", "must be canonical"), + ("/a//b", "must be canonical"), + ("/./warmup", "must be canonical"), + ("/a/../b", "must be canonical"), + ("/a/.", "must be canonical"), + ("/a/..", "must be canonical"), + ], + ) + def test_hook_config_invalid_paths(self, path, message): + with pytest.raises(ValueError, match=f"^HookConfig.path {message}"): + HookConfig(path=path) # type: ignore[arg-type] + + def test_hook_config_has_no_port(self): + with pytest.raises(TypeError): + HookConfig(path="/warmup", port=9000) # type: ignore[call-arg] + + def test_hook_config_is_frozen(self): + config = HookConfig(path="/warmup") + with pytest.raises(dataclasses.FrozenInstanceError): + config.path = "/other" # type: ignore[misc] diff --git a/tests/bedrock_agentcore/test_init.py b/tests/bedrock_agentcore/test_init.py index f757719c..fca3772e 100644 --- a/tests/bedrock_agentcore/test_init.py +++ b/tests/bedrock_agentcore/test_init.py @@ -26,5 +26,7 @@ def test_all_exports(): "RequestContext", "BedrockAgentCoreContext", "PingStatus", + "WarmupType", + "HookConfig", ] assert sorted(bedrock_agentcore.__all__) == sorted(expected_all) diff --git a/tests_integ/runtime/test_warmup_agent.py b/tests_integ/runtime/test_warmup_agent.py new file mode 100644 index 00000000..7b5b373d --- /dev/null +++ b/tests_integ/runtime/test_warmup_agent.py @@ -0,0 +1,104 @@ +import logging +import textwrap +import threading +import time + +import requests + +from tests_integ.runtime.base_test import BaseSDKRuntimeTest, start_agent_server +from tests_integ.runtime.http_client import HttpClient + +logger = logging.getLogger("sdk-runtime-warmup-agent-test") + +# Own port so this test can run in parallel with the other runtime tests (pytest -n auto). +WARMUP_PORT = 8082 +WARMUP_HEADER = "X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type" +MEMORY_WARMUP_SECONDS = 2 + + +class TestSDKWarmupAgent(BaseSDKRuntimeTest): + def setup(self): + self.agent_module = "warmup_agent" + with open(self.agent_module + ".py", "w") as file: + content = textwrap.dedent(f""" + import time + + from bedrock_agentcore import BedrockAgentCoreApp, HookConfig, WarmupType + + app = BedrockAgentCoreApp(debug=True, warmup_hook=HookConfig(path="/warmup")) + WARMED = False + + @app.warmup(WarmupType.MEMORY) + def load_shared_state(): + global WARMED + time.sleep({MEMORY_WARMUP_SECONDS}) # blocking work; /ping must keep answering + WARMED = True + + # No disk handler: the disk call must still succeed. + + @app.entrypoint + def invoke(payload): + return {{"warmed": WARMED}} + + app.run(port={WARMUP_PORT}) + """).strip() + file.write(content) + + def run_test(self): + base_url = f"http://127.0.0.1:{WARMUP_PORT}" + with start_agent_server(self.agent_module, port=WARMUP_PORT): + client = HttpClient(base_url) + assert "Healthy" in client.ping() + + # Before warmup, the entrypoint sees no prepared state. + assert '"warmed": false' in client.invoke_endpoint("{}") + + # Poll /ping from another thread while the memory warmup blocks. + pings = [] + stop = threading.Event() + + def poll_ping(): + while not stop.is_set(): + start = time.monotonic() + response = requests.get(f"{base_url}/ping", timeout=1) + pings.append((start, response.status_code, response.json()["status"], time.monotonic() - start)) + time.sleep(0.1) + + poller = threading.Thread(target=poll_ping, daemon=True) + poller.start() + try: + memory_start = time.monotonic() + memory = requests.post(f"{base_url}/warmup", headers={WARMUP_HEADER: "memory"}, timeout=10) + memory_end = time.monotonic() + memory_duration = memory_end - memory_start + finally: + stop.set() + poller.join(timeout=5) + + logger.info("memory warmup: %s %s (%.2fs)", memory.status_code, memory.text, memory_duration) + assert memory.status_code == 200 + assert memory.json() == {"status": "ok", "type": "memory", "result": "completed"} + assert memory_duration >= MEMORY_WARMUP_SECONDS # responded only after the work was done + + # Only pings that started while the memory warmup was running prove /ping overlapped it. + during = [ping for ping in pings if memory_start <= ping[0] <= memory_end] + logger.info("pings during memory warmup: %s", during) + assert len(during) >= 5 + assert all(code == 200 and status == "Healthy" for _, code, status, _ in during) + assert max(duration for _, _, _, duration in during) < 0.5 + + disk = requests.post(f"{base_url}/warmup", headers={WARMUP_HEADER: "disk"}, timeout=10) + logger.info("disk warmup: %s %s", disk.status_code, disk.text) + assert disk.status_code == 200 + assert disk.json() == {"status": "ok", "type": "disk", "result": "skipped"} + + bad = requests.post(f"{base_url}/warmup", headers={WARMUP_HEADER: "cpu"}, timeout=10) + assert bad.status_code == 400 + + response = client.invoke_endpoint("{}") + logger.info(response) + assert '"warmed": true' in response + + +def test(tmp_path): + TestSDKWarmupAgent().run(tmp_path)