From c14c2651ecb75f88c69bdc9da0502b70dc0f9fa0 Mon Sep 17 00:00:00 2001 From: Pooya Paridel Date: Thu, 19 Nov 2026 23:19:34 +0000 Subject: [PATCH] feat(extras): add AgentcoreSession.invoke AgentcoreSession is now a class, as MicrovmSession is. The session handler receives it instead of the private handle. invoke runs one job in a child context named after the job. It builds the job scope with _AgentcoreScope.create, so it checks the name, the timeouts and the input size before any durable operation. It runs the job with _run_job and a stop that does nothing. So a failed job leaves the session running, and the session stops after its handler. A job error leaves the job's child context as ChildContextError. invoke and agentcore_session restore an AgentCore error to its own class, as microvm_session does. Other handler errors stay ChildContextError. agentcore_session is now exported from compute.agentcore. --- .../compute/agentcore/__init__.py | 2 + .../compute/agentcore/session.py | 106 +++++++--- .../agentcore/agentcore_session_test.py | 183 +++++++++++++++++- 3 files changed, 257 insertions(+), 34 deletions(-) diff --git a/packages/aws-durable-execution-sdk-python-extras/src/aws_durable_execution_sdk_python_extras/compute/agentcore/__init__.py b/packages/aws-durable-execution-sdk-python-extras/src/aws_durable_execution_sdk_python_extras/compute/agentcore/__init__.py index c0e49c335..59126860f 100644 --- a/packages/aws-durable-execution-sdk-python-extras/src/aws_durable_execution_sdk_python_extras/compute/agentcore/__init__.py +++ b/packages/aws-durable-execution-sdk-python-extras/src/aws_durable_execution_sdk_python_extras/compute/agentcore/__init__.py @@ -28,6 +28,7 @@ ) from aws_durable_execution_sdk_python_extras.compute.agentcore.session import ( AgentcoreSession, + agentcore_session, ) from aws_durable_execution_sdk_python_extras.compute.agentcore.subtypes import ( AgentcoreOperationSubType, @@ -52,5 +53,6 @@ "AgentcoreTimeoutError", "ComputeError", "agentcore", + "agentcore_session", "default_agentcore_retry_strategy", ] diff --git a/packages/aws-durable-execution-sdk-python-extras/src/aws_durable_execution_sdk_python_extras/compute/agentcore/session.py b/packages/aws-durable-execution-sdk-python-extras/src/aws_durable_execution_sdk_python_extras/compute/agentcore/session.py index 3349420a6..551390655 100644 --- a/packages/aws-durable-execution-sdk-python-extras/src/aws_durable_execution_sdk_python_extras/compute/agentcore/session.py +++ b/packages/aws-durable-execution-sdk-python-extras/src/aws_durable_execution_sdk_python_extras/compute/agentcore/session.py @@ -1,22 +1,30 @@ # SPDX-FileCopyrightText: 2026-present Amazon.com, Inc. or its affiliates. # # SPDX-License-Identifier: Apache-2.0 -"""The types of ``agentcore_session``: run several jobs in one AgentCore +"""The ``agentcore_session`` operation: run several jobs in one AgentCore Runtime session.""" from __future__ import annotations from collections.abc import Callable -from dataclasses import dataclass -from typing import TYPE_CHECKING, Any, Protocol, TypeVar +from typing import TYPE_CHECKING, Any, TypeVar from aws_durable_execution_sdk_python.exceptions import ( + ChildContextError, ExecutionError, InvocationError, ) +from aws_durable_execution_sdk_python_extras.compute.agentcore.config import ( + AgentcoreConfig, +) +from aws_durable_execution_sdk_python_extras.compute.agentcore.errors import ( + AgentcoreError, +) from aws_durable_execution_sdk_python_extras.compute.agentcore.operation import ( + _AgentcoreScope, _create_session_id, + _run_job, _stop_session, _validate_base, ) @@ -37,18 +45,23 @@ _T = TypeVar("_T") -class AgentcoreSession(Protocol): +class AgentcoreSession: """The handle that an :func:`agentcore_session` handler receives. - Each :meth:`invoke` creates its durable operations in the context that - the caller passes. Parallel :meth:`invoke` calls on one session run in - the same microVM, so the job handlers must allow it. + The handle holds no context of its own. Each :meth:`invoke` creates its + durable operations in the context that the caller passes. Parallel + :meth:`invoke` calls on one session run in the same microVM, so the job + handlers must allow it. """ + def __init__(self, config: AgentcoreSessionConfig, runtime_session_id: str) -> None: + self._config = config + self._runtime_session_id = runtime_session_id + @property def runtime_session_id(self) -> str: """The ``runtimeSessionId`` that every job of the session uses.""" - ... + return self._runtime_session_id def invoke( self, @@ -60,6 +73,11 @@ def invoke( ) -> Any: """Send one job to the session, and return the job's result. + Each call creates a child context named ``name`` in ``context``, with + a callback ``.callback`` and a request step ``.request``. + A failed job does not stop the session. The session stops when its + handler returns or raises. + Args: context: The context to create the job's durable operations in: the session's child context, or a context nested in it. @@ -73,12 +91,44 @@ def invoke( ``SendDurableExecutionCallbackSuccess``, parsed as JSON. Raises: + ValidationError: When ``name`` or ``options`` is not valid, or the + Region of the durable function cannot be determined. No + durable operation starts. + TypeError: When ``job_input`` is not JSON-serializable. No + durable operation starts. + ValueError: When the JSON of ``job_input`` is over + ``MAX_JOB_INPUT_BYTES`` UTF-8 bytes. No durable operation + starts. AgentcoreJobFailedError: When the agent reports a failure. AgentcoreTimeoutError: When the job or its heartbeat times out. AgentcoreDeliveryError: When the request fails after all retries, or the agent does not accept the job. """ - ... + config = self._config + scope = _AgentcoreScope.create( + context, + name, + job_input, + AgentcoreConfig( + agent_runtime_arn=config.agent_runtime_arn, + timeout=options.timeout, + qualifier=config.qualifier, + heartbeat_timeout=options.heartbeat_timeout, + retry_strategy=config.retry_strategy, + client=config.client, + ), + ) + session_id = self._runtime_session_id + + def run(job_context: DurableContext) -> Any: + # The session stops itself after its handler. So a failed job + # leaves the session running for the next job. + return _run_job(job_context, scope, session_id, job_input, lambda: None) + + try: + return context.run_in_child_context(run, name=name) + except ChildContextError as error: + raise AgentcoreError.from_child_context_error(name, error) from error def _validate_session_config(name: str, config: AgentcoreSessionConfig) -> int: @@ -98,24 +148,12 @@ def _validate_session_config(name: str, config: AgentcoreSessionConfig) -> int: return _validate_base(name, config.timeout) -@dataclass(frozen=True) -class _SessionHandle: - """The handle that an :func:`agentcore_session` handler receives, until - the session can send jobs. - - It has the ``runtime_session_id`` of :class:`AgentcoreSession`, and no - ``invoke`` yet. - """ - - runtime_session_id: str - - def agentcore_session( context: DurableContext, name: str, *, config: AgentcoreSessionConfig, - handler: Callable[[_SessionHandle, DurableContext], _T], + handler: Callable[[AgentcoreSession, DurableContext], _T], ) -> _T: """Run a handler in one AgentCore Runtime session, and return the handler's value. @@ -125,7 +163,9 @@ def agentcore_session( 1. ``.session`` generates the runtime session ID, and checkpoints it. So every retry and replay uses the same session. - 2. The handler runs with the session handle and the child context. + 2. The handler runs with an :class:`AgentcoreSession` and the child + context. Each :meth:`AgentcoreSession.invoke` sends one job to the + session and waits for its result. 3. ``.stop`` calls ``StopRuntimeSession`` after the handler returns or raises an error that ends the session. @@ -146,6 +186,11 @@ def agentcore_session( A stop for one of them would end a session that the replay still uses, or add an operation that the replay does not expect. + A failed :meth:`AgentcoreSession.invoke` raises inside the handler. The + handler can catch the error and send the next job to the same session. + An AgentCore error that leaves the handler reaches the caller with its + own class, as from :func:`agentcore`. + Args: context: The context to create the durable operations in. name: The child context name. It also prefixes the session's own @@ -160,7 +205,9 @@ def agentcore_session( Raises: ValidationError: When ``name`` or ``config`` is not valid. No durable operation starts. - ChildContextError: Any error that the handler raised. + AgentcoreError: An AgentCore error that the handler did not catch, + such as :class:`AgentcoreJobFailedError`, with its own class. + ChildContextError: Any other error that the handler raised. """ _validate_session_config(name, config) retry_strategy = config.retry_strategy or default_agentcore_retry_strategy @@ -172,7 +219,7 @@ def stop() -> None: _stop_session(child, name, config, retry_strategy, session_id) try: - result = handler(_SessionHandle(session_id), child) + result = handler(AgentcoreSession(config, session_id), child) except ExecutionError: raise except InvocationError as error: @@ -187,4 +234,11 @@ def stop() -> None: stop() return result - return context.run_in_child_context(run, name=name) + try: + return context.run_in_child_context(run, name=name) + except ChildContextError as error: + # The handler is caller code. So only an AgentCore error is restored + # to its class. Every other error keeps the SDK's ChildContextError. + if isinstance(error.__cause__, AgentcoreError): + raise AgentcoreError.from_child_context_error(name, error) from error + raise diff --git a/packages/aws-durable-execution-sdk-python-extras/tests/compute/agentcore/agentcore_session_test.py b/packages/aws-durable-execution-sdk-python-extras/tests/compute/agentcore/agentcore_session_test.py index 0c81f4648..fac2aca34 100644 --- a/packages/aws-durable-execution-sdk-python-extras/tests/compute/agentcore/agentcore_session_test.py +++ b/packages/aws-durable-execution-sdk-python-extras/tests/compute/agentcore/agentcore_session_test.py @@ -23,6 +23,7 @@ InvocationStatus, durable_execution, ) +from aws_durable_execution_sdk_python.lambda_service import ErrorObject from aws_durable_execution_sdk_python.retries import RetryDecision from aws_durable_execution_sdk_python.serdes import SerDes from aws_durable_execution_sdk_python_testing.runner import ( @@ -32,19 +33,22 @@ from botocore.exceptions import ClientError from aws_durable_execution_sdk_python_extras.compute.agentcore import ( + MAX_JOB_INPUT_BYTES, + AgentcoreError, + AgentcoreInvokeOptions, + AgentcoreSession, AgentcoreSessionConfig, + agentcore_session, ) from aws_durable_execution_sdk_python_extras.compute.agentcore.session import ( - _SessionHandle, _validate_session_config, - agentcore_session, ) WAIT = 30 ARN = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/reviewer-abc123" -Body = Callable[[_SessionHandle, DurableContext], Any] +Body = Callable[[AgentcoreSession, DurableContext], Any] def session_config(client: Any, **fields: Any) -> AgentcoreSessionConfig: @@ -120,7 +124,7 @@ def test_returns_the_handlers_value_and_stops_the_session( def test_stops_the_session_after_a_handler_error(fake_agentcore_client: Any) -> None: client = fake_agentcore_client() - def body(session: _SessionHandle, ctx: DurableContext) -> Any: + def body(session: AgentcoreSession, ctx: DurableContext) -> Any: msg = "no diff" raise LookupError(msg) @@ -183,7 +187,7 @@ def test_stops_the_session_only_after_a_wait_in_the_handler_ends( # would end the session that the replay still uses. client = fake_agentcore_client() - def body(session: _SessionHandle, ctx: DurableContext) -> Any: + def body(session: AgentcoreSession, ctx: DurableContext) -> Any: return ctx.create_callback(name="approval").result() runner = DurableFunctionTestRunner( @@ -210,7 +214,7 @@ def test_does_not_stop_the_session_for_an_execution_error( # recorded for it would change that history. client = fake_agentcore_client() - def body(session: _SessionHandle, ctx: DurableContext) -> Any: + def body(session: AgentcoreSession, ctx: DurableContext) -> Any: msg = "history does not match" raise NonDeterministicExecutionError(msg) @@ -253,7 +257,7 @@ def fetch(_: object) -> int: order.append("fetch") return 1 - def body(session: _SessionHandle, ctx: DurableContext) -> Any: + def body(session: AgentcoreSession, ctx: DurableContext) -> Any: return ctx.step(fetch, name="fetch", config=StepConfig(serdes=serdes)) result = run(session_handler(session_config(client), body)) @@ -274,7 +278,7 @@ class Fatal(InvocationError): def is_retryable(self) -> bool: return False - def body(session: _SessionHandle, ctx: DurableContext) -> Any: + def body(session: AgentcoreSession, ctx: DurableContext) -> Any: msg = "checkpoint rejected" raise Fatal(msg) @@ -360,3 +364,166 @@ def test_rejects_a_timeout_under_1_second() -> None: ValidationError, match='AgentCore "review": timeout must be at least 1 second' ): _validate_session_config("review", config) + + +OPTIONS = AgentcoreInvokeOptions(timeout=Duration.from_minutes(5)) +DENIED: Any = {"Error": {"Code": "AccessDeniedException", "Message": "denied"}} + + +def run_jobs( + handler: Callable[..., Any], complete: dict[str, bytes | ErrorObject] +) -> DurableFunctionTestResult: + """Run ``handler``, and complete each named callback in order.""" + runner = DurableFunctionTestRunner(handler=handler, poll_interval=0.05) + try: + arn = runner.run_async(input="{}", execution_timeout=WAIT) + for name, answer in complete.items(): + callback_id = runner.wait_for_callback(arn, name=name, timeout=WAIT) + if isinstance(answer, ErrorObject): + runner.send_callback_failure(callback_id, answer) + else: + runner.send_callback_success(callback_id, answer) + return runner.wait_for_result(arn, timeout=WAIT) + finally: + runner.close() + + +def payload(request: dict[str, Any]) -> Any: + return json.loads(request["payload"]) + + +FAILED = ErrorObject( + message="3 tests failed", type="RuntimeError", data=None, stack_trace=None +) + + +def test_two_jobs_use_the_same_session_and_their_own_callbacks( + fake_agentcore_client: Any, +) -> None: + client = fake_agentcore_client() + + def body(session: AgentcoreSession, ctx: DurableContext) -> Any: + build = session.invoke(ctx, "build", job_input={"step": 1}, options=OPTIONS) + return session.invoke(ctx, "test", job_input=build, options=OPTIONS) + + result = run_jobs( + session_handler(session_config(client), body), + {"build.callback": b'{"built": true}', "test.callback": b'"passed"'}, + ) + + assert outcome(result) == {"result": "passed"} + build, test = client.requests("invoke_agent_runtime") + [stop] = client.requests("stop_runtime_session") + assert build["runtimeSessionId"] == stop["runtimeSessionId"] + assert test["runtimeSessionId"] == stop["runtimeSessionId"] + assert payload(build)["input"] == {"step": 1} + assert payload(test)["input"] == {"built": True} + assert payload(build)["callbackId"] != payload(test)["callbackId"] + assert operation_names(result) == ["review.session", "build", "test", "review.stop"] + job = result.get_context("review").get_context("build") + assert [child.name for child in job.child_operations] == [ + "build.callback", + "build.request", + ] + + +@pytest.mark.parametrize( + ("fields", "invokes", "complete", "expected"), + [ + ({}, [], {"build.callback": FAILED}, "AgentcoreJobFailedError"), + ( + {"timeout": Duration.from_seconds(2)}, + [], + {}, + "AgentcoreTimeoutError", + ), + ({}, [ClientError(DENIED, "InvokeAgentRuntime")], {}, "AgentcoreDeliveryError"), + ], +) +def test_a_job_error_reaches_the_handler_with_its_agentcore_class( + fake_agentcore_client: Any, + fields: dict[str, Any], + invokes: list[Any], + complete: dict[str, Any], + expected: str, +) -> None: + client = fake_agentcore_client(invokes=invokes) + options = AgentcoreInvokeOptions(**{"timeout": OPTIONS.timeout, **fields}) + + def body(session: AgentcoreSession, ctx: DurableContext) -> Any: + try: + return session.invoke(ctx, "build", job_input={}, options=options) + except AgentcoreError as error: + return type(error).__name__ + + result = run_jobs(session_handler(session_config(client), body), complete) + + assert outcome(result) == {"result": expected} + + +def test_a_job_error_that_leaves_the_handler_keeps_its_class( + fake_agentcore_client: Any, +) -> None: + client = fake_agentcore_client() + config = session_config(client) + + def body(session: AgentcoreSession, ctx: DurableContext) -> Any: + return session.invoke(ctx, "build", job_input={}, options=OPTIONS) + + @durable_execution + def handler(event: Any, context: DurableContext) -> Any: + try: + agentcore_session(context, "review", config=config, handler=body) + except AgentcoreError as error: + return {"error": type(error).__name__, "message": error.message} + return None + + result = run_jobs(handler, {"build.callback": FAILED}) + + assert outcome(result) == { + "error": "AgentcoreJobFailedError", + "message": 'AgentCore "build": the job failed (RuntimeError): 3 tests failed', + } + assert len(client.requests("stop_runtime_session")) == 1 + + +def test_a_failed_job_does_not_stop_the_session(fake_agentcore_client: Any) -> None: + client = fake_agentcore_client(invokes=[ClientError(DENIED, "InvokeAgentRuntime")]) + + def body(session: AgentcoreSession, ctx: DurableContext) -> Any: + try: + session.invoke(ctx, "build", job_input={}, options=OPTIONS) + except AgentcoreError: + pass + return session.invoke(ctx, "retry", job_input={}, options=OPTIONS) + + result = run_jobs( + session_handler(session_config(client), body), {"retry.callback": b"1"} + ) + + assert outcome(result) == {"result": 1} + assert [call for call, _ in client.calls] == [ + "invoke_agent_runtime", + "invoke_agent_runtime", + "stop_runtime_session", + ] + + +def test_checks_the_job_input_size_before_any_job_operation( + fake_agentcore_client: Any, +) -> None: + client = fake_agentcore_client() + + def body(session: AgentcoreSession, ctx: DurableContext) -> Any: + job_input = "x" * MAX_JOB_INPUT_BYTES + try: + session.invoke(ctx, "build", job_input=job_input, options=OPTIONS) + except ValueError as error: + return str(error) + return None + + result = run_jobs(session_handler(session_config(client), body), {}) + + assert "the job input is" in outcome(result)["result"] + assert operation_names(result) == ["review.session", "review.stop"] + assert client.requests("invoke_agent_runtime") == []