Merge branch 'strands-agents:main' into feature/vincilb/config-loader

Author: vawsgit

pyproject.toml

@@ -70,6 +70,8 @@ docs = [
 ]
 litellm = [
     "litellm>=1.73.1,<2.0.0",
+    # https://github.com/BerriAI/litellm/issues/13711
+    "openai<1.100.0",
 ]
 llamaapi = [
     "llama-api-client>=0.1.0,<1.0.0",
@@ -93,7 +95,9 @@ writer = [
 sagemaker = [
     "boto3>=1.26.0,<2.0.0",
     "botocore>=1.29.0,<2.0.0",
-    "boto3-stubs[sagemaker-runtime]>=1.26.0,<2.0.0"
+    "boto3-stubs[sagemaker-runtime]>=1.26.0,<2.0.0",
+    # uses OpenAI as part of the implementation
+    "openai>=1.68.0,<2.0.0",
 ]
 
 a2a = [
@@ -105,50 +109,7 @@ a2a = [
     "starlette>=0.46.2,<1.0.0",
 ]
 all = [
-    # anthropic
-    "anthropic>=0.21.0,<1.0.0",
-
-    # dev
-    "commitizen>=4.4.0,<5.0.0",
-    "hatch>=1.0.0,<2.0.0",
-    "moto>=5.1.0,<6.0.0",
-    "mypy>=1.15.0,<2.0.0",
-    "pre-commit>=3.2.0,<4.2.0",
-    "pytest>=8.0.0,<9.0.0",
-    "pytest-asyncio>=0.26.0,<0.27.0",
-    "pytest-cov>=4.1.0,<5.0.0",
-    "pytest-xdist>=3.0.0,<4.0.0",
-    "ruff>=0.4.4,<0.5.0",
-
-    # docs
-    "sphinx>=5.0.0,<6.0.0",
-    "sphinx-rtd-theme>=1.0.0,<2.0.0",
-    "sphinx-autodoc-typehints>=1.12.0,<2.0.0",
-
-    # litellm
-    "litellm>=1.72.6,<1.73.0",
-
-    # llama
-    "llama-api-client>=0.1.0,<1.0.0",
-
-    # mistral
-    "mistralai>=1.8.2",
-
-    # ollama
-    "ollama>=0.4.8,<1.0.0",
-
-    # openai
-    "openai>=1.68.0,<2.0.0",
-
-    # otel
-    "opentelemetry-exporter-otlp-proto-http>=1.30.0,<2.0.0",
-
-    # a2a
-    "a2a-sdk[sql]>=0.3.0,<0.4.0",
-    "uvicorn>=0.34.2,<1.0.0",
-    "httpx>=0.28.1,<1.0.0",
-    "fastapi>=0.115.12,<1.0.0",
-    "starlette>=0.46.2,<1.0.0",
+    "strands-agents[a2a,anthropic,dev,docs,litellm,llamaapi,mistral,ollama,openai,otel]",
 ]
 
 [tool.hatch.version]
@@ -160,7 +121,7 @@ features = ["anthropic", "litellm", "llamaapi", "ollama", "openai", "otel", "mis
 dependencies = [
   "mypy>=1.15.0,<2.0.0",
   "ruff>=0.11.6,<0.12.0",
-  "strands-agents @ {root:uri}"
+  "strands-agents @ {root:uri}",
 ]
 
 [tool.hatch.envs.hatch-static-analysis.scripts]

src/strands/event_loop/streaming.py

@@ -40,10 +40,12 @@ def remove_blank_messages_content_text(messages: Messages) -> Messages:
         # only modify assistant messages
         if "role" in message and message["role"] != "assistant":
             continue
-
         if "content" in message:
             content = message["content"]
             has_tool_use = any("toolUse" in item for item in content)
+            if len(content) == 0:
+                content.append({"text": "[blank text]"})
+                continue
 
             if has_tool_use:
                 # Remove blank 'text' items for assistant messages
@@ -194,16 +196,18 @@ def handle_content_block_stop(state: dict[str, Any]) -> dict[str, Any]:
         state["text"] = ""
 
     elif reasoning_text:
-        content.append(
-            {
-                "reasoningContent": {
-                    "reasoningText": {
-                        "text": state["reasoningText"],
-                        "signature": state["signature"],
-                    }
+        content_block: ContentBlock = {
+            "reasoningContent": {
+                "reasoningText": {
+                    "text": state["reasoningText"],
                 }
             }
-        )
+        }
+
+        if "signature" in state:
+            content_block["reasoningContent"]["reasoningText"]["signature"] = state["signature"]
+
+        content.append(content_block)
         state["reasoningText"] = ""
 
     return state
@@ -263,7 +267,6 @@ async def process_stream(chunks: AsyncIterable[StreamEvent]) -> AsyncGenerator[d
         "text": "",
         "current_tool_use": {},
         "reasoningText": "",
-        "signature": "",
     }
     state["content"] = state["message"]["content"]
 
@@ -272,7 +275,6 @@ async def process_stream(chunks: AsyncIterable[StreamEvent]) -> AsyncGenerator[d
 
     async for chunk in chunks:
         yield {"callback": {"event": chunk}}
-
         if "messageStart" in chunk:
             state["message"] = handle_message_start(chunk["messageStart"], state["message"])
         elif "contentBlockStart" in chunk:
@@ -312,7 +314,6 @@ async def stream_messages(
     logger.debug("model=<%s> | streaming messages", model)
 
     messages = remove_blank_messages_content_text(messages)
-
     chunks = model.stream(messages, tool_specs if tool_specs else None, system_prompt)
 
     async for event in process_stream(chunks):

src/strands/telemetry/metrics.py

@@ -11,7 +11,7 @@
 
 from ..telemetry import metrics_constants as constants
 from ..types.content import Message
-from ..types.streaming import Metrics, Usage
+from ..types.event_loop import Metrics, Usage
 from ..types.tools import ToolUse
 
 logger = logging.getLogger(__name__)
@@ -264,6 +264,21 @@ def update_usage(self, usage: Usage) -> None:
         self.accumulated_usage["outputTokens"] += usage["outputTokens"]
         self.accumulated_usage["totalTokens"] += usage["totalTokens"]
 
+        # Handle optional cached token metrics
+        if "cacheReadInputTokens" in usage:
+            cache_read_tokens = usage["cacheReadInputTokens"]
+            self._metrics_client.event_loop_cache_read_input_tokens.record(cache_read_tokens)
+            self.accumulated_usage["cacheReadInputTokens"] = (
+                self.accumulated_usage.get("cacheReadInputTokens", 0) + cache_read_tokens
+            )
+
+        if "cacheWriteInputTokens" in usage:
+            cache_write_tokens = usage["cacheWriteInputTokens"]
+            self._metrics_client.event_loop_cache_write_input_tokens.record(cache_write_tokens)
+            self.accumulated_usage["cacheWriteInputTokens"] = (
+                self.accumulated_usage.get("cacheWriteInputTokens", 0) + cache_write_tokens
+            )
+
     def update_metrics(self, metrics: Metrics) -> None:
         """Update the accumulated performance metrics with new metrics data.
 
@@ -325,11 +340,21 @@ def _metrics_summary_to_lines(event_loop_metrics: EventLoopMetrics, allowed_name
         f"├─ Cycles: total={summary['total_cycles']}, avg_time={summary['average_cycle_time']:.3f}s, "
         f"total_time={summary['total_duration']:.3f}s"
     )
-    yield (
-        f"├─ Tokens: in={summary['accumulated_usage']['inputTokens']}, "
-        f"out={summary['accumulated_usage']['outputTokens']}, "
-        f"total={summary['accumulated_usage']['totalTokens']}"
-    )
+
+    # Build token display with optional cached tokens
+    token_parts = [
+        f"in={summary['accumulated_usage']['inputTokens']}",
+        f"out={summary['accumulated_usage']['outputTokens']}",
+        f"total={summary['accumulated_usage']['totalTokens']}",
+    ]
+
+    # Add cached token info if present
+    if summary["accumulated_usage"].get("cacheReadInputTokens"):
+        token_parts.append(f"cache_read_input_tokens={summary['accumulated_usage']['cacheReadInputTokens']}")
+    if summary["accumulated_usage"].get("cacheWriteInputTokens"):
+        token_parts.append(f"cache_write_input_tokens={summary['accumulated_usage']['cacheWriteInputTokens']}")
+
+    yield f"├─ Tokens: {', '.join(token_parts)}"
     yield f"├─ Bedrock Latency: {summary['accumulated_metrics']['latencyMs']}ms"
 
     yield "├─ Tool Usage:"
@@ -421,6 +446,8 @@ class MetricsClient:
     event_loop_latency: Histogram
     event_loop_input_tokens: Histogram
     event_loop_output_tokens: Histogram
+    event_loop_cache_read_input_tokens: Histogram
+    event_loop_cache_write_input_tokens: Histogram
 
     tool_call_count: Counter
     tool_success_count: Counter
@@ -474,3 +501,9 @@ def create_instruments(self) -> None:
         self.event_loop_output_tokens = self.meter.create_histogram(
             name=constants.STRANDS_EVENT_LOOP_OUTPUT_TOKENS, unit="token"
         )
+        self.event_loop_cache_read_input_tokens = self.meter.create_histogram(
+            name=constants.STRANDS_EVENT_LOOP_CACHE_READ_INPUT_TOKENS, unit="token"
+        )
+        self.event_loop_cache_write_input_tokens = self.meter.create_histogram(
+            name=constants.STRANDS_EVENT_LOOP_CACHE_WRITE_INPUT_TOKENS, unit="token"
+        )

src/strands/telemetry/metrics_constants.py

@@ -13,3 +13,5 @@
 STRANDS_EVENT_LOOP_CYCLE_DURATION = "strands.event_loop.cycle_duration"
 STRANDS_EVENT_LOOP_INPUT_TOKENS = "strands.event_loop.input.tokens"
 STRANDS_EVENT_LOOP_OUTPUT_TOKENS = "strands.event_loop.output.tokens"
+STRANDS_EVENT_LOOP_CACHE_READ_INPUT_TOKENS = "strands.event_loop.cache_read.input.tokens"
+STRANDS_EVENT_LOOP_CACHE_WRITE_INPUT_TOKENS = "strands.event_loop.cache_write.input.tokens"

src/strands/types/event_loop.py

@@ -2,21 +2,25 @@
 
 from typing import Literal
 
-from typing_extensions import TypedDict
+from typing_extensions import Required, TypedDict
 
 
-class Usage(TypedDict):
+class Usage(TypedDict, total=False):
     """Token usage information for model interactions.
 
     Attributes:
-        inputTokens: Number of tokens sent in the request to the model..
+        inputTokens: Number of tokens sent in the request to the model.
         outputTokens: Number of tokens that the model generated for the request.
         totalTokens: Total number of tokens (input + output).
+        cacheReadInputTokens: Number of tokens read from cache (optional).
+        cacheWriteInputTokens: Number of tokens written to cache (optional).
     """
 
-    inputTokens: int
-    outputTokens: int
-    totalTokens: int
+    inputTokens: Required[int]
+    outputTokens: Required[int]
+    totalTokens: Required[int]
+    cacheReadInputTokens: int
+    cacheWriteInputTokens: int
 
 
 class Metrics(TypedDict):

tests/strands/event_loop/test_streaming.py

@@ -26,13 +26,15 @@ def moto_autouse(moto_env, moto_mock_aws):
                 {"role": "assistant", "content": [{"text": "a"}, {"text": " \n"}, {"toolUse": {}}]},
                 {"role": "assistant", "content": [{"text": ""}, {"toolUse": {}}]},
                 {"role": "assistant", "content": [{"text": "a"}, {"text": " \n"}]},
+                {"role": "assistant", "content": []},
                 {"role": "assistant"},
                 {"role": "user", "content": [{"text": " \n"}]},
             ],
             [
                 {"role": "assistant", "content": [{"text": "a"}, {"toolUse": {}}]},
                 {"role": "assistant", "content": [{"toolUse": {}}]},
                 {"role": "assistant", "content": [{"text": "a"}, {"text": "[blank text]"}]},
+                {"role": "assistant", "content": [{"text": "[blank text]"}]},
                 {"role": "assistant"},
                 {"role": "user", "content": [{"text": " \n"}]},
             ],
@@ -216,6 +218,21 @@ def test_handle_content_block_delta(event: ContentBlockDeltaEvent, state, exp_up
                 "signature": "123",
             },
         ),
+        # Reasoning without signature
+        (
+            {
+                "content": [],
+                "current_tool_use": {},
+                "text": "",
+                "reasoningText": "test",
+            },
+            {
+                "content": [{"reasoningContent": {"reasoningText": {"text": "test"}}}],
+                "current_tool_use": {},
+                "text": "",
+                "reasoningText": "",
+            },
+        ),
         # Empty
         (
             {
@@ -260,6 +277,18 @@ def test_extract_usage_metrics():
     assert tru_usage == exp_usage and tru_metrics == exp_metrics
 
 
+def test_extract_usage_metrics_with_cache_tokens():
+    event = {
+        "usage": {"inputTokens": 0, "outputTokens": 0, "totalTokens": 0, "cacheReadInputTokens": 0},
+        "metrics": {"latencyMs": 0},
+    }
+
+    tru_usage, tru_metrics = strands.event_loop.streaming.extract_usage_metrics(event)
+    exp_usage, exp_metrics = event["usage"], event["metrics"]
+
+    assert tru_usage == exp_usage and tru_metrics == exp_metrics
+
+
 @pytest.mark.parametrize(
     ("response", "exp_events"),
     [

tests/strands/telemetry/test_metrics.py

@@ -90,6 +90,7 @@ def usage(request):
         "inputTokens": 1,
         "outputTokens": 2,
         "totalTokens": 3,
+        "cacheWriteInputTokens": 2,
     }
     if hasattr(request, "param"):
         params.update(request.param)
@@ -315,17 +316,14 @@ def test_event_loop_metrics_update_usage(usage, event_loop_metrics, mock_get_met
         event_loop_metrics.update_usage(usage)
 
     tru_usage = event_loop_metrics.accumulated_usage
-    exp_usage = Usage(
-        inputTokens=3,
-        outputTokens=6,
-        totalTokens=9,
-    )
+    exp_usage = Usage(inputTokens=3, outputTokens=6, totalTokens=9, cacheWriteInputTokens=6)
 
     assert tru_usage == exp_usage
     mock_get_meter_provider.return_value.get_meter.assert_called()
     metrics_client = event_loop_metrics._metrics_client
     metrics_client.event_loop_input_tokens.record.assert_called()
     metrics_client.event_loop_output_tokens.record.assert_called()
+    metrics_client.event_loop_cache_write_input_tokens.record.assert_called()
 
 
 def test_event_loop_metrics_update_metrics(metrics, event_loop_metrics, mock_get_meter_provider):