agent-framework-core 1.24.0__tar.gz → 1.25.0__tar.gz

{agent_framework_core-1.24.0 → agent_framework_core-1.25.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: agent-framework-core
-Version: 1.24.0
+Version: 1.25.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
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Development Status :: 5 - Production/Stable
@@ -25,35 +25,35 @@ Requires-Dist: pyyaml>=6.0,<7.0
 Requires-Dist: regex>=2024.11.6
 Requires-Dist: mcp>=2.2.0,<3 ; extra == "all"
 Requires-Dist: tenacity>=9.1.4,<9.2.0 ; extra == "all"
-Requires-Dist: agent-framework-a2a>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-ag-ui>=1.7.1,<2 ; extra == "all"
-Requires-Dist: agent-framework-anthropic>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-azure-ai-search>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-azure-contentunderstanding>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-azure-cosmos>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-a2a>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-ag-ui>=1.8.0,<2 ; extra == "all"
+Requires-Dist: agent-framework-anthropic>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-azure-ai-search>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-azure-contentunderstanding>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-azure-cosmos>=1.0.0b261106,<2 ; extra == "all"
 Requires-Dist: agent-framework-azurefunctions>=1.0.0b260922,<2 ; extra == "all"
-Requires-Dist: agent-framework-bedrock>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-chatkit>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-claude>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-copilotstudio>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-declarative>=1.4.1,<2 ; extra == "all"
-Requires-Dist: agent-framework-devui>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-bedrock>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-chatkit>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-claude>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-copilotstudio>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-declarative>=1.5.0,<2 ; extra == "all"
+Requires-Dist: agent-framework-devui>=1.0.0b261106,<2 ; extra == "all"
 Requires-Dist: agent-framework-durabletask>=1.0.0b260922,<2 ; extra == "all"
-Requires-Dist: agent-framework-foundry>=1.16.0,<2 ; extra == "all"
-Requires-Dist: agent-framework-foundry-hosting>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-foundry-local>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-gemini>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-github-copilot>=2.1.1,<3 ; extra == "all" and ( python_version >= '3.11')
-Requires-Dist: agent-framework-hyperlight>=1.0.0b261030,<2 ; extra == "all" and ( (sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64'))
-Requires-Dist: agent-framework-mem0>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-mistral>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-monty>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-ollama>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-openai>=1.18.0,<2 ; extra == "all"
-Requires-Dist: agent-framework-orchestrations>=1.4.1,<2 ; extra == "all"
-Requires-Dist: agent-framework-purview>=1.0.0b261030,<2 ; extra == "all"
-Requires-Dist: agent-framework-redis>=1.0.0b261030,<2 ; extra == "all" and ( python_version < '3.15')
-Requires-Dist: agent-framework-tools>=1.0.0b261030,<2 ; extra == "all"
+Requires-Dist: agent-framework-foundry>=1.16.1,<2 ; extra == "all"
+Requires-Dist: agent-framework-foundry-hosting>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-foundry-local>=1.0.0b261106,<2 ; extra == "all" and ( python_version >= '3.11' and python_version < '3.15' and ((sys_platform == 'darwin' and platform_machine == 'arm64') or (sys_platform == 'linux' and (platform_machine == 'x86_64' or platform_machine == 'aarch64')) or (sys_platform == 'win32' and (platform_machine == 'AMD64' or platform_machine == 'ARM64' or platform_machine == 'x86_64' or platform_machine == 'aarch64'))))
+Requires-Dist: agent-framework-gemini>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-github-copilot>=2.1.2,<3 ; extra == "all"
+Requires-Dist: agent-framework-hyperlight>=1.0.0b261106,<2 ; extra == "all" and ( (sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64'))
+Requires-Dist: agent-framework-mem0>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-mistral>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-monty>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-ollama>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-openai>=1.18.1,<2 ; extra == "all"
+Requires-Dist: agent-framework-orchestrations>=1.4.2,<2 ; extra == "all"
+Requires-Dist: agent-framework-purview>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-redis>=1.0.0b261106,<2 ; extra == "all"
+Requires-Dist: agent-framework-tools>=1.0.0b261106,<2 ; extra == "all"
 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
@@ -88,12 +88,8 @@ Supported Platforms:
 - Python: 3.11–3.15
 - OS: Windows, macOS, Linux
 
-Python 3.10 is no longer supported because it has reached upstream end of life.
-Package metadata still permits Python 3.10 installation, but CI no longer runs
-unit or integration tests on it and compatibility is not guaranteed. Use
-Python 3.11–3.15 for supported environments, subject to
-[integration-specific limits](../../README.md#python-315-limitations). Raising
-the installation minimum will be handled separately.
+Python 3.11 or later is required. Supported environments are subject to
+[integration-specific limits](../../README.md#python-315-limitations).
 
 ## 1. Setup API Keys
 
@@ -261,6 +257,34 @@ cookie-bearing clients and MCP tool sessions to one authenticated principal; do
 share a user-specific cookie jar across users. Rejecting cookies does not partition
 MCP protocol sessions or other server-side state between principals.
 
+### MCP HTTP concurrency and timeouts
+
+`MCPStreamableHTTPTool` and `FoundryToolbox` attach a separate header snapshot to each
+outgoing HTTP request. Calls with identical effective static and dynamic headers can
+overlap on one MCP session. A different identity waits for active operations before
+reconnecting and refreshing discovery. Discovery, reset, close, and recovery are
+exclusive against active network attempts on framework-owned MCP connections, with
+or without a header provider. Same-identity Agent run preparation does not drain
+active calls. Direct prompt calls resolve current headers rather than reusing an
+inherited invocation snapshot; generated prompts resolve host runtime kwargs
+separately from model arguments. Calls still share server-side session state;
+applications must order state-dependent operations themselves.
+
+Resource reads wait for replacement initialization before requiring the connection.
+Catalog discovery restarts the complete snapshot once after a connection replacement,
+without reusing old pages or cursors. A second replacement fails explicitly.
+
+`request_timeout` bounds header admission and session reconciliation together, and
+connection recovery separately from the RPC timeout. These are separate budgets,
+not an end-to-end deadline. `None` disables these budgets. An admission timeout does
+not cancel another caller's active operation. Cleanup may continue after a timeout
+or cancellation so the lifecycle owner can finish releasing resources safely.
+Caller-owned MCP clients retain their own RPC timeout policy and are not recreated.
+
+Concurrent failures of the same connection share its replacement. Calling `close()`
+interrupts older recovery so it cannot reopen the connection or retry the failed
+operation after shutdown. A later explicit `connect()` remains supported.
+
 ## 5. Multi-Agent Orchestration
 
 Coordinate multiple agents to collaborate on complex tasks using orchestration patterns:

{agent_framework_core-1.24.0 → agent_framework_core-1.25.0}/README.md

@@ -25,12 +25,8 @@ Supported Platforms:
 - Python: 3.11–3.15
 - OS: Windows, macOS, Linux
 
-Python 3.10 is no longer supported because it has reached upstream end of life.
-Package metadata still permits Python 3.10 installation, but CI no longer runs
-unit or integration tests on it and compatibility is not guaranteed. Use
-Python 3.11–3.15 for supported environments, subject to
-[integration-specific limits](../../README.md#python-315-limitations). Raising
-the installation minimum will be handled separately.
+Python 3.11 or later is required. Supported environments are subject to
+[integration-specific limits](../../README.md#python-315-limitations).
 
 ## 1. Setup API Keys
 
@@ -198,6 +194,34 @@ cookie-bearing clients and MCP tool sessions to one authenticated principal; do
 share a user-specific cookie jar across users. Rejecting cookies does not partition
 MCP protocol sessions or other server-side state between principals.
 
+### MCP HTTP concurrency and timeouts
+
+`MCPStreamableHTTPTool` and `FoundryToolbox` attach a separate header snapshot to each
+outgoing HTTP request. Calls with identical effective static and dynamic headers can
+overlap on one MCP session. A different identity waits for active operations before
+reconnecting and refreshing discovery. Discovery, reset, close, and recovery are
+exclusive against active network attempts on framework-owned MCP connections, with
+or without a header provider. Same-identity Agent run preparation does not drain
+active calls. Direct prompt calls resolve current headers rather than reusing an
+inherited invocation snapshot; generated prompts resolve host runtime kwargs
+separately from model arguments. Calls still share server-side session state;
+applications must order state-dependent operations themselves.
+
+Resource reads wait for replacement initialization before requiring the connection.
+Catalog discovery restarts the complete snapshot once after a connection replacement,
+without reusing old pages or cursors. A second replacement fails explicitly.
+
+`request_timeout` bounds header admission and session reconciliation together, and
+connection recovery separately from the RPC timeout. These are separate budgets,
+not an end-to-end deadline. `None` disables these budgets. An admission timeout does
+not cancel another caller's active operation. Cleanup may continue after a timeout
+or cancellation so the lifecycle owner can finish releasing resources safely.
+Caller-owned MCP clients retain their own RPC timeout policy and are not recreated.
+
+Concurrent failures of the same connection share its replacement. Calling `close()`
+interrupts older recovery so it cannot reopen the connection or retry the failed
+operation after shutdown. A later explicit `connect()` remains supported.
+
 ## 5. Multi-Agent Orchestration
 
 Coordinate multiple agents to collaborate on complex tasks using orchestration patterns:

{agent_framework_core-1.24.0 → agent_framework_core-1.25.0}/agent_framework/_agents.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import logging
 import re
 import sys
-from collections.abc import Awaitable, Callable, Mapping, MutableMapping, Sequence
+from collections.abc import AsyncIterable, Awaitable, Callable, Mapping, MutableMapping, Sequence
 from contextlib import AbstractAsyncContextManager, AsyncExitStack
 from copy import deepcopy
 from functools import partial
@@ -18,6 +18,8 @@ from typing import (
     Generic,
     Literal,
     Protocol,
+    Self,
+    TypedDict,
     cast,
     overload,
     runtime_checkable,
@@ -51,6 +53,7 @@ from ._sessions import (
 )
 from ._telemetry import FeatureIndex, mark_feature_used
 from ._types import (
+    _EVALUATION_TOOLS_METADATA_KEY,  # pyright: ignore[reportPrivateUsage]
     AgentResponse,
     AgentResponseUpdate,
     AgentRunInputs,
@@ -60,6 +63,8 @@ from ._types import (
     ResponseStream,
     _append_instructions,  # pyright: ignore[reportPrivateUsage]
     _build_agent_response_from_chat_response,  # pyright: ignore[reportPrivateUsage]
+    _capture_evaluation_tools,  # pyright: ignore[reportPrivateUsage]
+    _copy_operation_state,  # pyright: ignore[reportPrivateUsage]
     map_chat_to_agent_update,
     normalize_messages,
 )
@@ -75,10 +80,6 @@ if sys.version_info >= (3, 13):
     from typing import TypeVar  # pragma: no cover
 else:
     from typing_extensions import TypeVar  # pragma: no cover
-if sys.version_info >= (3, 11):
-    from typing import Self, TypedDict  # pragma: no cover
-else:
-    from typing_extensions import Self, TypedDict  # pragma: no cover
 
 if TYPE_CHECKING:
     from collections.abc import Collection
@@ -275,6 +276,7 @@ class _RunContext(TypedDict):
     agent_name: str
     suppress_response_id: bool
     chat_options: MutableMapping[str, Any]
+    evaluation_tools: dict[str, dict[str, Any]]
     compaction_strategy: CompactionStrategy | None
     tokenizer: TokenizerProtocol | None
     client_kwargs: Mapping[str, Any]
@@ -396,7 +398,8 @@ class SupportsAgentRun(Protocol):
             messages: The message(s) to send to the agent.
 
         Keyword Args:
-            stream: Whether to stream the response. Defaults to False.
+            stream: Whether to stream the response. Defaults to False. Streams
+                may include response metadata updates without message contents.
             session: The conversation session associated with the message(s).
             function_invocation_kwargs: Keyword arguments forwarded to tool invocation.
             client_kwargs: Additional client-specific keyword arguments.
@@ -701,6 +704,9 @@ class BaseAgent(SerializationMixin):
             :attr:`FunctionInvocationContext.parent_service_session_state_keys` when
             the parent session is non-empty. Automatic function calling supplies it.
 
+            ``WorkflowAgent.as_tool()`` is not supported, because every caller of
+            the tool would share the state of one workflow.
+
         Examples:
             .. code-block:: python
 
@@ -882,6 +888,8 @@ class BaseAgent(SerializationMixin):
             func=_agent_wrapper,
             input_model=input_schema,
             approval_mode=approval_mode,
+            # Private link for hosts that must know which agent a tool delegates to. Serialization skips it.
+            _wrapped_agent=self,
         )
 
 
@@ -1406,6 +1414,7 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
             response_format=context["chat_options"].get("response_format"),
             suppress_response_id=context["suppress_response_id"],
         )
+        agent_response.additional_properties[_EVALUATION_TOOLS_METADATA_KEY] = context["evaluation_tools"]
         session_context = context["session_context"]
         session_context._response = agent_response  # type: ignore[assignment]
         await self._run_after_providers(session=session, context=session_context)
@@ -1442,6 +1451,7 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
             session_context = context["session_context"]
             if context["suppress_response_id"]:
                 response.response_id = None
+            response.additional_properties[_EVALUATION_TOOLS_METADATA_KEY] = context["evaluation_tools"]
             session_context._response = response  # type: ignore[assignment]
             # Result hooks run during finalization, outside the per-pull identity
             # scope registered below, so re-stamp this run's identity around its
@@ -1482,7 +1492,28 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
         # carries this run's identity; nested runs re-stamp their own within theirs.
         stream = stream.with_pull_context_manager(partial(_run_identity_scope, run_identity))
 
-        return stream.with_transform_hook(_propagate_conversation_id).with_result_hook(_post_hook)
+        stream = stream.with_transform_hook(_propagate_conversation_id).with_result_hook(_post_hook)
+
+        async def _with_evaluation_metadata() -> AsyncIterable[AgentResponseUpdate]:
+            async with stream:
+                async for update in stream:
+                    yield update
+                response = await stream.get_final_response()
+                metadata_update = AgentResponseUpdate(
+                    continuation_token=response.continuation_token,
+                    additional_properties={
+                        _EVALUATION_TOOLS_METADATA_KEY: deepcopy(
+                            response.additional_properties[_EVALUATION_TOOLS_METADATA_KEY]
+                        )
+                    },
+                )
+                _copy_operation_state(response, metadata_update)
+                yield metadata_update
+
+        async def _finalize_with_metadata(updates: Sequence[AgentResponseUpdate]) -> AgentResponse[Any]:
+            return await stream.get_final_response()
+
+        return ResponseStream(_with_evaluation_metadata(), finalizer=_finalize_with_metadata)
 
     def _finalize_response_updates(
         self,
@@ -1491,6 +1522,10 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
         response_format: Any | None = None,
     ) -> AgentResponse[Any]:
         """Finalize response updates into a single AgentResponse."""
+        if isinstance(self.client, BaseChatClient):
+            return self.client._finalize_agent_response_updates(  # pyright: ignore[reportPrivateUsage]
+                updates, response_format=response_format
+            )
         return AgentResponse.from_updates(
             updates,
             output_format_type=response_format,
@@ -1760,6 +1795,12 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
                 per_service_call_history_middleware,
             ]
 
+        evaluation_tools: dict[str, dict[str, Any]] = {}
+        if isinstance(self.client, BaseChatClient):
+            effective_client_kwargs["_evaluation_tool_capture"] = partial(_capture_evaluation_tools, evaluation_tools)
+        else:
+            _capture_evaluation_tools(evaluation_tools, co.get("tools"))
+
         return {
             "session": active_session,
             "session_context": session_context,
@@ -1768,6 +1809,7 @@ class RawAgent(BaseAgent, Generic[OptionsCoT]):
             "agent_name": agent_name,
             "suppress_response_id": bool(per_service_call_history_providers) and not service_stores_history,
             "chat_options": co,
+            "evaluation_tools": evaluation_tools,
             "compaction_strategy": compaction_strategy or self.compaction_strategy,
             "tokenizer": tokenizer or self.tokenizer,
             "client_kwargs": effective_client_kwargs,

{agent_framework_core-1.24.0 → agent_framework_core-1.25.0}/agent_framework/_clients.py

@@ -21,6 +21,7 @@ from typing import (
     Generic,
     Literal,
     Protocol,
+    Self,
     TypedDict,
     cast,
     overload,
@@ -30,6 +31,8 @@ from typing import (
 from ._docstrings import apply_layered_docstring
 from ._serialization import SerializationMixin
 from ._types import (
+    AgentResponse,
+    AgentResponseUpdate,
     ChatResponse,
     ChatResponseUpdate,
     EmbeddingGenerationOptions,
@@ -47,11 +50,6 @@ if sys.version_info >= (3, 13):
 else:
     from typing_extensions import TypeVar  # pragma: no cover
 
-if sys.version_info >= (3, 11):
-    from typing import Self  # pragma: no cover
-else:
-    from typing_extensions import Self  # pragma: no cover
-
 
 if TYPE_CHECKING:
     from pydantic import BaseModel
@@ -360,9 +358,15 @@ class BaseChatClient(SerializationMixin, ABC, Generic[OptionsCoT]):
         # Get the base dict from SerializationMixin
         result = super().to_dict(exclude=exclude, exclude_none=exclude_none)
 
-        # Extract additional_properties to root level
-        if self.additional_properties:
-            result.update(self.additional_properties)
+        # Extract additional_properties to root level respecting exclusions and exclude_none
+        if self.additional_properties and (exclude is None or "additional_properties" not in exclude):
+            exclude_set = exclude or set()
+            for key, value in self.additional_properties.items():
+                if key in exclude_set:
+                    continue
+                if exclude_none and value is None:
+                    continue
+                result[key] = value
 
         return result
 
@@ -391,6 +395,15 @@ class BaseChatClient(SerializationMixin, ABC, Generic[OptionsCoT]):
             output_format_type=response_format,
         )
 
+    def _finalize_agent_response_updates(
+        self,
+        updates: Sequence[AgentResponseUpdate],
+        *,
+        response_format: Any | None = None,
+    ) -> AgentResponse[Any]:
+        """Aggregate mapped agent updates without reapplying per-model-turn processing."""
+        return AgentResponse.from_updates(updates, output_format_type=response_format)
+
     def _build_response_stream(
         self,
         stream: AsyncIterable[ChatResponseUpdate] | Awaitable[AsyncIterable[ChatResponseUpdate]],
@@ -581,6 +594,11 @@ class BaseChatClient(SerializationMixin, ABC, Generic[OptionsCoT]):
             tokenizer=tokenizer,
         )
         merged_client_kwargs = dict(client_kwargs) if client_kwargs is not None else {}
+        evaluation_tool_capture = cast(
+            Callable[[Any], None] | None, merged_client_kwargs.pop("_evaluation_tool_capture", None)
+        )
+        if evaluation_tool_capture is not None:
+            evaluation_tool_capture((options or {}).get("tools"))
 
         if not compaction_overrides:
             return self._inner_get_response(

{agent_framework_core-1.24.0 → agent_framework_core-1.25.0}/agent_framework/_evaluation.py

@@ -56,7 +56,11 @@ from typing import (
 
 from ._feature_stage import ExperimentalFeature, experimental
 from ._tools import FunctionTool, normalize_tools
-from ._types import AgentResponse, Message
+from ._types import (
+    _EVALUATION_TOOLS_METADATA_KEY,  # pyright: ignore[reportPrivateUsage]
+    AgentResponse,
+    Message,
+)
 
 if TYPE_CHECKING:
     from ._agents import SupportsAgentRun
@@ -872,8 +876,44 @@ def _to_eval_item(
     all_msgs = list(input_msgs) + list(response.messages or [])
 
     typed_tools: list[FunctionTool] = []
-    if tools:
+    if tools is not None:
         typed_tools = [tool for tool in normalize_tools(tools) if isinstance(tool, FunctionTool)]
+    elif _EVALUATION_TOOLS_METADATA_KEY in response.additional_properties:
+        called_tools = {
+            content.name for message in all_msgs for content in message.contents if content.type == "function_call"
+        }
+        definitions = response.additional_properties[_EVALUATION_TOOLS_METADATA_KEY]
+        if not isinstance(definitions, dict):
+            raise ValueError("Invalid agent_framework.evaluation metadata: expected tool definitions keyed by name.")
+        for name, definition in cast(dict[str, Any], definitions).items():
+            if not isinstance(name, str) or not name or not isinstance(definition, dict):
+                raise ValueError("Invalid agent_framework.evaluation metadata: expected named tool definition objects.")
+            definition = cast(dict[str, Any], definition)
+            description = definition.get("description")
+            schema = definition.get("input_schema")
+            if not isinstance(description, str) or not isinstance(schema, dict):
+                raise ValueError(
+                    f"Invalid agent_framework.evaluation definition for {name!r}: "
+                    "expected a string description and an input_schema object."
+                )
+            schema_changed = definition.get("schema_changed", False)
+            if not isinstance(schema_changed, bool):
+                raise ValueError(
+                    f"Invalid agent_framework.evaluation definition for {name!r}: schema_changed must be bool."
+                )
+            if schema_changed and name in called_tools:
+                raise ValueError(
+                    f"Tool {name!r} changed input schema during the captured conversation; "
+                    "automatic evaluation cannot represent multiple schemas for the same called tool. "
+                    "Use distinct tool names or supply an explicit tools= override."
+                )
+            try:
+                schema = json.loads(json.dumps(schema, allow_nan=False))
+            except (TypeError, ValueError) as exc:
+                raise ValueError(
+                    f"Invalid agent_framework.evaluation input_schema for {name!r}: expected JSON-serializable data."
+                ) from exc
+            typed_tools.append(FunctionTool(name=name, description=description, input_model=schema))
     elif agent:
         raw_tools = getattr(agent, "default_options", {}).get("tools", [])
         typed_tools = [tool for tool in normalize_tools(raw_tools) if isinstance(tool, FunctionTool)]
@@ -1604,6 +1644,7 @@ async def evaluate_agent(
     expected_output: str | Sequence[str] | None = None,
     expected_tool_calls: Sequence[ExpectedToolCall] | Sequence[Sequence[ExpectedToolCall]] | None = None,
     responses: AgentResponse[Any] | Sequence[AgentResponse[Any]] | None = None,
+    tools: FunctionTool | Callable[..., Any] | Sequence[FunctionTool | Callable[..., Any]] | None = None,
     evaluators: Evaluator | Callable[..., Any] | Sequence[Evaluator | Callable[..., Any]],
     eval_name: str | None = None,
     context: str | None = None,
@@ -1621,8 +1662,16 @@ async def evaluate_agent(
     or a list for convenience.
 
     If ``responses`` is provided, skips running the agent and evaluates those
-    responses directly — but still extracts tool definitions from the agent.
-    In this mode ``queries`` is required to construct the conversation.
+    responses directly. Tool definitions come from the original run when
+    available, including schema-only snapshots retained through JSON or pickle
+    serialization. Responses without captured definitions fall back to the
+    agent's configured tools; supply ``tools`` when those definitions are
+    unavailable or need to be overridden. In this mode ``queries`` is required
+    to construct the conversation.
+
+    Automatic discovery rejects a called tool whose captured input schema changed
+    under the same name, even if the schemas might be compatible. Use distinct
+    names for different schemas or supply an explicit ``tools`` override.
 
     Args:
         agent: An agent-framework agent instance.
@@ -1642,6 +1691,9 @@ async def evaluate_agent(
             running the agent. A single response is wrapped into a one-element
             list. When provided, ``queries`` must also be provided to
             construct the conversation for evaluation.
+        tools: Tool definitions for evaluation, overriding automatic discovery
+            for every item. These are not passed to ``agent.run``. An empty
+            sequence disables tool definitions.
         evaluators: One or more ``Evaluator`` instances.
         eval_name: Display name (defaults to agent name).
         context: Optional context for groundedness evaluation.
@@ -1746,6 +1798,7 @@ async def evaluate_agent(
                         query=q,
                         response=r,
                         agent=agent,
+                        tools=tools,
                         context=context,
                     )
                 )
@@ -1766,6 +1819,7 @@ async def evaluate_agent(
                         query=query,
                         response=response,
                         agent=agent,
+                        tools=tools,
                         context=context,
                     )
                 )