@aws/nx-plugin 1.0.0-rc.8 → 1.0.0-rc.80

package/src/utils/agent-connection/files/py-core-langchain/s3/s3_checkpoint_saver_langchain.py.template

@@ -0,0 +1,360 @@
+"""Async S3 checkpoint storage for LangGraph, backed by a plain (sync) boto3 client."""
+
+from __future__ import annotations
+
+import base64
+import builtins
+import json
+import logging
+from collections.abc import AsyncIterator, Iterator, Sequence
+from typing import Any, cast
+
+import boto3
+from botocore.exceptions import ClientError
+from langchain_core.runnables import RunnableConfig, run_in_executor
+from langgraph.checkpoint.base import (
+    WRITES_IDX_MAP,
+    BaseCheckpointSaver,
+    ChannelVersions,
+    Checkpoint,
+    CheckpointMetadata,
+    CheckpointTuple,
+    get_checkpoint_id,
+    get_checkpoint_metadata,
+)
+from langgraph.checkpoint.serde.base import SerializerProtocol
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize_checkpoint_ns(checkpoint_ns: str) -> str:
+    return checkpoint_ns if checkpoint_ns else "__default__"
+
+
+def _denormalize_checkpoint_ns(checkpoint_ns_safe: str) -> str:
+    return "" if checkpoint_ns_safe == "__default__" else checkpoint_ns_safe
+
+
+def _get_checkpoint_key(prefix: str, thread_id: str, checkpoint_ns: str, checkpoint_id: str) -> str:
+    checkpoint_ns_safe = _normalize_checkpoint_ns(checkpoint_ns)
+    return f"{prefix}checkpoints/{thread_id}/{checkpoint_ns_safe}/{checkpoint_id}.json"
+
+
+def _get_writes_prefix(prefix: str, thread_id: str, checkpoint_ns: str, checkpoint_id: str) -> str:
+    checkpoint_ns_safe = _normalize_checkpoint_ns(checkpoint_ns)
+    return f"{prefix}writes/{thread_id}/{checkpoint_ns_safe}/{checkpoint_id}/"
+
+
+def _get_write_key(prefix: str, thread_id: str, checkpoint_ns: str, checkpoint_id: str, task_id: str, idx: int) -> str:
+    return f"{_get_writes_prefix(prefix, thread_id, checkpoint_ns, checkpoint_id)}{task_id}_{idx}.json"
+
+
+def _serialize_checkpoint_data(checkpoint: Checkpoint, metadata: CheckpointMetadata, serde: SerializerProtocol) -> str:
+    checkpoint_type, serialized_checkpoint = serde.dumps_typed(checkpoint)
+    checkpoint_b64 = base64.b64encode(serialized_checkpoint).decode("utf-8")
+    metadata_type, serialized_metadata = serde.dumps_typed(metadata)
+    metadata_b64 = base64.b64encode(serialized_metadata).decode("utf-8")
+    return json.dumps(
+        {
+            "checkpoint_type": checkpoint_type,
+            "checkpoint": checkpoint_b64,
+            "metadata_type": metadata_type,
+            "metadata": metadata_b64,
+        },
+        indent=2,
+    )
+
+
+def _deserialize_checkpoint_data(data: str, serde: SerializerProtocol) -> tuple[Checkpoint, CheckpointMetadata]:
+    parsed = json.loads(data)
+    checkpoint = serde.loads_typed((parsed["checkpoint_type"], base64.b64decode(parsed["checkpoint"])))
+    metadata = cast(
+        CheckpointMetadata,
+        serde.loads_typed((parsed["metadata_type"], base64.b64decode(parsed["metadata"]))),
+    )
+    return checkpoint, metadata
+
+
+def _serialize_write_data(channel: str, value: Any, serde: SerializerProtocol) -> str:
+    type_, serialized_value = serde.dumps_typed(value)
+    value_b64 = base64.b64encode(serialized_value).decode("utf-8")
+    return json.dumps({"channel": channel, "value_type": type_, "value": value_b64}, indent=2)
+
+
+def _deserialize_write_data(data: str, serde: SerializerProtocol) -> tuple[str, Any]:
+    parsed = json.loads(data)
+    value = serde.loads_typed((parsed["value_type"], base64.b64decode(parsed["value"])))
+    return parsed["channel"], value
+
+
+class S3CheckpointSaver(BaseCheckpointSaver[str]):
+    """A checkpoint saver that stores LangGraph checkpoints in Amazon S3.
+
+    The sync methods (`get_tuple`, `list`, `put`, `put_writes`,
+    `delete_thread`) call boto3 directly. The async methods offload the same
+    sync methods to a thread via `run_in_executor` (mirroring
+    `langgraph_checkpoint_aws`'s `DynamoDBSaver`), since graphs compiled with
+    this checkpointer are invoked via `.ainvoke()`/`.astream()`.
+    """
+
+    def __init__(
+        self,
+        bucket_name: str,
+        *,
+        prefix: str = "checkpoints/",
+        s3_client: Any | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.bucket_name = bucket_name
+        self.prefix = prefix.rstrip("/") + "/" if prefix else ""
+        self.s3_client = s3_client or boto3.client("s3")
+
+    def _iter_objects(self, prefix: str) -> Iterator[dict[str, Any]]:
+        paginator = self.s3_client.get_paginator("list_objects_v2")
+        for page in paginator.paginate(Bucket=self.bucket_name, Prefix=prefix):
+            yield from page.get("Contents", [])
+
+    def get_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        thread_id = str(config["configurable"]["thread_id"])
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+
+        if checkpoint_id := get_checkpoint_id(config):
+            key = _get_checkpoint_key(self.prefix, thread_id, checkpoint_ns, checkpoint_id)
+            try:
+                response = self.s3_client.get_object(Bucket=self.bucket_name, Key=key)
+                checkpoint_data = response["Body"].read().decode("utf-8")
+                checkpoint, metadata = _deserialize_checkpoint_data(checkpoint_data, self.serde)
+
+                pending_writes = self._get_writes(thread_id, checkpoint_ns, checkpoint_id)
+
+                parent_config = None
+                if "parents" in metadata and checkpoint_ns in metadata["parents"]:
+                    parent_config = RunnableConfig(
+                        configurable={
+                            "thread_id": thread_id,
+                            "checkpoint_ns": checkpoint_ns,
+                            "checkpoint_id": metadata["parents"][checkpoint_ns],
+                        }
+                    )
+
+                return CheckpointTuple(
+                    config=config,
+                    checkpoint=checkpoint,
+                    metadata=metadata,
+                    parent_config=parent_config,
+                    pending_writes=pending_writes,
+                )
+            except ClientError as e:
+                if e.response["Error"]["Code"] == "NoSuchKey":
+                    return None
+                raise RuntimeError(f"Failed to get checkpoint: {e}") from e
+
+        # No checkpoint_id given - resolve the latest one the same way list() does.
+        return next(self.list(config, limit=1), None)
+
+    # `builtins.list` is used here (rather than the bare `list` type) because this class
+    # defines its own `list` method below, which shadows the builtin for annotations
+    # resolved within this class body.
+    def _get_writes(
+        self, thread_id: str, checkpoint_ns: str, checkpoint_id: str
+    ) -> builtins.list[tuple[str, str, Any]]:
+        writes_prefix = _get_writes_prefix(self.prefix, thread_id, checkpoint_ns, checkpoint_id)
+        writes = []
+        for obj in self._iter_objects(writes_prefix):
+            key = obj["Key"]
+            filename = key.split("/")[-1].replace(".json", "")
+            if "_" not in filename:
+                continue
+            task_id, idx_str = filename.rsplit("_", 1)
+            try:
+                idx = int(idx_str)
+            except ValueError:
+                continue
+            response = self.s3_client.get_object(Bucket=self.bucket_name, Key=key)
+            channel, value = _deserialize_write_data(response["Body"].read().decode("utf-8"), self.serde)
+            writes.append((task_id, channel, value, idx))
+
+        writes.sort(key=lambda x: (x[0], x[3]))
+        return [(task_id, channel, value) for task_id, channel, value, _ in writes]
+
+    def list(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> Iterator[CheckpointTuple]:
+        if config is None:
+            prefix = f"{self.prefix}checkpoints/"
+        else:
+            thread_id = str(config["configurable"]["thread_id"])
+            checkpoint_ns_safe = _normalize_checkpoint_ns(config["configurable"].get("checkpoint_ns", ""))
+            prefix = f"{self.prefix}checkpoints/{thread_id}/{checkpoint_ns_safe}/"
+
+        before_checkpoint_id = get_checkpoint_id(before) if before else None
+
+        try:
+            checkpoints = []
+            for obj in self._iter_objects(prefix):
+                key = obj["Key"]
+                if not key.endswith(".json"):
+                    continue
+                parts = key[len(self.prefix) :].split("/")
+                if len(parts) < 4 or parts[0] != "checkpoints":
+                    continue
+                key_checkpoint_id = parts[3].replace(".json", "")
+                if before_checkpoint_id and key_checkpoint_id >= before_checkpoint_id:
+                    continue
+                checkpoints.append((parts[1], _denormalize_checkpoint_ns(parts[2]), key_checkpoint_id))
+
+            checkpoints.sort(key=lambda x: x[2], reverse=True)
+            if limit:
+                checkpoints = checkpoints[:limit]
+
+            for thread_id, checkpoint_ns, checkpoint_id in checkpoints:
+                checkpoint_tuple = self.get_tuple(
+                    RunnableConfig(
+                        configurable={
+                            "thread_id": thread_id,
+                            "checkpoint_ns": checkpoint_ns,
+                            "checkpoint_id": checkpoint_id,
+                        }
+                    )
+                )
+                if checkpoint_tuple and (
+                    not filter or all(checkpoint_tuple.metadata.get(k) == v for k, v in filter.items())
+                ):
+                    yield checkpoint_tuple
+        except ClientError as e:
+            raise RuntimeError(f"Failed to list checkpoints: {e}") from e
+
+    def put(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        thread_id = str(config["configurable"]["thread_id"])
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        checkpoint_id = checkpoint["id"]
+
+        full_metadata = get_checkpoint_metadata(config, metadata)
+        checkpoint_data = _serialize_checkpoint_data(checkpoint, full_metadata, self.serde)
+        key = _get_checkpoint_key(self.prefix, thread_id, checkpoint_ns, checkpoint_id)
+
+        try:
+            self.s3_client.put_object(
+                Bucket=self.bucket_name,
+                Key=key,
+                Body=checkpoint_data,
+                ContentType="application/json",
+            )
+            return {
+                "configurable": {
+                    "thread_id": thread_id,
+                    "checkpoint_ns": checkpoint_ns,
+                    "checkpoint_id": checkpoint_id,
+                }
+            }
+        except ClientError as e:
+            raise RuntimeError(f"Failed to save checkpoint: {e}") from e
+
+    def put_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        thread_id = str(config["configurable"]["thread_id"])
+        checkpoint_ns = config["configurable"].get("checkpoint_ns", "")
+        checkpoint_id = str(config["configurable"]["checkpoint_id"])
+
+        try:
+            for idx, (channel, value) in enumerate(writes):
+                write_idx = WRITES_IDX_MAP.get(channel, idx)
+                write_data = _serialize_write_data(channel, value, self.serde)
+                key = _get_write_key(self.prefix, thread_id, checkpoint_ns, checkpoint_id, task_id, write_idx)
+                self.s3_client.put_object(
+                    Bucket=self.bucket_name,
+                    Key=key,
+                    Body=write_data,
+                    ContentType="application/json",
+                )
+        except ClientError as e:
+            raise RuntimeError(f"Failed to store writes: {e}") from e
+
+    def delete_thread(self, thread_id: str) -> None:
+        thread_id = str(thread_id)
+        prefixes = [
+            f"{self.prefix}checkpoints/{thread_id}/",
+            f"{self.prefix}writes/{thread_id}/",
+        ]
+        deleted_count = 0
+        try:
+            for prefix in prefixes:
+                objects_to_delete = []
+                for obj in self._iter_objects(prefix):
+                    objects_to_delete.append({"Key": obj["Key"]})
+                    if len(objects_to_delete) >= 1000:
+                        self.s3_client.delete_objects(
+                            Bucket=self.bucket_name, Delete={"Objects": objects_to_delete}
+                        )
+                        deleted_count += len(objects_to_delete)
+                        objects_to_delete = []
+                if objects_to_delete:
+                    self.s3_client.delete_objects(Bucket=self.bucket_name, Delete={"Objects": objects_to_delete})
+                    deleted_count += len(objects_to_delete)
+        except ClientError as e:
+            raise RuntimeError(f"Failed to delete thread data: {e}") from e
+
+        if deleted_count == 0:
+            logger.info("No checkpoints found for thread_id=%s", thread_id)
+        else:
+            logger.info("Deleted %d objects for thread_id=%s", deleted_count, thread_id)
+
+    async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
+        return await run_in_executor(None, self.get_tuple, config)
+
+    async def alist(
+        self,
+        config: RunnableConfig | None,
+        *,
+        filter: dict[str, Any] | None = None,
+        before: RunnableConfig | None = None,
+        limit: int | None = None,
+    ) -> AsyncIterator[CheckpointTuple]:
+        # ``list`` is backed by blocking boto3 calls, so it is driven from a
+        # background thread one item at a time to avoid blocking the event loop
+        # while still yielding lazily (no need to materialize all results).
+        iterator = self.list(config, filter=filter, before=before, limit=limit)
+
+        def next_item() -> CheckpointTuple | None:
+            return next(iterator, None)
+
+        while (item := await run_in_executor(None, next_item)) is not None:
+            yield item
+
+    async def aput(
+        self,
+        config: RunnableConfig,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata,
+        new_versions: ChannelVersions,
+    ) -> RunnableConfig:
+        return await run_in_executor(None, self.put, config, checkpoint, metadata, new_versions)
+
+    async def aput_writes(
+        self,
+        config: RunnableConfig,
+        writes: Sequence[tuple[str, Any]],
+        task_id: str,
+        task_path: str = "",
+    ) -> None:
+        await run_in_executor(None, self.put_writes, config, writes, task_id, task_path)
+
+    async def adelete_thread(self, thread_id: str) -> None:
+        await run_in_executor(None, self.delete_thread, thread_id)

package/src/utils/agent-connection/files/py-core-mcp/agentcore_mcp_transport.py.template

@@ -0,0 +1,34 @@
+from collections.abc import Callable
+
+from .agentcore_endpoints import mcp_url_from_arn, region_from_arn
+from .agentcore_transport import (
+    TransportFactory,
+    jwt_transport,
+    no_auth_transport,
+    sigv4_transport,
+)
+
+
+class AgentCoreMCPTransport:
+    """Factory for MCP transport factories that connect to an AgentCore runtime."""
+
+    @staticmethod
+    def with_iam_auth(agent_runtime_arn: str) -> TransportFactory:
+        """SigV4-authenticated transport for a Bedrock AgentCore runtime."""
+        return sigv4_transport(
+            mcp_url_from_arn(agent_runtime_arn), region_from_arn(agent_runtime_arn)
+        )
+
+    @staticmethod
+    def with_jwt_auth(
+        agent_runtime_arn: str, access_token_provider: Callable[[], str]
+    ) -> TransportFactory:
+        """Bearer-authenticated transport for a Bedrock AgentCore runtime."""
+        return jwt_transport(
+            mcp_url_from_arn(agent_runtime_arn), access_token_provider
+        )
+
+    @staticmethod
+    def without_auth(url: str) -> TransportFactory:
+        """Plain-HTTP transport — for local dev."""
+        return no_auth_transport(url)

package/src/utils/agent-connection/files/py-core-runtime-config/runtime_config.py.template

@@ -5,9 +5,12 @@ from aws_lambda_powertools.utilities import parameters
 from botocore.config import Config
 
 
-def _get_agentcore_runtime_config() -> dict[str, Any]:
+def get_agentcore_runtime_config() -> dict[str, Any]:
     """Read the runtime-config ``agentcore`` namespace from AppConfig.
 
+    Agent runtime entries include an ARN and optional session storage details.
+    Gateway entries map their construct names to URLs.
+
     ``RUNTIME_CONFIG_APP_ID`` is set on the AgentCore runtime by the generated
     CDK/Terraform construct for this project.
     """
@@ -23,20 +26,3 @@ def _get_agentcore_runtime_config() -> dict[str, Any]:
         config=Config(region_name=region) if region else None,
     )
     return cast(dict[str, Any], provider.get("agentcore", transform="json"))
-
-
-def get_connected_agent_runtime_arn(name: str) -> str:
-    """Resolve the AgentCore runtime ARN for a connected agent or MCP server
-    from this project's runtime configuration.
-
-    ``name`` must match the class name of the target construct
-    (e.g. ``MyAgent``, ``InventoryMcpServer``).
-    """
-    config = _get_agentcore_runtime_config()
-    agent_runtimes = config.get("agentRuntimes", {}) if config else {}
-    arn = agent_runtimes.get(name)
-    if not arn:
-        raise RuntimeError(
-            f"No connected agent runtime named '{name}' found in runtime configuration."
-        )
-    return arn

package/src/utils/agent-connection/files/py-core-runtime-config/session_context.py.template

@@ -1,4 +1,4 @@
-from collections.abc import Iterator
+from collections.abc import Generator
 from contextlib import contextmanager
 from contextvars import ContextVar
 
@@ -13,7 +13,7 @@ def get_current_session_id() -> str | None:
 
 
 @contextmanager
-def session_id_context(session_id: str) -> Iterator[None]:
+def session_id_context(session_id: str) -> Generator[None]:
     """Bind *session_id* as the current session for the scope of the block."""
     token = _session_id_var.set(session_id)
     try:

package/src/utils/agent-connection/files/py-core-shared/agentcore_transport.py.template

@@ -0,0 +1,40 @@
+from collections.abc import Callable
+from typing import Any
+
+import boto3
+
+from mcp.client.streamable_http import streamablehttp_client
+
+from .auth.session import jwt_auth, plain_auth, sigv4_auth
+
+# Agent frameworks wrap a transport *factory* — a no-arg callable returning a
+# streamable-HTTP transport context manager. Typed as ``Any`` so this layer
+# stays free of any framework-specific transport type.
+TransportFactory = Callable[[], Any]
+
+
+def _factory(url: str, auth) -> TransportFactory:
+    return lambda: streamablehttp_client(
+        url,
+        auth=auth,
+        timeout=120,
+        terminate_on_close=False,
+    )
+
+
+def sigv4_transport(url: str, region: str) -> TransportFactory:
+    """SigV4-signed transport factory for a resolved AgentCore endpoint."""
+    credentials = boto3.Session(region_name=region).get_credentials()
+    return _factory(url, sigv4_auth(credentials, region))
+
+
+def jwt_transport(
+    url: str, access_token_provider: Callable[[], str]
+) -> TransportFactory:
+    """Bearer-token transport factory for a resolved AgentCore endpoint."""
+    return _factory(url, jwt_auth(access_token_provider))
+
+
+def no_auth_transport(url: str) -> TransportFactory:
+    """Plain-HTTP transport factory — for local dev."""
+    return _factory(url, plain_auth())

package/src/utils/agent-connection/files/py-core-strands/a2a/agentcore_a2a_client_strands.py.template

@@ -0,0 +1,111 @@
+import asyncio
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+
+import httpx
+from a2a.client import ClientConfig
+from strands.agent.a2a_agent import A2AAgent
+from strands.agent.agent_result import AgentResult
+
+from .agentcore_a2a_client_config import AgentCoreA2aClientConfig
+
+
+def _run_sync(coro):
+    # The tool is invoked from sync agent code, which under uvicorn runs inside a
+    # live event loop where asyncio.run() would raise — fall back to a worker.
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+    with ThreadPoolExecutor(max_workers=1) as pool:
+        return pool.submit(asyncio.run, coro).result()
+
+
+class _A2AClient:
+    def __init__(
+        self,
+        url: str,
+        client_config: ClientConfig,
+        *,
+        name: str | None,
+        description: str | None,
+    ):
+        shared_client = client_config.httpx_client
+        if shared_client is None:
+            raise RuntimeError("A2A client config is missing an httpx client")
+        self._url = url
+        self._auth = shared_client.auth
+        self._timeout = shared_client.timeout
+        self._name = name
+        self._description = description
+
+    def __call__(self, prompt: str) -> AgentResult:
+        return _run_sync(self._invoke(prompt))
+
+    async def _invoke(self, prompt: str) -> AgentResult:
+        async with httpx.AsyncClient(
+            auth=self._auth, timeout=self._timeout
+        ) as httpx_client:
+            agent = A2AAgent(
+                endpoint=self._url,
+                name=self._name,
+                description=self._description,
+                client_config=ClientConfig(httpx_client=httpx_client, streaming=False),
+            )
+            return await agent.invoke_async(prompt)
+
+
+def _build(
+    config: tuple, *, name: str | None, description: str | None
+) -> _A2AClient:
+    url, client_config = config
+    return _A2AClient(url, client_config, name=name, description=description)
+
+
+class AgentCoreA2aClientStrands:
+    """Factory for Strands A2A clients that connect to an AgentCore runtime."""
+
+    @staticmethod
+    def with_iam_auth(
+        agent_runtime_arn: str,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> _A2AClient:
+        """SigV4-authenticated client for a Bedrock AgentCore runtime."""
+        return _build(
+            AgentCoreA2aClientConfig.with_iam_auth(agent_runtime_arn),
+            name=name,
+            description=description,
+        )
+
+    @staticmethod
+    def with_jwt_auth(
+        agent_runtime_arn: str,
+        access_token_provider: Callable[[], str],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> _A2AClient:
+        """Bearer-authenticated client for a Bedrock AgentCore runtime."""
+        return _build(
+            AgentCoreA2aClientConfig.with_jwt_auth(
+                agent_runtime_arn, access_token_provider
+            ),
+            name=name,
+            description=description,
+        )
+
+    @staticmethod
+    def without_auth(
+        url: str,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> _A2AClient:
+        """Plain-HTTP client — for local dev."""
+        return _build(
+            AgentCoreA2aClientConfig.without_auth(url),
+            name=name,
+            description=description,
+        )

package/src/utils/agent-connection/files/py-core-strands/base/model_errors_strands.py.template

@@ -0,0 +1,40 @@
+import logging
+
+from botocore.exceptions import ClientError, NoCredentialsError, PartialCredentialsError
+from strands.hooks import AfterModelCallEvent, HookRegistry
+
+logger = logging.getLogger(__name__)
+
+_NO_CREDENTIALS = (
+    "Unable to invoke the model: no AWS credentials found. Configure credentials "
+    "(e.g. run `aws configure`, set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / "
+    "AWS_SESSION_TOKEN, or assume a role) before running the agent."
+)
+_ACCESS_DENIED = (
+    "Unable to invoke the model: access denied. Grant your AWS principal permission "
+    "to call bedrock:InvokeModelWithResponseStream for your model."
+)
+
+
+def _is_access_denied(error: BaseException) -> bool:
+    return isinstance(error, ClientError) and error.response.get("Error", {}).get("Code") == "AccessDeniedException"
+
+
+class _LogModelErrors:
+    def register_hooks(self, registry: HookRegistry, **_kwargs) -> None:
+        registry.add_callback(AfterModelCallEvent, self._on_after_model_call)
+
+    @staticmethod
+    def _on_after_model_call(event: AfterModelCallEvent) -> None:
+        error = event.exception
+        if error is None:
+            return
+        if isinstance(error, (NoCredentialsError, PartialCredentialsError)):
+            logger.error(_NO_CREDENTIALS)
+        elif _is_access_denied(error):
+            logger.error(_ACCESS_DENIED)
+        else:
+            logger.error("Model invocation failed: %s", error)
+
+
+log_model_errors = _LogModelErrors()

package/src/utils/agent-connection/files/py-core-strands/base/tool_errors_strands.py.template

@@ -0,0 +1,24 @@
+import logging
+
+from strands.hooks import AfterToolCallEvent, HookRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class _LogToolErrors:
+    def register_hooks(self, registry: HookRegistry, **_kwargs) -> None:
+        registry.add_callback(AfterToolCallEvent, self._on_after_tool_call)
+
+    @staticmethod
+    def _on_after_tool_call(event: AfterToolCallEvent) -> None:
+        tool_name = event.tool_use.get("name", "<unknown>")
+        if event.exception is not None:
+            logger.error("Tool '%s' failed: %s", tool_name, event.exception)
+            return
+        if event.result.get("status") != "error":
+            return
+        message = " ".join(block["text"] for block in event.result.get("content", []) if "text" in block)
+        logger.error("Tool '%s' failed%s", tool_name, f": {message}" if message else "")
+
+
+log_tool_errors = _LogToolErrors()

package/src/utils/agent-connection/files/{py-core-runtime-config/with_session_id.py.template → py-core-strands/base/with_session_id_strands.py.template}

@@ -1,4 +1,4 @@
-from collections.abc import Callable, Iterator
+from collections.abc import Callable, Generator
 from contextlib import AbstractContextManager, ExitStack, contextmanager
 from typing import Any
 
@@ -11,7 +11,7 @@ def with_session_id(
     *,
     name: str,
     description: str,
-) -> Iterator[Any]:
+) -> Generator[Any]:
     """Wrap an agent factory so each session gets its own cached Agent."""
     stack = ExitStack()
     agents: dict[str, Any] = {}