Repository navigation
Conversation
c7133dc to
4feb80f
Compare
…ooks Add BedrockAgentCoreApp.warmup(WarmupType.MEMORY | WarmupType.DISK) to register build warmup handlers, and a keyword-only warmup_hook=HookConfig(path=...) constructor argument that serves them at POST <path>. The path must equal hooksConfiguration.build.warmup.action.httpPost.path; the SDK has no default, and without warmup_hook no route is added and @app.warmup raises. HookConfig validates the path against the public API constraints (HttpPostLifecycleHookAction): 1-32 characters, an allowed character set, and canonical form. The hook is served on the app's serving port, so httpPost.port must be unset or equal to it. A warmup path that clashes with an existing route on a shared HTTP method (such as POST /invocations) raises at construction; POST /ping and POST /ws are allowed. The route reads X-Amzn-Bedrock-AgentCore-Runtime-Warmup-Type: a registered type runs its handler (200 completed; 500 on exception or when a sync handler returns an awaitable), a type with no handler returns 200 skipped, and a missing or invalid header returns 400. Sync handlers run in a worker thread and async handlers on a separate event loop, so /ping keeps answering; an asyncio.Lock keeps warmup handlers from running concurrently. The dispatch logic moves from _invoke_handler into a shared _dispatch_handler; _invoke_handler's behavior is unchanged. Export WarmupType and HookConfig from bedrock_agentcore and bedrock_agentcore.runtime. Closes aws#741
4feb80f to
639971d
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #746 +/- ##
=======================================
Coverage ? 89.80%
=======================================
Files ? 130
Lines ? 11574
Branches ? 1810
=======================================
Hits ? 10394
Misses ? 773
Partials ? 407
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
| if warmup_type in handlers: | ||
| raise ValueError(f"A {warmup_type.value} warmup handler is already registered") | ||
|
|
||
| def register(func: Callable) -> Callable: |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
| 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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Done in 40bbb06. An unknown, well-formed type returns 200 {"result": "skipped"}; only a missing or empty header returns 400.
| ValueError: If ``path`` doesn't meet the API constraints. | ||
| """ | ||
|
|
||
| path: str |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| 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 |
There was a problem hiding this comment.
Update this once port is supported: the hook is served on warmup_hook.port when set, otherwise on the serving port.
Closes #741
Description
Adds
@app.warmuptoBedrockAgentCoreAppfor the AgentCore Runtime build warmup hook.When a V2 runtime sets
hooksConfiguration.build.warmup, AgentCore Runtime sends twoPOSTrequests to the agent before the runtime isREADY:memory, thendisk. The call type comes in theX-Amzn-Bedrock-AgentCore-Runtime-Warmup-Typeheader. Today each agent has to add the route, parse the header, keep/pingresponsive and map errors to status codes itself. With this change:Behavior
200 {"status": "ok", "type": ..., "result": "completed"}200 {"status": "ok", "type": ..., "result": "skipped"}500 {"error": ..., "type": ...}, which fails the create or update500("declare it with async def")400warmup_hookValueErrorwhen the decorator is appliedPOST /invocations)ValueErrorwhen the app is constructedValueErrorwhenHookConfigis created/pingstays responsive. Sync handlers run in a worker thread and async handlers on a separate event loop, the same as@app.entrypoint.asyncio.Lock.Changes
runtime/models.pyWarmupType(MEMORY,DISK) andWARMUP_TYPE_HEADER.HookConfig(path): a frozen dataclass.pathis validated against the public API rules: 1–32 characters,A-Z a-z 0-9 . _ ~ / -, starts with/, canonical form. Each rule raises its own message.runtime/app.pyBedrockAgentCoreApp(..., *, warmup_hook=None): a new keyword-only argument.Noneadds no route.@app.warmup(type)registers a handler;_handle_warmupserves the route._add_routerejects a route whose(method, path)is already served._Hookholds each hook's config, handlers and lock._invoke_handlerinto_dispatch_handler, so warmup handlers can be called with no arguments._invoke_handlerbehaves as before.__init__.py,runtime/__init__.py: exportWarmupTypeandHookConfig.README.md: a "Build Warmup Hook" section.Design notes
httpPost.path, soHookConfigrequires it too. The path is then written out in both places, which makes a mismatch easy to spot, and apps that don't use the hook get no new route./ping. In the runtime'shooksConfiguration(CreateAgentRuntime/UpdateAgentRuntime), leavebuild.warmup.action.httpPost.portunset, so the platform uses the runtime's serving port, or set it to that same port. Serving a hook on a separate port is planned as a follow-up, which will add an optionalHookConfig.portwithout breaking existing code.POST /pingandPOST /wsare allowed;POST /invocationsisn't.uvicorn --workers N) only one of them is warmed. The README says so.Backward compatible
Yes.
warmup_hookis a new keyword-only argument that defaults toNone, so existing apps get no new route and no behavior change.Testing
Unit tests:
TestWarmup(57 cases) intests/bedrock_agentcore/runtime/test_app.py/pinganswersHealthyin < 0.5 s while a sync handler blocks for 1.5 s; three overlapping warmup calls run one at a time; each hook has its own lockwarmup_hook/warmupthen 404s;POST /pingandPOST /wsallowed;POST /invocationsraises; nowarmup_hookmeans no route and the decorator raises; existing positional arguments unchangedHookConfigportargument rejected; frozentests/bedrock_agentcore/test_init.py:WarmupTypeandHookConfigadded to the pinned__all__.Integration test:
tests_integ/runtime/test_warmup_agent.pyRuns a generated agent as a real local server. Its memory handler blocks for 2 s; it has no disk handler. The test asserts:
completedonly after the work is done;/pings that started during the warmup all returnedHealthyin < 0.5 s;skipped, and an invalid type returns400.Results (on
mainatc629a24)test_runtime_passthrough.pywasn't run; it needs AWS credentials.close(), dropping the conflict check, dropping the canonical-path check, and running sync handlers on the event loop each make a test fail.End-to-end on deployed V2 runtimes
Run on 2026-11-19 against the public
us-west-2endpoints, with the agent image built from this branch's wheel (639971d).Test agent: one image. Environment variables on the runtime pick which handlers are registered, which one raises, and how long the memory handler blocks. The memory handler sets an in-process flag, the disk handler reads a few-MB file, and the entrypoint returns both flags.
disk_warmedis alwaysfalse, as expected. Per the docs, only what the memory call loads is what each new instance starts with. The disk call warms file access, so its success shows in the build logs, not in the invoke response./warmupCreateAgentRuntimewithplatformVersion="V2",hooksConfiguration.build.warmup.action.httpPost.path=/warmup, and both handlers enabled.2. Poll
GetAgentRuntimeuntil the status isREADYorCREATE_FAILED.3. Read the build logs: the
[LIFECYCLE-HOOK …]lines and the SDK'sWarmup (…)lines.4.
InvokeAgentRuntimewith a new session.5. Delete the runtime.
READYwarmup hook (memory) succeeded,warmup hook (disk) succeeded; invoke{"memory_warmed": true, "disk_warmed": false}READYWarmup (disk): no handler registered, nothing to do;warmup hook (disk) succeeded; invoketrue/falseREADYWarmup (memory): no handler registered, nothing to do;warmup hook (disk) succeeded in 0.8 s; invokefalse/false/ping(the same path as the health check)httpPost.path=/pingandHookConfig(path="/ping"). The platform's ownGET /pinghealth checks run on the same path throughout.READYPOST /pingaccepted as the hook route; both calls succeeded while the health checks kept passing; invoketrue/falsehttpPost.path=/prepareandHookConfig(path="/warmup").CREATE_FAILED[ERROR] warmup hook (memory) failed: POST /prepare on port 8080 returned 404RuntimeError.CREATE_FAILEDWarmup (memory) failed(RuntimeError);[ERROR] warmup hook (memory) failed: POST /warmup on port 8080 returned 500RuntimeError.CREATE_FAILEDWarmup (disk) failed(RuntimeError);[ERROR] warmup hook (disk) failed: POST /warmup on port 8080 returned 500time.sleep(90), so the disk call gets the remaining budget.READYWarmup (memory) completed (90.000s);warmup hook (memory) succeeded in 90.0 s (30.0 s of the 120 s warmup budget left); no health-check failures; invoketrue/falsehooksConfigurationhooksConfiguration.READY[LIFECYCLE-HOOK]lines; invoke{"memory_warmed": false, "disk_warmed": false}UpdateAgentRuntimeREADY.2.
UpdateAgentRuntimewith the same artifact, role, network, platform version, environment andhooksConfiguration(an update replaces the whole hook config, so it must be included).3. Poll until
READYorUPDATE_FAILED.4. Read the build logs and invoke, as in M1.
5. Delete the runtime.
READY(version 2)warmup hook (memory) succeededandwarmup hook (disk) succeeded; invoketrue/falseExcerpts per case (from the build logs and invoke responses; IDs replaced with placeholders):
M1: memory and disk handlers, path
/warmupCreate request (parameters; the other cases differ only as noted in the Steps column):
M2: memory handler only
M3: disk handler only
M4: hook path
/ping(the same path as the health check)M5: path mismatch
M6a: memory handler raises
M6b: disk handler raises
M7: sync memory handler blocks for 90 s
M8: decorator in the code, no
hooksConfigurationM9: M1 through
UpdateAgentRuntime