agent-framework-core 1.16.0__tar.gz → 1.18.0__tar.gz

{agent_framework_core-1.16.0 → agent_framework_core-1.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-core
-Version: 1.16.0
+Version: 1.18.0
 Summary: Microsoft Agent Framework for building AI Agents with Python. This is the core package that has all the core abstractions and implementations.
 Author-email: Microsoft <af-support@microsoft.com>
 Requires-Python: >=3.10
@@ -21,7 +21,6 @@ Requires-Dist: typing-extensions>=4.15.0,<5
 Requires-Dist: pydantic>=2,<3
 Requires-Dist: python-dotenv>=1,<2
 Requires-Dist: opentelemetry-api>=1.39.0,<2
-Requires-Dist: agent-hooks-sdk>=0.1.0a4,<0.2 ; extra == "agent-hooks"
 Requires-Dist: mcp>=1.24.0,<2 ; extra == "all"
 Requires-Dist: agent-framework-a2a ; extra == "all"
 Requires-Dist: agent-framework-ag-ui ; extra == "all"
@@ -42,8 +41,7 @@ Requires-Dist: agent-framework-foundry-hosting ; extra == "all"
 Requires-Dist: agent-framework-foundry-local ; extra == "all"
 Requires-Dist: agent-framework-gemini ; extra == "all"
 Requires-Dist: agent-framework-github-copilot ; extra == "all" and ( python_version >= '3.11')
-Requires-Dist: agent-framework-hyperlight ; extra == "all" and ( ((sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64')) and python_version < '3.14')
-Requires-Dist: agent-framework-lab ; extra == "all"
+Requires-Dist: agent-framework-hyperlight ; extra == "all" and ( (sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64'))
 Requires-Dist: agent-framework-mem0 ; extra == "all"
 Requires-Dist: agent-framework-mistral ; extra == "all"
 Requires-Dist: agent-framework-monty ; extra == "all"
@@ -57,7 +55,6 @@ Project-URL: homepage, https://aka.ms/agent-framework
 Project-URL: issues, https://github.com/microsoft/agent-framework/issues
 Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
 Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
-Provides-Extra: agent-hooks
 Provides-Extra: all
 
 # Get Started with Microsoft Agent Framework

{agent_framework_core-1.16.0 → agent_framework_core-1.18.0}/agent_framework/__init__.py

@@ -284,6 +284,37 @@ _LAZY_MODULE_EXPORTS: Final[Mapping[str, tuple[str, ...]]] = {
         "validate_tool_mode",
         "validate_tools",
     ),
+    "._in_memory": (
+        "InMemoryCollection",
+        "InMemoryStore",
+    ),
+    "._vector_filters": (
+        "Filter",
+        "FilterGroup",
+        "FilterGroupOperator",
+        "FilterOperator",
+        "Param",
+    ),
+    "._vectors": (
+        "DISTANCE_FUNCTION_DIRECTION_HELPER",
+        "BaseVectorCollection",
+        "BaseVectorSearch",
+        "BaseVectorStore",
+        "DistanceFunction",
+        "FieldTypes",
+        "GenerateVectors",
+        "IndexKind",
+        "SearchResponse",
+        "SearchResults",
+        "SearchType",
+        "SupportsVectorSearch",
+        "SupportsVectorUpsert",
+        "VectorStoreCollectionDefinition",
+        "VectorStoreField",
+        "create_vector_search_tool",
+        "register_vectorstoremodel",
+        "vectorstoremodel",
+    ),
     "._workflows._agent": ("WorkflowAgent",),
     "._workflows._agent_executor": ("AgentExecutor", "AgentExecutorRequest", "AgentExecutorResponse"),
     "._workflows._agent_utils": ("resolve_agent_id",),
@@ -343,7 +374,7 @@ _LAZY_MODULE_EXPORTS: Final[Mapping[str, tuple[str, ...]]] = {
         "validate_workflow_graph",
     ),
     "._workflows._viz": ("WorkflowViz",),
-    "._workflows._workflow": ("Workflow", "WorkflowRunResult"),
+    "._workflows._workflow": ("Workflow", "WorkflowInvocationKwargs", "WorkflowRunResult"),
     "._workflows._workflow_builder": ("WorkflowBuilder",),
     "._workflows._workflow_context": ("WorkflowContext",),
     "._workflows._workflow_executor": (
@@ -371,6 +402,7 @@ __all__ = [
     "DEFAULT_MODE_SOURCE_ID",
     "DEFAULT_TODO_SOURCE_ID",
     "DEFAULT_TOOL_APPROVAL_SOURCE_ID",
+    "DISTANCE_FUNCTION_DIRECTION_HELPER",
     "EXCLUDED_KEY",
     "EXCLUDE_REASON_KEY",
     "GROUP_ANNOTATION_KEY",
@@ -412,6 +444,9 @@ __all__ = [
     "BaseAgent",
     "BaseChatClient",
     "BaseEmbeddingClient",
+    "BaseVectorCollection",
+    "BaseVectorSearch",
+    "BaseVectorStore",
     "CachingSkillsSource",
     "Case",
     "CharacterEstimatorTokenizer",
@@ -438,6 +473,7 @@ __all__ = [
     "DeduplicatingSkillsSource",
     "Default",
     "DelegatingSkillsSource",
+    "DistanceFunction",
     "Edge",
     "EdgeCondition",
     "EdgeDuplicationError",
@@ -456,6 +492,7 @@ __all__ = [
     "ExperimentalFeature",
     "FanInEdgeGroup",
     "FanOutEdgeGroup",
+    "FieldTypes",
     "FileAccessProvider",
     "FileCheckpointStorage",
     "FileHistoryProvider",
@@ -468,6 +505,10 @@ __all__ = [
     "FileSkillsSource",
     "FileStoreEntry",
     "FileSystemAgentFileStore",
+    "Filter",
+    "FilterGroup",
+    "FilterGroupOperator",
+    "FilterOperator",
     "FilteringSkillsSource",
     "FinalT",
     "FinishReason",
@@ -482,14 +523,18 @@ __all__ = [
     "FunctionalWorkflow",
     "FunctionalWorkflowAgent",
     "FunctionalWorkflowDefinition",
+    "GenerateVectors",
     "GeneratedEmbeddings",
     "GraphConnectivityError",
     "HistoryProvider",
     "InMemoryAgentFileStore",
     "InMemoryCheckpointStorage",
+    "InMemoryCollection",
     "InMemoryHistoryProvider",
     "InMemorySkillsSource",
+    "InMemoryStore",
     "InProcRunnerContext",
+    "IndexKind",
     "InlineSkill",
     "InlineSkillResource",
     "InlineSkillScript",
@@ -517,6 +562,7 @@ __all__ = [
     "MiddlewareTypes",
     "OuterFinalT",
     "OuterUpdateT",
+    "Param",
     "RawAgent",
     "ReleaseCandidateFeature",
     "ResponseStream",
@@ -527,6 +573,9 @@ __all__ = [
     "Runner",
     "RunnerContext",
     "SamplingApprovalCallback",
+    "SearchResponse",
+    "SearchResults",
+    "SearchType",
     "SecretString",
     "SelectiveToolCallCompactionStrategy",
     "ServiceSessionId",
@@ -555,6 +604,8 @@ __all__ = [
     "SupportsImageGenerationTool",
     "SupportsMCPTool",
     "SupportsShellTool",
+    "SupportsVectorSearch",
+    "SupportsVectorUpsert",
     "SupportsWebSearchTool",
     "SwitchCaseEdgeGroup",
     "SwitchCaseEdgeGroupCase",
@@ -580,6 +631,8 @@ __all__ = [
     "UsageDetails",
     "UserInputRequiredException",
     "ValidationTypeEnum",
+    "VectorStoreCollectionDefinition",
+    "VectorStoreField",
     "Workflow",
     "WorkflowAgent",
     "WorkflowBuilder",
@@ -593,6 +646,7 @@ __all__ = [
     "WorkflowEventType",
     "WorkflowException",
     "WorkflowExecutor",
+    "WorkflowInvocationKwargs",
     "WorkflowMessage",
     "WorkflowRunResult",
     "WorkflowRunState",
@@ -613,6 +667,7 @@ __all__ = [
     "create_always_approve_tool_with_arguments_response",
     "create_edge_runner",
     "create_harness_agent",
+    "create_vector_search_tool",
     "detect_media_type_from_base64",
     "enqueue_messages",
     "evaluate_agent",
@@ -636,6 +691,7 @@ __all__ = [
     "prepend_instructions_to_messages",
     "register_checkpoint_type",
     "register_state_type",
+    "register_vectorstoremodel",
     "resolve_agent_id",
     "response_handler",
     "set_agent_mode",
@@ -650,6 +706,7 @@ __all__ = [
     "validate_tool_mode",
     "validate_tools",
     "validate_workflow_graph",
+    "vectorstoremodel",
     "workflow",
 ]
 

{agent_framework_core-1.16.0 → agent_framework_core-1.18.0}/agent_framework/__init__.pyi

@@ -123,6 +123,7 @@ from ._harness._tool_approval import (
     create_always_approve_tool_response,
     create_always_approve_tool_with_arguments_response,
 )
+from ._in_memory import InMemoryCollection, InMemoryStore
 from ._mcp import (
     MCPStdioTool,
     MCPStreamableHTTPTool,
@@ -250,6 +251,27 @@ from ._types import (
     validate_tool_mode,
     validate_tools,
 )
+from ._vector_filters import Filter, FilterGroup, FilterGroupOperator, FilterOperator, Param
+from ._vectors import (
+    DISTANCE_FUNCTION_DIRECTION_HELPER,
+    BaseVectorCollection,
+    BaseVectorSearch,
+    BaseVectorStore,
+    DistanceFunction,
+    FieldTypes,
+    GenerateVectors,
+    IndexKind,
+    SearchResponse,
+    SearchResults,
+    SearchType,
+    SupportsVectorSearch,
+    SupportsVectorUpsert,
+    VectorStoreCollectionDefinition,
+    VectorStoreField,
+    create_vector_search_tool,
+    register_vectorstoremodel,
+    vectorstoremodel,
+)
 from ._workflows._agent import WorkflowAgent
 from ._workflows._agent_executor import AgentExecutor, AgentExecutorRequest, AgentExecutorResponse
 from ._workflows._agent_utils import resolve_agent_id
@@ -306,7 +328,7 @@ from ._workflows._validation import (
     validate_workflow_graph,
 )
 from ._workflows._viz import WorkflowViz
-from ._workflows._workflow import Workflow, WorkflowRunResult
+from ._workflows._workflow import Workflow, WorkflowInvocationKwargs, WorkflowRunResult
 from ._workflows._workflow_builder import WorkflowBuilder
 from ._workflows._workflow_context import WorkflowContext
 from ._workflows._workflow_executor import SubWorkflowRequestMessage, SubWorkflowResponseMessage, WorkflowExecutor
@@ -335,6 +357,7 @@ __all__ = [
     "DEFAULT_MODE_SOURCE_ID",
     "DEFAULT_TODO_SOURCE_ID",
     "DEFAULT_TOOL_APPROVAL_SOURCE_ID",
+    "DISTANCE_FUNCTION_DIRECTION_HELPER",
     "EXCLUDED_KEY",
     "EXCLUDE_REASON_KEY",
     "GROUP_ANNOTATION_KEY",
@@ -376,6 +399,9 @@ __all__ = [
     "BaseAgent",
     "BaseChatClient",
     "BaseEmbeddingClient",
+    "BaseVectorCollection",
+    "BaseVectorSearch",
+    "BaseVectorStore",
     "CachingSkillsSource",
     "Case",
     "CharacterEstimatorTokenizer",
@@ -402,6 +428,7 @@ __all__ = [
     "DeduplicatingSkillsSource",
     "Default",
     "DelegatingSkillsSource",
+    "DistanceFunction",
     "Edge",
     "EdgeCondition",
     "EdgeDuplicationError",
@@ -420,6 +447,7 @@ __all__ = [
     "ExperimentalFeature",
     "FanInEdgeGroup",
     "FanOutEdgeGroup",
+    "FieldTypes",
     "FileAccessProvider",
     "FileCheckpointStorage",
     "FileHistoryProvider",
@@ -432,6 +460,10 @@ __all__ = [
     "FileSkillsSource",
     "FileStoreEntry",
     "FileSystemAgentFileStore",
+    "Filter",
+    "FilterGroup",
+    "FilterGroupOperator",
+    "FilterOperator",
     "FilteringSkillsSource",
     "FinalT",
     "FinishReason",
@@ -446,14 +478,18 @@ __all__ = [
     "FunctionalWorkflow",
     "FunctionalWorkflowAgent",
     "FunctionalWorkflowDefinition",
+    "GenerateVectors",
     "GeneratedEmbeddings",
     "GraphConnectivityError",
     "HistoryProvider",
     "InMemoryAgentFileStore",
     "InMemoryCheckpointStorage",
+    "InMemoryCollection",
     "InMemoryHistoryProvider",
     "InMemorySkillsSource",
+    "InMemoryStore",
     "InProcRunnerContext",
+    "IndexKind",
     "InlineSkill",
     "InlineSkillResource",
     "InlineSkillScript",
@@ -481,6 +517,7 @@ __all__ = [
     "MiddlewareTypes",
     "OuterFinalT",
     "OuterUpdateT",
+    "Param",
     "RawAgent",
     "ReleaseCandidateFeature",
     "ResponseStream",
@@ -491,6 +528,9 @@ __all__ = [
     "Runner",
     "RunnerContext",
     "SamplingApprovalCallback",
+    "SearchResponse",
+    "SearchResults",
+    "SearchType",
     "SecretString",
     "SelectiveToolCallCompactionStrategy",
     "ServiceSessionId",
@@ -519,6 +559,8 @@ __all__ = [
     "SupportsImageGenerationTool",
     "SupportsMCPTool",
     "SupportsShellTool",
+    "SupportsVectorSearch",
+    "SupportsVectorUpsert",
     "SupportsWebSearchTool",
     "SwitchCaseEdgeGroup",
     "SwitchCaseEdgeGroupCase",
@@ -544,6 +586,8 @@ __all__ = [
     "UsageDetails",
     "UserInputRequiredException",
     "ValidationTypeEnum",
+    "VectorStoreCollectionDefinition",
+    "VectorStoreField",
     "Workflow",
     "WorkflowAgent",
     "WorkflowBuilder",
@@ -557,6 +601,7 @@ __all__ = [
     "WorkflowEventType",
     "WorkflowException",
     "WorkflowExecutor",
+    "WorkflowInvocationKwargs",
     "WorkflowMessage",
     "WorkflowRunResult",
     "WorkflowRunState",
@@ -577,6 +622,7 @@ __all__ = [
     "create_always_approve_tool_with_arguments_response",
     "create_edge_runner",
     "create_harness_agent",
+    "create_vector_search_tool",
     "detect_media_type_from_base64",
     "enqueue_messages",
     "evaluate_agent",
@@ -600,6 +646,7 @@ __all__ = [
     "prepend_instructions_to_messages",
     "register_checkpoint_type",
     "register_state_type",
+    "register_vectorstoremodel",
     "resolve_agent_id",
     "response_handler",
     "set_agent_mode",
@@ -614,5 +661,6 @@ __all__ = [
     "validate_tool_mode",
     "validate_tools",
     "validate_workflow_graph",
+    "vectorstoremodel",
     "workflow",
 ]

{agent_framework_core-1.16.0 → agent_framework_core-1.18.0}/agent_framework/_agent_hooks.py

@@ -93,7 +93,7 @@ per-run points and the host owns the session boundaries.
 
 The ``agent-hooks-sdk`` dependency is optional: importing this module (and the lazy root
 exports) works without it, and the factories raise a descriptive ``ModuleNotFoundError``
-when the SDK is missing. Install it via ``pip install agent-framework-core[agent-hooks]``.
+when the SDK is missing. Install it via ``pip install agent-hooks-sdk``.
 """
 
 from __future__ import annotations
@@ -162,7 +162,7 @@ _DEFAULT_TIMEOUT = 5.0
 
 _SDK_MISSING_MESSAGE = (
     "The agent-hooks middleware requires the optional `agent-hooks-sdk` package. "
-    "Please install `agent-framework-core[agent-hooks]` (or `agent-hooks-sdk`)."
+    "Please install it with `pip install agent-hooks-sdk`."
 )
 
 _TRIO_REQUIRED_MESSAGE = (
@@ -191,7 +191,7 @@ def _require_sdk() -> None:
     """Import the SDK surface this module uses at runtime, with a helpful install hint.
 
     Only a genuinely missing ``agent_hooks`` package is translated into the
-    install-the-extra message; anything else (a broken installation, an incompatible
+    SDK installation message; anything else (a broken installation, an incompatible
     SDK version missing symbols, a failing transitive import) propagates unchanged so
     real breakage is not masked as a missing extra.
     """
@@ -862,23 +862,99 @@ def _agent_updates_from_response(response: AgentResponse[Any]) -> list[AgentResp
     return updates
 
 
-def _tool_names(context: AgentContext) -> list[str]:
-    """Project the registered tool names for ``agent_startup`` (spec ``tools_registered``)."""
-    from ._tools import _get_tool_name, normalize_tools  # type: ignore[reportPrivateUsage]
+def _normalized_tools(tools: Any, *, point: str) -> list[Any]:
+    """Normalize a tools value for projection; empty (with a warning) when it cannot be.
+
+    Everything — including the emptiness check inside ``normalize_tools`` — runs under
+    the guard, so a tools container whose ``__bool__``/``__len__``/``__iter__`` raises
+    degrades to omitting the projection instead of aborting the emission mid-run.
+    """
+    from ._tools import normalize_tools
 
-    tools: Any = context.tools if context.tools is not None else getattr(context.agent, "tools", None)
-    if tools is None:
+    try:
+        return list(normalize_tools(tools))
+    except Exception:
+        logger.warning("agent-hooks could not normalize the tools for the %s projection.", point)
         return []
+
+
+def _projected_tool_name(item: Any) -> str:
+    """Project a tool's display name; hosted-tool mappings fall back to their ``type``."""
+    from ._tools import _get_tool_name  # type: ignore[reportPrivateUsage]
+
+    fallback = type(item).__name__
+    name = _get_tool_name(item)
+    if name:
+        return name
+    if isinstance(item, Mapping):
+        # Hosted-tool mappings carry top-level fields (no nested "function"), e.g.
+        # {"type": "web_search"} or {"type": "web_search_20250305", "name": "web_search"}.
+        mapping = cast("Mapping[str, Any]", item)
+        for key in ("name", "type"):
+            value = mapping.get(key)
+            if isinstance(value, str) and value:
+                return value
+    return fallback
+
+
+def _tool_description(item: Any) -> str | None:
+    """Extract a tool description from a tool object or dict tool definition."""
+    if isinstance(item, Mapping):
+        mapping = cast("Mapping[str, Any]", item)
+        function = mapping.get("function")
+        # Function-tool dicts nest the description; hosted-tool mappings keep it top-level.
+        description = (
+            cast("Mapping[str, Any]", function).get("description")
+            if isinstance(function, Mapping)
+            else mapping.get("description")
+        )
+        return description if isinstance(description, str) else None
+    description = getattr(item, "description", None)
+    return description if isinstance(description, str) else None
+
+
+def _tool_names(context: AgentContext) -> list[str]:
+    """Project the run-start tool names for ``agent_startup`` (spec ``tools_registered``).
+
+    The framework owns the run-start resolution — ``AgentContext._resolve_run_start_tools``
+    returns the agent-declared tools plus this invocation's run-level tools (the named
+    ``tools`` parameter takes precedence over a ``tools`` entry in the options mapping),
+    already normalized — so this helper is projection only. This is deliberately the
+    run-start snapshot: tools registered dynamically during the run (for example by
+    context providers during run preparation, or by MCP servers whose functions expand
+    at connect time) cannot be known at ``agent_startup`` time; they surface in each
+    ``pre_model_call`` emission's ``tools`` projection (the completed per-call set) and
+    are bracketed by ``pre_tool_call``/``post_tool_call`` like any other tool when
+    invoked. An unresolvable set degrades to a warning and an empty snapshot rather
+    than aborting the emission.
+    """
     try:
-        normalized = normalize_tools(tools)
+        resolved = context._resolve_run_start_tools()  # pyright: ignore[reportPrivateUsage]
     except Exception:
-        logger.warning("agent-hooks could not normalize the run's tools for the agent_startup projection.")
+        logger.warning("agent-hooks could not resolve the run-start tools for the agent_startup projection.")
         return []
-    names: list[str] = []
-    for item in normalized:
-        name = _get_tool_name(item)
-        names.append(name if name else type(item).__name__)
-    return names
+    return [_projected_tool_name(item) for item in resolved]
+
+
+def _pre_model_call_tools(options: Mapping[str, Any]) -> list[dict[str, Any]] | None:
+    """Project the per-call effective tool set for ``pre_model_call`` (spec ``tools``).
+
+    This is the completed set for this model call — the run-start tools plus anything
+    registered during the run (context-provider tools, connected MCP-server functions,
+    progressive tool exposure) — whereas ``agent_startup``'s ``tools_registered`` is the
+    run-start snapshot. Entries carry ``{"name", "description"?}`` (description omitted
+    when the tool has none). Returns ``None`` — the spec's optional field is omitted —
+    when the call offers no tools or the set cannot be projected, so an unprojectable
+    set is never misreported as "no tools".
+    """
+    projected: list[dict[str, Any]] = []
+    for item in _normalized_tools(options.get("tools"), point="pre_model_call"):
+        entry: dict[str, Any] = {"name": _projected_tool_name(item)}
+        description = _tool_description(item)
+        if description:
+            entry["description"] = description
+        projected.append(entry)
+    return projected or None
 
 
 def _is_host_error(record: InterceptionRecord) -> bool:
@@ -1269,7 +1345,7 @@ class _AgentHooksChatMiddleware(_AgentHooksMiddlewareBase, ChatMiddleware):
         model_id = str(options.get("model") or type(context.client).__name__)
         before = _ModelRequestCodec.to_wire(context.messages)
         outcome: EmitOutcome = await state.emitter.emit(
-            state.builder.pre_model_call(model_id=model_id, messages=before)
+            state.builder.pre_model_call(model_id=model_id, messages=before, tools=_pre_model_call_tools(options))
         )
         transformed_messages = _ModelRequestCodec.write_back(context.messages, before, outcome.target)
         if transformed_messages is not None:

{agent_framework_core-1.16.0 → agent_framework_core-1.18.0}/agent_framework/_agents.py

@@ -31,6 +31,8 @@ from ._middleware import (
     FunctionInvocationContext,
     MiddlewareTypes,
     _as_middleware_list,  # pyright: ignore[reportPrivateUsage]
+    _copy_middleware_sequence,  # pyright: ignore[reportPrivateUsage]
+    _select_run_level_tools,  # pyright: ignore[reportPrivateUsage]
     categorize_middleware,
 )
 from ._serialization import SerializationMixin
@@ -439,7 +441,7 @@ class BaseAgent(SerializationMixin):
         name: str | None = None,
         description: str | None = None,
         context_providers: Sequence[ContextProvider] | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         additional_properties: MutableMapping[str, Any] | None = None,
     ) -> None:
         """Initialize a BaseAgent instance.
@@ -450,10 +452,8 @@ class BaseAgent(SerializationMixin):
             name: The name of the agent, can be None.
             description: The description of the agent.
             context_providers: Context providers to include during agent invocation.
-            middleware: List of middleware, or a single middleware object (including a
-                ``MiddlewareBundle``) which is treated as a one-element list. The
-                constructor copies the sequence; assign to or mutate the
-                ``middleware`` attribute for post-construction changes.
+            middleware: List of middleware. The constructor copies the sequence; assign
+                to or mutate the ``middleware`` attribute for post-construction changes.
             additional_properties: Additional properties set on the agent.
         """
         if id is None:
@@ -462,11 +462,8 @@ class BaseAgent(SerializationMixin):
         self.name = name
         self.description = description
         self.context_providers: list[ContextProvider] = list(context_providers or [])
-        # Canonicalize storage: the bare-source rule (a single middleware object or a
-        # MiddlewareBundle is one element) is owned by _as_middleware_list; storing a
-        # normalized list keeps the declared attribute type honest.
         self.middleware: list[MiddlewareTypes] | None = (
-            _as_middleware_list(middleware) if middleware is not None else None
+            _copy_middleware_sequence(middleware) if middleware is not None else None
         )
         self.additional_properties: dict[str, Any] = cast(dict[str, Any], additional_properties or {})
 
@@ -819,7 +816,7 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: OptionsCoT | None = None,
         context_providers: Sequence[ContextProvider] | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         require_per_service_call_history_persistence: bool = False,
         compaction_strategy: CompactionStrategy | None = None,
         tokenizer: TokenizerProtocol | None = None,
@@ -838,8 +835,6 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
             description: A brief description of the agent's purpose.
             context_providers: Context providers to include during agent invocation.
             middleware: List of middleware to intercept agent and function invocations.
-                A single middleware object (including a ``MiddlewareBundle``) is
-                treated as a one-element list.
             require_per_service_call_history_persistence: When True (and a HistoryProvider is
                 present), the provider always persists history via per-service-call middleware,
                 regardless of whether the client stores history server-side. If the client does
@@ -1365,8 +1360,13 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
         opts = dict(options) if options else {}
         existing_additional_args: dict[str, Any] = opts.pop("additional_function_arguments", None) or {}
 
-        # Get tools from options or named parameter (named param takes precedence)
-        tools_ = tools if tools is not None else opts.pop("tools", None)
+        # Run-level tools: the named parameter takes precedence over an options entry
+        # (_select_run_level_tools is the framework's single statement of that rule,
+        # shared with the middleware layer's run-start resolution). The options entry
+        # is consumed either way, so a losing options["tools"] can never ride the
+        # remaining options into the request and silently override the resolved list.
+        tools_ = _select_run_level_tools(tools, opts)
+        opts.pop("tools", None)
 
         input_messages = normalize_messages(messages)
 
@@ -1808,7 +1808,7 @@ class Agent(
         *,
         stream: Literal[False] = ...,
         session: AgentSession | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         options: ChatOptions[ResponseModelBoundT],
         compaction_strategy: CompactionStrategy | None = None,
@@ -1824,7 +1824,7 @@ class Agent(
         *,
         stream: Literal[False] = ...,
         session: AgentSession | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         options: OptionsCoT | ChatOptions[None] | None = None,
         compaction_strategy: CompactionStrategy | None = None,
@@ -1840,7 +1840,7 @@ class Agent(
         *,
         stream: Literal[True],
         session: AgentSession | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         options: OptionsCoT | ChatOptions[Any] | None = None,
         compaction_strategy: CompactionStrategy | None = None,
@@ -1855,7 +1855,7 @@ class Agent(
         *,
         stream: bool = False,
         session: AgentSession | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         options: OptionsCoT | ChatOptions[Any] | None = None,
         compaction_strategy: CompactionStrategy | None = None,
@@ -1893,7 +1893,7 @@ class Agent(
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: OptionsCoT | None = None,
         context_providers: Sequence[ContextProvider] | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         require_per_service_call_history_persistence: bool = False,
         compaction_strategy: CompactionStrategy | None = None,
         tokenizer: TokenizerProtocol | None = None,

{agent_framework_core-1.16.0 → agent_framework_core-1.18.0}/agent_framework/_clients.py

@@ -96,6 +96,10 @@ class SupportsChatGetResponse(Protocol[OptionsContraT]):
         Protocols use structural subtyping (duck typing). Classes don't need
         to explicitly inherit from this protocol to be considered compatible.
 
+        Implementing this protocol does not by itself guarantee that an instance
+        can be reused across concurrent calls. Check the concrete client's
+        concurrency contract before sharing it.
+
     Examples:
         .. code-block:: python
 
@@ -578,7 +582,7 @@ class BaseChatClient(SerializationMixin, ABC, Generic[OptionsCoT]):
         tools: ToolTypes | Callable[..., Any] | Sequence[ToolTypes | Callable[..., Any]] | None = None,
         default_options: OptionsCoT | Mapping[str, Any] | None = None,
         context_providers: Sequence[Any] | None = None,
-        middleware: MiddlewareTypes | Sequence[MiddlewareTypes] | None = None,
+        middleware: Sequence[MiddlewareTypes] | None = None,
         require_per_service_call_history_persistence: bool = False,
         compaction_strategy: CompactionStrategy | None = None,
         tokenizer: TokenizerProtocol | None = None,