Merge branch 'main' into interface-kwargs-update

Author: Murat Kaan Meral

.gitignore

@@ -8,4 +8,5 @@ __pycache__*
 .ruff_cache
 *.bak
 .vscode
-dist
+dist
+repl_state

pyproject.toml

@@ -58,6 +58,8 @@ dev = [
     "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 = [
@@ -94,13 +96,59 @@ a2a = [
     "fastapi>=0.115.12",
     "starlette>=0.46.2",
 ]
+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.2.11",
+    "uvicorn>=0.34.2",
+    "httpx>=0.28.1",
+    "fastapi>=0.115.12",
+    "starlette>=0.46.2",
+]
 
 [tool.hatch.version]
 # Tells Hatch to use your version control system (git) to determine the version.
 source = "vcs"
 
 [tool.hatch.envs.hatch-static-analysis]
-features = ["anthropic", "litellm", "llamaapi", "ollama", "openai", "otel", "mistral", "writer"]
+features = ["anthropic", "litellm", "llamaapi", "ollama", "openai", "otel", "mistral", "writer", "a2a"]
 dependencies = [
   "mypy>=1.15.0,<2.0.0",
   "ruff>=0.11.6,<0.12.0",
@@ -116,15 +164,14 @@ format-fix = [
 ]
 lint-check = [
     "ruff check",
-    # excluding due to A2A and OTEL http exporter dependency conflict
-    "mypy -p src --exclude src/strands/multiagent"
+    "mypy -p src"
 ]
 lint-fix = [
     "ruff check --fix"
 ]
 
 [tool.hatch.envs.hatch-test]
-features = ["anthropic", "litellm", "llamaapi", "ollama", "openai", "otel", "mistral", "writer"]
+features = ["anthropic", "litellm", "llamaapi", "ollama", "openai", "otel", "mistral", "writer", "a2a"]
 extra-dependencies = [
     "moto>=5.1.0,<6.0.0",
     "pytest>=8.0.0,<9.0.0",
@@ -140,35 +187,17 @@ extra-args = [
 
 [tool.hatch.envs.dev]
 dev-mode = true
-features = ["dev", "docs", "anthropic", "litellm", "llamaapi", "ollama", "otel", "mistral", "writer"]
-
-[tool.hatch.envs.a2a]
-dev-mode = true
-features = ["dev", "docs", "anthropic", "litellm", "llamaapi", "ollama", "a2a"]
-
-[tool.hatch.envs.a2a.scripts]
-run = [
-    "pytest{env:HATCH_TEST_ARGS:} tests/strands/multiagent/a2a {args}"
-]
-run-cov = [
-    "pytest{env:HATCH_TEST_ARGS:} tests/strands/multiagent/a2a --cov --cov-config=pyproject.toml {args}"
-]
-lint-check = [
-    "ruff check",
-    "mypy -p src/strands/multiagent/a2a"
-]
+features = ["dev", "docs", "anthropic", "litellm", "llamaapi", "ollama", "otel", "mistral", "writer", "a2a"]
 
 [[tool.hatch.envs.hatch-test.matrix]]
 python = ["3.13", "3.12", "3.11", "3.10"]
 
 [tool.hatch.envs.hatch-test.scripts]
 run = [
-    # excluding due to A2A and OTEL http exporter dependency conflict
-    "pytest{env:HATCH_TEST_ARGS:} {args} --ignore=tests/strands/multiagent/a2a"
+    "pytest{env:HATCH_TEST_ARGS:} {args}"
 ]
 run-cov = [
-    # excluding due to A2A and OTEL http exporter dependency conflict
-    "pytest{env:HATCH_TEST_ARGS:} --cov --cov-config=pyproject.toml {args} --ignore=tests/strands/multiagent/a2a"
+    "pytest{env:HATCH_TEST_ARGS:} --cov --cov-config=pyproject.toml {args}"
 ]
 
 cov-combine = []
@@ -203,10 +232,6 @@ prepare = [
     "hatch run test-lint",
     "hatch test --all"
 ]
-test-a2a = [
-    # required to run manually due to A2A and OTEL http exporter dependency conflict
-    "hatch -e a2a run run {args}"
-]
 
 [tool.mypy]
 python_version = "3.10"

src/strands/agent/agent.py

@@ -15,27 +15,29 @@
 import random
 from concurrent.futures import ThreadPoolExecutor
 from typing import Any, AsyncGenerator, AsyncIterator, Callable, Mapping, Optional, Type, TypeVar, Union, cast
+from uuid import uuid4
 
 from opentelemetry import trace
 from pydantic import BaseModel
 
 from ..event_loop.event_loop import event_loop_cycle, run_tool
-from ..experimental.hooks import (
+from ..handlers.callback_handler import PrintingCallbackHandler, null_callback_handler
+from ..hooks import (
     AfterInvocationEvent,
     AgentInitializedEvent,
     BeforeInvocationEvent,
+    HookProvider,
     HookRegistry,
     MessageAddedEvent,
 )
-from ..handlers.callback_handler import PrintingCallbackHandler, null_callback_handler
 from ..models.bedrock import BedrockModel
+from ..models.model import Model
 from ..telemetry.metrics import EventLoopMetrics
 from ..telemetry.tracer import get_tracer
 from ..tools.registry import ToolRegistry
 from ..tools.watcher import ToolWatcher
 from ..types.content import ContentBlock, Message, Messages
 from ..types.exceptions import ContextWindowOverflowException
-from ..types.models import Model
 from ..types.tools import ToolResult, ToolUse
 from ..types.traces import AttributeValue
 from .agent_result import AgentResult
@@ -200,9 +202,11 @@ def __init__(
         load_tools_from_directory: bool = True,
         trace_attributes: Optional[Mapping[str, AttributeValue]] = None,
         *,
+        agent_id: Optional[str] = None,
         name: Optional[str] = None,
         description: Optional[str] = None,
         state: Optional[Union[AgentState, dict]] = None,
+        hooks: Optional[list[HookProvider]] = None,
     ):
         """Initialize the Agent with the specified configuration.
 
@@ -233,17 +237,24 @@ def __init__(
             load_tools_from_directory: Whether to load and automatically reload tools in the `./tools/` directory.
                 Defaults to True.
             trace_attributes: Custom trace attributes to apply to the agent's trace span.
+            agent_id: Optional ID for the agent, useful for multi-agent scenarios.
+                If None, a UUID is generated.
             name: name of the Agent
                 Defaults to None.
             description: description of what the Agent does
                 Defaults to None.
             state: stateful information for the agent. Can be either an AgentState object, or a json serializable dict.
                 Defaults to an empty AgentState object.
+            hooks: hooks to be added to the agent hook registry
+                Defaults to None.
         """
         self.model = BedrockModel() if not model else BedrockModel(model_id=model) if isinstance(model, str) else model
         self.messages = messages if messages is not None else []
 
         self.system_prompt = system_prompt
+        self.agent_id = agent_id or str(uuid4())
+        self.name = name or _DEFAULT_AGENT_NAME
+        self.description = description
 
         # If not provided, create a new PrintingCallbackHandler instance
         # If explicitly set to None, use null_callback_handler
@@ -299,12 +310,12 @@ def __init__(
             self.state = AgentState()
 
         self.tool_caller = Agent.ToolCaller(self)
-        self.name = name or _DEFAULT_AGENT_NAME
-        self.description = description
 
-        self._hooks = HookRegistry()
-        # Register built-in hook providers (like ConversationManager) here
-        self._hooks.invoke_callbacks(AgentInitializedEvent(agent=self))
+        self.hooks = HookRegistry()
+        if hooks:
+            for hook in hooks:
+                self.hooks.add_hook(hook)
+        self.hooks.invoke_callbacks(AgentInitializedEvent(agent=self))
 
     @property
     def tool(self) -> ToolCaller:
@@ -425,7 +436,7 @@ async def structured_output_async(
         Raises:
             ValueError: If no conversation history or prompt is provided.
         """
-        self._hooks.invoke_callbacks(BeforeInvocationEvent(agent=self))
+        self.hooks.invoke_callbacks(BeforeInvocationEvent(agent=self))
 
         try:
             if not self.messages and not prompt:
@@ -444,7 +455,7 @@ async def structured_output_async(
             return event["output"]
 
         finally:
-            self._hooks.invoke_callbacks(AfterInvocationEvent(agent=self))
+            self.hooks.invoke_callbacks(AfterInvocationEvent(agent=self))
 
     async def stream_async(self, prompt: Union[str, list[ContentBlock]], **kwargs: Any) -> AsyncIterator[Any]:
         """Process a natural language prompt and yield events as an async iterator.
@@ -512,7 +523,7 @@ async def _run_loop(
         Yields:
             Events from the event loop cycle.
         """
-        self._hooks.invoke_callbacks(BeforeInvocationEvent(agent=self))
+        self.hooks.invoke_callbacks(BeforeInvocationEvent(agent=self))
 
         try:
             yield {"callback": {"init_event_loop": True, **invocation_state}}
@@ -526,7 +537,7 @@ async def _run_loop(
 
         finally:
             self.conversation_manager.apply_management(self)
-            self._hooks.invoke_callbacks(AfterInvocationEvent(agent=self))
+            self.hooks.invoke_callbacks(AfterInvocationEvent(agent=self))
 
     async def _execute_event_loop_cycle(self, invocation_state: dict[str, Any]) -> AsyncGenerator[dict[str, Any], None]:
         """Execute the event loop cycle with retry logic for context window limits.
@@ -656,4 +667,4 @@ def _end_agent_trace_span(
     def _append_message(self, message: Message) -> None:
         """Appends a message to the agent's list of messages and invokes the callbacks for the MessageCreatedEvent."""
         self.messages.append(message)
-        self._hooks.invoke_callbacks(MessageAddedEvent(agent=self, message=message))
+        self.hooks.invoke_callbacks(MessageAddedEvent(agent=self, message=message))

src/strands/agent/conversation_manager/sliding_window_conversation_manager.py

@@ -76,7 +76,7 @@ def apply_management(self, agent: "Agent", **kwargs: Any) -> None:
 
         if len(messages) <= self.window_size:
             logger.debug(
-                "window_size=<%s>, message_count=<%s> | skipping context reduction", len(messages), self.window_size
+                "message_count=<%s>, window_size=<%s> | skipping context reduction", len(messages), self.window_size
             )
             return
         self.reduce_context(agent)

src/strands/event_loop/event_loop.py

@@ -18,8 +18,9 @@
     AfterToolInvocationEvent,
     BeforeModelInvocationEvent,
     BeforeToolInvocationEvent,
+)
+from ..hooks import (
     MessageAddedEvent,
-    get_registry,
 )
 from ..telemetry.metrics import Trace
 from ..telemetry.tracer import get_tracer
@@ -120,7 +121,7 @@ async def event_loop_cycle(agent: "Agent", invocation_state: dict[str, Any]) ->
 
         tool_specs = agent.tool_registry.get_all_tool_specs()
 
-        get_registry(agent).invoke_callbacks(
+        agent.hooks.invoke_callbacks(
             BeforeModelInvocationEvent(
                 agent=agent,
             )
@@ -139,7 +140,7 @@ async def event_loop_cycle(agent: "Agent", invocation_state: dict[str, Any]) ->
             stop_reason, message, usage, metrics = event["stop"]
             invocation_state.setdefault("request_state", {})
 
-            get_registry(agent).invoke_callbacks(
+            agent.hooks.invoke_callbacks(
                 AfterModelInvocationEvent(
                     agent=agent,
                     stop_response=AfterModelInvocationEvent.ModelStopResponse(
@@ -157,7 +158,7 @@ async def event_loop_cycle(agent: "Agent", invocation_state: dict[str, Any]) ->
             if model_invoke_span:
                 tracer.end_span_with_error(model_invoke_span, str(e), e)
 
-            get_registry(agent).invoke_callbacks(
+            agent.hooks.invoke_callbacks(
                 AfterModelInvocationEvent(
                     agent=agent,
                     exception=e,
@@ -191,7 +192,7 @@ async def event_loop_cycle(agent: "Agent", invocation_state: dict[str, Any]) ->
 
         # Add the response message to the conversation
         agent.messages.append(message)
-        get_registry(agent).invoke_callbacks(MessageAddedEvent(agent=agent, message=message))
+        agent.hooks.invoke_callbacks(MessageAddedEvent(agent=agent, message=message))
         yield {"callback": {"message": message}}
 
         # Update metrics
@@ -311,7 +312,7 @@ async def run_tool(agent: "Agent", tool_use: ToolUse, invocation_state: dict[str
         }
     )
 
-    before_event = get_registry(agent).invoke_callbacks(
+    before_event = agent.hooks.invoke_callbacks(
         BeforeToolInvocationEvent(
             agent=agent,
             selected_tool=tool_func,
@@ -346,7 +347,7 @@ async def run_tool(agent: "Agent", tool_use: ToolUse, invocation_state: dict[str
                 "content": [{"text": f"Unknown tool: {tool_name}"}],
             }
             # for every Before event call, we need to have an AfterEvent call
-            after_event = get_registry(agent).invoke_callbacks(
+            after_event = agent.hooks.invoke_callbacks(
                 AfterToolInvocationEvent(
                     agent=agent,
                     selected_tool=selected_tool,
@@ -363,7 +364,7 @@ async def run_tool(agent: "Agent", tool_use: ToolUse, invocation_state: dict[str
 
         result = event
 
-        after_event = get_registry(agent).invoke_callbacks(
+        after_event = agent.hooks.invoke_callbacks(
             AfterToolInvocationEvent(
                 agent=agent,
                 selected_tool=selected_tool,
@@ -381,7 +382,7 @@ async def run_tool(agent: "Agent", tool_use: ToolUse, invocation_state: dict[str
             "status": "error",
             "content": [{"text": f"Error: {str(e)}"}],
         }
-        after_event = get_registry(agent).invoke_callbacks(
+        after_event = agent.hooks.invoke_callbacks(
             AfterToolInvocationEvent(
                 agent=agent,
                 selected_tool=selected_tool,
@@ -458,7 +459,7 @@ def tool_handler(tool_use: ToolUse) -> ToolGenerator:
     }
 
     agent.messages.append(tool_result_message)
-    get_registry(agent).invoke_callbacks(MessageAddedEvent(agent=agent, message=tool_result_message))
+    agent.hooks.invoke_callbacks(MessageAddedEvent(agent=agent, message=tool_result_message))
     yield {"callback": {"message": tool_result_message}}
 
     if cycle_span:

src/strands/event_loop/streaming.py

@@ -4,8 +4,8 @@
 import logging
 from typing import Any, AsyncGenerator, AsyncIterable, Optional
 
+from ..models.model import Model
 from ..types.content import ContentBlock, Message, Messages
-from ..types.models import Model
 from ..types.streaming import (
     ContentBlockDeltaEvent,
     ContentBlockStart,