From ea8d8696f2ab9bcd3f27efad7d146bc61189cf19 Mon Sep 17 00:00:00 2001 From: danielquintas8 Date: Tue, 3 Nov 2026 15:26:07 +0000 Subject: [PATCH 1/3] feat: expose provider call IDs in invocation contexts --- .../specs/004-python-function-calling-loop.md | 6 + python/packages/core/AGENTS.md | 3 + .../core/agent_framework/_middleware.py | 11 ++ .../packages/core/agent_framework/_tools.py | 3 + .../core/test_function_invocation_logic.py | 124 ++++++++++++++++++ .../core/tests/core/test_middleware.py | 10 ++ python/packages/core/tests/core/test_tools.py | 35 +++++ 7 files changed, 192 insertions(+) diff --git a/docs/specs/004-python-function-calling-loop.md b/docs/specs/004-python-function-calling-loop.md index b35a4fe23d9..85e103def54 100644 --- a/docs/specs/004-python-function-calling-loop.md +++ b/docs/specs/004-python-function-calling-loop.md @@ -425,6 +425,11 @@ that manually replay messages own the equivalent rule: do not resend an approval - Parallel calls retain model order in the returned transcript. - `call_id` remains the provider/service correlation id; a locally actionable `function_call` also carries a stable Agent Framework occurrence identity in `Content.id`. +- `FunctionInvocationContext.call_id` exposes that provider ID as a read-only property before function middleware + and tool execution, with or without middleware and after approval resume. Standalone `FunctionTool.invoke` calls + use the supplied `tool_call_id`, or `None` when omitted; reusing a context does not retain an earlier call ID. + Existing middleware identity metadata remains available. This property does not expose the call's payload or + framework occurrence identity. - Reused `call_id` values are correlated by logical occurrence, not one global value per id. - Existing `Content.id` values survive aggregation and replay and are never regenerated; legacy deserialization does not invent one. @@ -605,6 +610,7 @@ that manually replay messages own the equivalent rule: do not resend an approval | String input | Flexible string input follows the same loop behavior. | `test_base_client_with_function_calling_string_input` | | Multiple sequential rounds | Each round retains one call/result pair. | `test_base_client_with_function_calling_resets` | | Streaming call | Call chunks, one result update, and final text are emitted in order. | `test_base_client_with_streaming_function_calling` | +| Tool-visible provider call ID | Tools and function middleware can read the provider ID on both execution paths, in both response modes, and after approval resume. The public property is read-only. Standalone invocation uses its supplied ID or `None`, including when a context is reused. | `test_tool_context_exposes_provider_call_id`, `packages/core/tests/core/test_tools.py::test_invoke_exposes_tool_call_id_to_context`, `test_invoke_clears_call_id_when_reusing_context_without_an_id`, `packages/core/tests/core/test_middleware.py::TestFunctionInvocationContext` | | Function-call occurrence identity | Actionable calls gain one stable `Content.id`; a safe local empty-`call_id` fallback uses that id with a migration warning, and streaming aggregation preserves provider-assigned occurrence ids across interleaved fragments. OpenAI Chat Completions scopes fragment correlation to each request and `(choice.index, tool.index)`. | `test_actionable_function_call_gets_stable_occurrence_identity`, `test_actionable_function_call_uses_occurrence_identity_for_empty_call_id`, `test_streaming_empty_call_id_keeps_occurrence_identity_through_approval`, `test_streaming_empty_call_id_delta_reuses_opening_call_identity`, `test_streaming_interleaved_indexed_call_fragments_coalesce_by_occurrence`, `packages/core/tests/core/test_types.py::test_function_call_occurrence_id_roundtrips_without_regeneration`, `packages/openai/tests/openai/test_openai_chat_completion_client.py::test_streaming_tool_call_identity_is_request_local_and_scoped_by_choice_index` | | Reasoning-bound call | Finalized output retains reasoning, function call, function result, and final text. | `test_streaming_function_calling_response_includes_reasoning_and_tool_results` | | Calls across response messages | Every actionable call is executed once. | `test_base_client_executes_function_calls_across_multiple_response_messages` | diff --git a/python/packages/core/AGENTS.md b/python/packages/core/AGENTS.md index 3acfc513d51..cb532c55f13 100644 --- a/python/packages/core/AGENTS.md +++ b/python/packages/core/AGENTS.md @@ -195,6 +195,9 @@ The vector store API is experimental under the shared `VECTOR_STORES` feature ID - **`AgentMiddleware`** - Intercepts agent `run()` calls - **`ChatMiddleware`** - Intercepts chat client `get_response()` calls - **`FunctionMiddleware`** - Intercepts function/tool invocations +- **`FunctionInvocationContext.call_id`** - Read-only provider call ID, available before function middleware and + tool execution in the automatic loop, including approval resume. Standalone `FunctionTool.invoke` calls use + `tool_call_id` and expose `None` when it is omitted. Existing middleware identity metadata remains available. - **`AgentContext`** / **`ChatContext`** / **`FunctionInvocationContext`** - Context objects passed through middleware. A tool can declare a `FunctionInvocationContext` parameter to receive it; `context.tools` is the live, mutable tools list for the run, and `context.add_tools(...)` / `context.remove_tools(...)` enable progressive tool exposure (changes apply on the next function-calling iteration). Chat middleware that constructs provider-local replacement messages must call `context.record_message_replacement(...)` for every replacement before downstream compaction so complete summaries can reconcile to caller-owned messages without persisting the replacements themselves. - **`MessageInjectionMiddleware`** - Session-scoped chat middleware that lets tools or other code enqueue messages for the next model call in the current `AgentSession`; it drains queued messages into the next call and loops only when no function calls need to be handled by the function invocation layer. diff --git a/python/packages/core/agent_framework/_middleware.py b/python/packages/core/agent_framework/_middleware.py index 96478b9eb44..c5aecdf19c1 100644 --- a/python/packages/core/agent_framework/_middleware.py +++ b/python/packages/core/agent_framework/_middleware.py @@ -439,6 +439,11 @@ class FunctionInvocationContext: Attributes: function: The function being invoked. + call_id: The read-only provider call ID for this invocation. Automatic invocation + supplies it before function middleware and tool execution, including + approval resume. Direct ``FunctionTool.invoke`` calls use ``tool_call_id``; + it is ``None`` when no ID is supplied. This is distinct from the + framework occurrence identity in ``Content.id``. arguments: The function arguments. In the automatic function-calling loop, schema-compatible provider arguments retain the existing normalized mapping contract. If provisional normalization rejects provider @@ -535,6 +540,7 @@ def __init__( or ``None`` when the invocation path cannot establish that ownership. """ self.function = function + self._call_id: str | None = None self.arguments = arguments self.session = session self.metadata: dict[str, Any] = dict(metadata) if metadata is not None else {} @@ -545,6 +551,11 @@ def __init__( ) self.tools = tools + @property + def call_id(self) -> str | None: + """Get the provider call ID supplied by the invocation layer, if any.""" + return self._call_id + @experimental(feature_id=ExperimentalFeature.PROGRESSIVE_TOOLS) def add_tools( self, diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index 8aa177ec117..4ba04d49602 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -1198,6 +1198,8 @@ async def invoke( ) if effective_context is not None: effective_context.function = self + # Invocation owns this read-only public value, including clearing a reused context. + effective_context._call_id = tool_call_id # pyright: ignore[reportPrivateUsage] effective_context.arguments = validated_arguments effective_context.kwargs = dict(runtime_kwargs) @@ -2395,6 +2397,7 @@ async def _auto_invoke_function( raise KeyError(f'Function "{function_call_content.name}" is missing call_id.') # Pass both provider correlation and framework occurrence identity to middleware. + middleware_context._call_id = call_id # pyright: ignore[reportPrivateUsage] # Bind before middleware runs. middleware_context.metadata["call_id"] = call_id if function_call_content.id is not None: middleware_context.metadata["function_call_occurrence_id"] = function_call_content.id diff --git a/python/packages/core/tests/core/test_function_invocation_logic.py b/python/packages/core/tests/core/test_function_invocation_logic.py index 73544412e05..5653eddb8d6 100644 --- a/python/packages/core/tests/core/test_function_invocation_logic.py +++ b/python/packages/core/tests/core/test_function_invocation_logic.py @@ -971,6 +971,130 @@ def _finalize(stream_updates: Sequence[ChatResponseUpdate]) -> ChatResponse: chat_client_base._get_streaming_response = _get_streaming_response +@pytest.mark.parametrize("streaming", [False, True], ids=["non-streaming", "streaming"]) +@pytest.mark.parametrize("with_middleware", [False, True], ids=["direct", "middleware"]) +@pytest.mark.parametrize("requires_approval", [False, True], ids=["immediate", "approved"]) +async def test_tool_context_exposes_provider_call_id( + chat_client_base: SupportsChatGetResponse, + streaming: bool, + with_middleware: bool, + requires_approval: bool, +) -> None: + """Tools and middleware receive the provider ID across execution and approval paths.""" + observed_call_ids: list[str] = [] + middleware_call_ids: list[str] = [] + + class ObserveCall(FunctionMiddleware): + async def process(self, context: FunctionInvocationContext, call_next: Callable[[], Awaitable[None]]) -> None: + assert context.call_id is not None + assert context.metadata["call_id"] == context.call_id + middleware_call_ids.append(context.call_id) + await call_next() + + @tool(name="lookup", approval_mode="always_require" if requires_approval else "never_require") + async def lookup(context: FunctionInvocationContext, value: str) -> str: + await asyncio.sleep(0) + provider_call_id = context.call_id + assert provider_call_id is not None + observed_call_ids.append(provider_call_id) + return value + + calls = [ + Content.from_function_call( + call_id=f"provider-{index}", + name="lookup", + arguments='{"value":"same"}', + id=f"occurrence-{index}", + additional_properties={"provider": {"item_id": f"item-{index}"}}, + ) + for index in (1, 2) + ] + responses = [ + ChatResponse(messages=Message(role="assistant", contents=calls)), + ChatResponse(messages=Message(role="assistant", contents=["done"])), + ] + if streaming: + chat_client_base.streaming_responses = [ # type: ignore[attr-defined] # ty: ignore[unresolved-attribute] + [ + ChatResponseUpdate( + role="assistant", + contents=[ + Content.from_function_call( + call_id=f"provider-{index}", + name="lookup", + arguments='{"value":', + id=f"occurrence-{index}", + additional_properties={"provider": {"item_id": f"item-{index}"}}, + ) + for index in (1, 2) + ], + ), + ChatResponseUpdate( + role="assistant", + contents=[ + Content.from_function_call( + call_id=f"provider-{index}", name="", arguments='"same"}', id=f"occurrence-{index}" + ) + for index in (1, 2) + ], + ), + ], + [ChatResponseUpdate(role="assistant", contents=[Content.from_text("done")])], + ] + else: + chat_client_base.run_responses = responses # type: ignore[attr-defined] # ty: ignore[unresolved-attribute] + + agent = Agent(client=chat_client_base, tools=[lookup], middleware=[ObserveCall()] if with_middleware else []) + session = agent.create_session() + + async def run(messages: str | list[Message]) -> list[Message]: + if streaming: + response_stream = agent.run(messages, session=session, stream=True) + updates = [update async for update in response_stream] + response = await response_stream.get_final_response() + assert [ + content.call_id + for update in updates + for content in update.contents + if content.type == "function_result" + ] == [ + content.call_id + for message in response.messages + for content in message.contents + if content.type == "function_result" + ] + else: + response = await agent.run(messages, session=session) + return response.messages + + messages = await run("look up the same value twice") + if requires_approval: + assert observed_call_ids == [] + assert middleware_call_ids == [] + requests = [ + content + for message in messages + for content in message.contents + if content.type == "function_approval_request" + ] + assert len(requests) == 2 + session = AgentSession.from_dict(json.loads(json.dumps(session.to_dict()))) + messages = await run([ + Message( + role="user", contents=[request.to_function_approval_response(approved=True) for request in requests] + ) + ]) + + assert sorted(observed_call_ids) == ["provider-1", "provider-2"] + assert middleware_call_ids == (["provider-1", "provider-2"] if with_middleware else []) + assert [ + (content.call_id, content.id, content.result) + for message in messages + for content in message.contents + if content.type == "function_result" + ] == [("provider-1", "occurrence-1", "same"), ("provider-2", "occurrence-2", "same")] + + async def test_base_client_with_function_calling(chat_client_base: SupportsChatGetResponse): exec_counter = 0 diff --git a/python/packages/core/tests/core/test_middleware.py b/python/packages/core/tests/core/test_middleware.py index ab473306b5f..0fb235861ec 100644 --- a/python/packages/core/tests/core/test_middleware.py +++ b/python/packages/core/tests/core/test_middleware.py @@ -99,6 +99,16 @@ def test_init_with_defaults(self, mock_function: FunctionTool) -> None: assert context.function is mock_function assert context.arguments == arguments assert context.metadata == {} + assert context.call_id is None + + def test_call_id_is_read_only(self, mock_function: FunctionTool) -> None: + """Applications cannot overwrite the framework-owned call ID through the public property.""" + context = FunctionInvocationContext(function=mock_function, arguments={}) + + with pytest.raises(AttributeError): + setattr(context, "call_id", "replacement") # noqa: B010 - Exercise runtime rejection, not typed assignment. + + assert context.call_id is None def test_init_with_custom_metadata(self, mock_function: FunctionTool) -> None: """Test FunctionInvocationContext initialization with custom metadata.""" diff --git a/python/packages/core/tests/core/test_tools.py b/python/packages/core/tests/core/test_tools.py index 39b2688501e..a5e6b57681c 100644 --- a/python/packages/core/tests/core/test_tools.py +++ b/python/packages/core/tests/core/test_tools.py @@ -1608,6 +1608,41 @@ def tool_with_kwargs(x: int, **kwargs: Any) -> str: assert result_default[0].text == "x=10, user=unknown" +@pytest.mark.parametrize("explicit_context", [False, True]) +@pytest.mark.parametrize("tool_call_id", [None, "manual-call"]) +async def test_invoke_exposes_tool_call_id_to_context(explicit_context: bool, tool_call_id: str | None) -> None: + """Standalone invocation exposes the supplied ID without fabricating one.""" + observed_call_ids: list[str | None] = [] + + @tool(approval_mode="never_require") + def lookup(context: FunctionInvocationContext) -> str: + observed_call_ids.append(context.call_id) + return "found" + + context = FunctionInvocationContext(function=lookup, arguments={}) if explicit_context else None + result = await lookup.invoke(context=context, tool_call_id=tool_call_id) + + assert observed_call_ids == [tool_call_id] + assert result[0].text == "found" + assert lookup.parameters()["properties"] == {} + + +async def test_invoke_clears_call_id_when_reusing_context_without_an_id() -> None: + """A reused manual context must not retain the previous invocation's call ID.""" + observed_call_ids: list[str | None] = [] + + @tool(approval_mode="never_require") + def lookup(context: FunctionInvocationContext) -> str: + observed_call_ids.append(context.call_id) + return "found" + + context = FunctionInvocationContext(function=lookup, arguments={}) + await lookup.invoke(context=context, tool_call_id="first-call") + await lookup.invoke(context=context) + + assert observed_call_ids == ["first-call", None] + + async def test_ai_function_with_explicit_invocation_context(): """Test that invoke() can receive runtime kwargs via FunctionInvocationContext.""" From e4423890300a6d352098a7fd1b53ef193eb46180 Mon Sep 17 00:00:00 2001 From: danielquintas8 Date: Wed, 4 Nov 2026 11:03:36 +0000 Subject: [PATCH 2/3] fix: bind invocation call IDs before validation --- .../packages/core/agent_framework/_tools.py | 6 +- python/packages/core/tests/core/test_tools.py | 59 ++++++++++++++++++- 2 files changed, 62 insertions(+), 3 deletions(-) diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index 4ba04d49602..881a744ddb4 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -1153,6 +1153,9 @@ async def invoke( Raises: TypeError: If arguments is not mapping-like or fails schema checks. """ + if context is not None: + # Bind before validation so failed invocations cannot retain an earlier call ID. + context._call_id = tool_call_id # pyright: ignore[reportPrivateUsage] if self.declaration_only: raise ToolException(f"Function '{self.name}' is declaration only and cannot be invoked.") global OBSERVABILITY_SETTINGS @@ -1196,10 +1199,9 @@ async def invoke( arguments=validated_arguments, kwargs=runtime_kwargs, ) + effective_context._call_id = tool_call_id # pyright: ignore[reportPrivateUsage] if effective_context is not None: effective_context.function = self - # Invocation owns this read-only public value, including clearing a reused context. - effective_context._call_id = tool_call_id # pyright: ignore[reportPrivateUsage] effective_context.arguments = validated_arguments effective_context.kwargs = dict(runtime_kwargs) diff --git a/python/packages/core/tests/core/test_tools.py b/python/packages/core/tests/core/test_tools.py index a5e6b57681c..3a68dc6886c 100644 --- a/python/packages/core/tests/core/test_tools.py +++ b/python/packages/core/tests/core/test_tools.py @@ -21,7 +21,7 @@ FunctionTool, tool, ) -from agent_framework._middleware import FunctionInvocationContext +from agent_framework._middleware import FunctionInvocationContext, MiddlewareFailure from agent_framework._tools import ( _auto_invoke_function, _format_tool_parameters, @@ -1643,6 +1643,63 @@ def lookup(context: FunctionInvocationContext) -> str: assert observed_call_ids == ["first-call", None] +@pytest.mark.parametrize("tool_call_id", [None, "second-call"]) +@pytest.mark.parametrize( + ("arguments", "invocation_kwargs", "error_message"), + [ + ({"item": "invalid"}, {}, "Invalid arguments"), + ({"item": 1}, {"unexpected": True}, "Unexpected keyword argument"), + ], +) +async def test_invoke_updates_call_id_before_argument_validation( + tool_call_id: str | None, + arguments: dict[str, Any], + invocation_kwargs: dict[str, Any], + error_message: str, +) -> None: + """Rejected arguments must not leave an earlier call ID on a reused context.""" + executed_items: list[int] = [] + + @tool(approval_mode="never_require") + def lookup(item: int) -> str: + executed_items.append(item) + return "found" + + context = FunctionInvocationContext(function=lookup, arguments={"item": 1}) + await lookup.invoke(context=context, tool_call_id="first-call") + assert context.call_id == "first-call" + + with pytest.raises(TypeError, match=error_message): + await lookup.invoke(arguments=arguments, context=context, tool_call_id=tool_call_id, **invocation_kwargs) + + assert context.call_id == tool_call_id + assert executed_items == [1] + + +@pytest.mark.parametrize("tool_call_id", [None, "second-call"]) +async def test_invoke_updates_call_id_before_security_validation(tool_call_id: str | None) -> None: + """Security rejection must preserve the failed invocation's ID without executing it.""" + executed_items: list[int] = [] + + @tool(approval_mode="never_require") + def lookup(item: int) -> str: + executed_items.append(item) + return "found" + + context = FunctionInvocationContext(function=lookup, arguments={"item": 1}) + context.metadata[tools_module._SECURITY_ARGUMENTS_SNAPSHOT_CONTEXT_KEY] = tools_module._argument_authority_token( + {"item": 1}, boundary="security policy" + ) + await lookup.invoke(context=context, tool_call_id="first-call") + assert context.call_id == "first-call" + + with pytest.raises(MiddlewareFailure, match="Function arguments changed after security middleware"): + await lookup.invoke(arguments={"item": 2}, context=context, tool_call_id=tool_call_id) + + assert context.call_id == tool_call_id + assert executed_items == [1] + + async def test_ai_function_with_explicit_invocation_context(): """Test that invoke() can receive runtime kwargs via FunctionInvocationContext.""" From e1730ef935343b72f2b935777f82ed57b01eaa0f Mon Sep 17 00:00:00 2001 From: danielquintas8 Date: Fri, 6 Nov 2026 13:04:02 +0000 Subject: [PATCH 3/3] fix: expose invocation identity through context metadata --- .../specs/004-python-function-calling-loop.md | 14 ++-- python/packages/core/AGENTS.md | 8 ++- .../core/agent_framework/_middleware.py | 19 ++---- .../packages/core/agent_framework/_tools.py | 42 +++++++++--- .../core/test_function_invocation_logic.py | 40 ++++++----- .../core/tests/core/test_middleware.py | 10 --- python/packages/core/tests/core/test_tools.py | 68 ++++++++++++++----- 7 files changed, 127 insertions(+), 74 deletions(-) diff --git a/docs/specs/004-python-function-calling-loop.md b/docs/specs/004-python-function-calling-loop.md index 85e103def54..a1432fb101c 100644 --- a/docs/specs/004-python-function-calling-loop.md +++ b/docs/specs/004-python-function-calling-loop.md @@ -425,11 +425,13 @@ that manually replay messages own the equivalent rule: do not resend an approval - Parallel calls retain model order in the returned transcript. - `call_id` remains the provider/service correlation id; a locally actionable `function_call` also carries a stable Agent Framework occurrence identity in `Content.id`. -- `FunctionInvocationContext.call_id` exposes that provider ID as a read-only property before function middleware - and tool execution, with or without middleware and after approval resume. Standalone `FunctionTool.invoke` calls - use the supplied `tool_call_id`, or `None` when omitted; reusing a context does not retain an earlier call ID. - Existing middleware identity metadata remains available. This property does not expose the call's payload or - framework occurrence identity. +- `FunctionInvocationContext.metadata["call_id"]` exposes the provider correlation ID, and + `metadata["function_call_occurrence_id"]` exposes the canonical `Content.id` when function-call content has one. + The automatic loop populates these entries before function middleware and tool execution on both execution + paths, including approval resume. Standalone `FunctionTool.invoke` sets or clears the provider ID from + `tool_call_id` before argument and security validation, including failed invocations. An occurrence ID supplied + with a matching provider call ID is preserved; changing or omitting the provider ID clears the occurrence ID. + Absent identity values leave no corresponding metadata entry. Call payloads are not added to the context. - Reused `call_id` values are correlated by logical occurrence, not one global value per id. - Existing `Content.id` values survive aggregation and replay and are never regenerated; legacy deserialization does not invent one. @@ -610,7 +612,7 @@ that manually replay messages own the equivalent rule: do not resend an approval | String input | Flexible string input follows the same loop behavior. | `test_base_client_with_function_calling_string_input` | | Multiple sequential rounds | Each round retains one call/result pair. | `test_base_client_with_function_calling_resets` | | Streaming call | Call chunks, one result update, and final text are emitted in order. | `test_base_client_with_streaming_function_calling` | -| Tool-visible provider call ID | Tools and function middleware can read the provider ID on both execution paths, in both response modes, and after approval resume. The public property is read-only. Standalone invocation uses its supplied ID or `None`, including when a context is reused. | `test_tool_context_exposes_provider_call_id`, `packages/core/tests/core/test_tools.py::test_invoke_exposes_tool_call_id_to_context`, `test_invoke_clears_call_id_when_reusing_context_without_an_id`, `packages/core/tests/core/test_middleware.py::TestFunctionInvocationContext` | +| Tool-visible invocation identity metadata | Tools and function middleware receive the provider call ID and canonical occurrence ID on both execution paths, in both response modes, and after approval resume, including reused provider IDs. Standalone invocation updates or clears identity metadata before validation and retains a supplied occurrence only with a matching provider ID. | `test_tool_context_exposes_call_identity_metadata`, `packages/core/tests/core/test_tools.py::test_invoke_exposes_tool_call_id_metadata`, `test_invoke_clears_stale_identity_metadata`, `test_invoke_preserves_matching_occurrence_metadata`, `test_invoke_updates_call_metadata_before_argument_validation`, `test_invoke_updates_call_metadata_before_security_validation` | | Function-call occurrence identity | Actionable calls gain one stable `Content.id`; a safe local empty-`call_id` fallback uses that id with a migration warning, and streaming aggregation preserves provider-assigned occurrence ids across interleaved fragments. OpenAI Chat Completions scopes fragment correlation to each request and `(choice.index, tool.index)`. | `test_actionable_function_call_gets_stable_occurrence_identity`, `test_actionable_function_call_uses_occurrence_identity_for_empty_call_id`, `test_streaming_empty_call_id_keeps_occurrence_identity_through_approval`, `test_streaming_empty_call_id_delta_reuses_opening_call_identity`, `test_streaming_interleaved_indexed_call_fragments_coalesce_by_occurrence`, `packages/core/tests/core/test_types.py::test_function_call_occurrence_id_roundtrips_without_regeneration`, `packages/openai/tests/openai/test_openai_chat_completion_client.py::test_streaming_tool_call_identity_is_request_local_and_scoped_by_choice_index` | | Reasoning-bound call | Finalized output retains reasoning, function call, function result, and final text. | `test_streaming_function_calling_response_includes_reasoning_and_tool_results` | | Calls across response messages | Every actionable call is executed once. | `test_base_client_executes_function_calls_across_multiple_response_messages` | diff --git a/python/packages/core/AGENTS.md b/python/packages/core/AGENTS.md index cb532c55f13..9322379c7a1 100644 --- a/python/packages/core/AGENTS.md +++ b/python/packages/core/AGENTS.md @@ -195,9 +195,11 @@ The vector store API is experimental under the shared `VECTOR_STORES` feature ID - **`AgentMiddleware`** - Intercepts agent `run()` calls - **`ChatMiddleware`** - Intercepts chat client `get_response()` calls - **`FunctionMiddleware`** - Intercepts function/tool invocations -- **`FunctionInvocationContext.call_id`** - Read-only provider call ID, available before function middleware and - tool execution in the automatic loop, including approval resume. Standalone `FunctionTool.invoke` calls use - `tool_call_id` and expose `None` when it is omitted. Existing middleware identity metadata remains available. +- **Function invocation identity metadata** - `FunctionInvocationContext.metadata["call_id"]` holds the provider + correlation ID, and `metadata["function_call_occurrence_id"]` holds the canonical `Content.id` when present. + The automatic loop supplies both before function middleware and tool execution, including approval resume. + Standalone `FunctionTool.invoke` sets or clears the provider ID from `tool_call_id` before validation and + retains an occurrence ID only when it was supplied with a matching provider call ID. - **`AgentContext`** / **`ChatContext`** / **`FunctionInvocationContext`** - Context objects passed through middleware. A tool can declare a `FunctionInvocationContext` parameter to receive it; `context.tools` is the live, mutable tools list for the run, and `context.add_tools(...)` / `context.remove_tools(...)` enable progressive tool exposure (changes apply on the next function-calling iteration). Chat middleware that constructs provider-local replacement messages must call `context.record_message_replacement(...)` for every replacement before downstream compaction so complete summaries can reconcile to caller-owned messages without persisting the replacements themselves. - **`MessageInjectionMiddleware`** - Session-scoped chat middleware that lets tools or other code enqueue messages for the next model call in the current `AgentSession`; it drains queued messages into the next call and loops only when no function calls need to be handled by the function invocation layer. diff --git a/python/packages/core/agent_framework/_middleware.py b/python/packages/core/agent_framework/_middleware.py index c5aecdf19c1..98f57a2db07 100644 --- a/python/packages/core/agent_framework/_middleware.py +++ b/python/packages/core/agent_framework/_middleware.py @@ -439,11 +439,6 @@ class FunctionInvocationContext: Attributes: function: The function being invoked. - call_id: The read-only provider call ID for this invocation. Automatic invocation - supplies it before function middleware and tool execution, including - approval resume. Direct ``FunctionTool.invoke`` calls use ``tool_call_id``; - it is ``None`` when no ID is supplied. This is distinct from the - framework occurrence identity in ``Content.id``. arguments: The function arguments. In the automatic function-calling loop, schema-compatible provider arguments retain the existing normalized mapping contract. If provisional normalization rejects provider @@ -454,7 +449,13 @@ class FunctionInvocationContext: Middleware that short-circuits without calling ``call_next()`` skips final validation and function execution. session: The agent session for this invocation, if any. - metadata: Metadata dictionary for sharing data between function middleware. + metadata: Metadata dictionary shared by function middleware and context-aware tools. + Automatic invocation supplies ``"call_id"`` for provider correlation and + ``"function_call_occurrence_id"`` for the canonical ``Content.id``, when present, + before middleware and tool execution, including approval resume. Standalone + ``FunctionTool.invoke`` calls set or clear ``"call_id"`` from ``tool_call_id`` + before validation. A supplied occurrence ID is retained only when the context's + provider call ID matches the supplied ``tool_call_id``; otherwise it is cleared. result: Function execution result. This attribute carries no guaranteed type. The pipeline assigns :meth:`FunctionTool.invoke`'s output — a ``list[Content]``, or the wrapped function's raw return value when the @@ -540,7 +541,6 @@ def __init__( or ``None`` when the invocation path cannot establish that ownership. """ self.function = function - self._call_id: str | None = None self.arguments = arguments self.session = session self.metadata: dict[str, Any] = dict(metadata) if metadata is not None else {} @@ -551,11 +551,6 @@ def __init__( ) self.tools = tools - @property - def call_id(self) -> str | None: - """Get the provider call ID supplied by the invocation layer, if any.""" - return self._call_id - @experimental(feature_id=ExperimentalFeature.PROGRESSIVE_TOOLS) def add_tools( self, diff --git a/python/packages/core/agent_framework/_tools.py b/python/packages/core/agent_framework/_tools.py index 881a744ddb4..1779fc7f888 100644 --- a/python/packages/core/agent_framework/_tools.py +++ b/python/packages/core/agent_framework/_tools.py @@ -101,6 +101,23 @@ logger = logging.getLogger("agent_framework") +def _update_function_invocation_metadata( + context: FunctionInvocationContext, + *, + call_id: str | None, + occurrence_id: str | None = None, +) -> None: + """Replace invocation identity metadata without retaining missing values.""" + if call_id is None: + context.metadata.pop("call_id", None) + else: + context.metadata["call_id"] = call_id + if occurrence_id is None: + context.metadata.pop("function_call_occurrence_id", None) + else: + context.metadata["function_call_occurrence_id"] = occurrence_id + + def _generate_function_call_occurrence_id() -> str: """Generate an Agent Framework identity for one function-call occurrence.""" return f"af-call-{uuid4().hex}" @@ -1138,7 +1155,11 @@ async def invoke( Keyword Args: arguments: A mapping or model instance containing the arguments for the function. context: Explicit function invocation context carrying runtime kwargs. - tool_call_id: Optional tool call identifier used for telemetry and tracing. + tool_call_id: Optional provider call identifier used for telemetry, tracing, and + ``context.metadata["call_id"]``. Omitting it clears the context's call identity. + Occurrence metadata supplied with a matching context call ID is preserved; + changing or omitting the call ID clears it. Identity metadata is updated before + argument and security validation, including when invocation fails. skip_parsing: When ``True``, bypass parsing and return the wrapped function's raw value instead of a ``list[Content]``. Defaults to ``False``. kwargs: Direct function argument values. When provided, every keyword @@ -1154,8 +1175,12 @@ async def invoke( TypeError: If arguments is not mapping-like or fails schema checks. """ if context is not None: - # Bind before validation so failed invocations cannot retain an earlier call ID. - context._call_id = tool_call_id # pyright: ignore[reportPrivateUsage] + occurrence_id = ( + context.metadata.get("function_call_occurrence_id") + if tool_call_id is not None and context.metadata.get("call_id") == tool_call_id + else None + ) + _update_function_invocation_metadata(context, call_id=tool_call_id, occurrence_id=occurrence_id) if self.declaration_only: raise ToolException(f"Function '{self.name}' is declaration only and cannot be invoked.") global OBSERVABILITY_SETTINGS @@ -1199,7 +1224,7 @@ async def invoke( arguments=validated_arguments, kwargs=runtime_kwargs, ) - effective_context._call_id = tool_call_id # pyright: ignore[reportPrivateUsage] + _update_function_invocation_metadata(effective_context, call_id=tool_call_id) if effective_context is not None: effective_context.function = self effective_context.arguments = validated_arguments @@ -2343,6 +2368,9 @@ async def _auto_invoke_function( parent_service_session_state_keys=parent_service_session_state_keys, tools=live_tools, ) + _update_function_invocation_metadata( + direct_context, call_id=function_call_content.call_id, occurrence_id=function_call_content.id + ) direct_context.metadata[_PARENT_TOOL_APPROVAL_SOURCE_IDS_CONTEXT_KEY] = parent_approval_source_ids if host_payload_budget is not None: direct_context.metadata[_FUNCTION_RESULT_PAYLOAD_BUDGET_CONTEXT_KEY] = host_payload_budget @@ -2398,11 +2426,7 @@ async def _auto_invoke_function( if call_id is None: raise KeyError(f'Function "{function_call_content.name}" is missing call_id.') - # Pass both provider correlation and framework occurrence identity to middleware. - middleware_context._call_id = call_id # pyright: ignore[reportPrivateUsage] # Bind before middleware runs. - middleware_context.metadata["call_id"] = call_id - if function_call_content.id is not None: - middleware_context.metadata["function_call_occurrence_id"] = function_call_content.id + _update_function_invocation_metadata(middleware_context, call_id=call_id, occurrence_id=function_call_content.id) # Pass through the original approval response so middleware can decide whether # this replay corresponds to a middleware-specific approval flow. diff --git a/python/packages/core/tests/core/test_function_invocation_logic.py b/python/packages/core/tests/core/test_function_invocation_logic.py index 5653eddb8d6..66aeb76360d 100644 --- a/python/packages/core/tests/core/test_function_invocation_logic.py +++ b/python/packages/core/tests/core/test_function_invocation_logic.py @@ -974,34 +974,35 @@ def _finalize(stream_updates: Sequence[ChatResponseUpdate]) -> ChatResponse: @pytest.mark.parametrize("streaming", [False, True], ids=["non-streaming", "streaming"]) @pytest.mark.parametrize("with_middleware", [False, True], ids=["direct", "middleware"]) @pytest.mark.parametrize("requires_approval", [False, True], ids=["immediate", "approved"]) -async def test_tool_context_exposes_provider_call_id( +@pytest.mark.parametrize("reused_provider_id", [False, True], ids=["distinct-call-ids", "reused-call-id"]) +async def test_tool_context_exposes_call_identity_metadata( chat_client_base: SupportsChatGetResponse, streaming: bool, with_middleware: bool, requires_approval: bool, + reused_provider_id: bool, ) -> None: - """Tools and middleware receive the provider ID across execution and approval paths.""" - observed_call_ids: list[str] = [] - middleware_call_ids: list[str] = [] + """Tools and middleware receive provider and occurrence identities across execution paths.""" + observed_identities: list[tuple[str, str]] = [] + middleware_identities: list[tuple[str, str]] = [] + expected_identities = [ + ("provider-shared" if reused_provider_id else f"provider-{index}", f"occurrence-{index}") for index in (1, 2) + ] class ObserveCall(FunctionMiddleware): async def process(self, context: FunctionInvocationContext, call_next: Callable[[], Awaitable[None]]) -> None: - assert context.call_id is not None - assert context.metadata["call_id"] == context.call_id - middleware_call_ids.append(context.call_id) + middleware_identities.append((context.metadata["call_id"], context.metadata["function_call_occurrence_id"])) await call_next() @tool(name="lookup", approval_mode="always_require" if requires_approval else "never_require") async def lookup(context: FunctionInvocationContext, value: str) -> str: await asyncio.sleep(0) - provider_call_id = context.call_id - assert provider_call_id is not None - observed_call_ids.append(provider_call_id) + observed_identities.append((context.metadata["call_id"], context.metadata["function_call_occurrence_id"])) return value calls = [ Content.from_function_call( - call_id=f"provider-{index}", + call_id="provider-shared" if reused_provider_id else f"provider-{index}", name="lookup", arguments='{"value":"same"}', id=f"occurrence-{index}", @@ -1020,7 +1021,7 @@ async def lookup(context: FunctionInvocationContext, value: str) -> str: role="assistant", contents=[ Content.from_function_call( - call_id=f"provider-{index}", + call_id="provider-shared" if reused_provider_id else f"provider-{index}", name="lookup", arguments='{"value":', id=f"occurrence-{index}", @@ -1033,7 +1034,10 @@ async def lookup(context: FunctionInvocationContext, value: str) -> str: role="assistant", contents=[ Content.from_function_call( - call_id=f"provider-{index}", name="", arguments='"same"}', id=f"occurrence-{index}" + call_id="provider-shared" if reused_provider_id else f"provider-{index}", + name="", + arguments='"same"}', + id=f"occurrence-{index}", ) for index in (1, 2) ], @@ -1069,8 +1073,8 @@ async def run(messages: str | list[Message]) -> list[Message]: messages = await run("look up the same value twice") if requires_approval: - assert observed_call_ids == [] - assert middleware_call_ids == [] + assert observed_identities == [] + assert middleware_identities == [] requests = [ content for message in messages @@ -1085,14 +1089,14 @@ async def run(messages: str | list[Message]) -> list[Message]: ) ]) - assert sorted(observed_call_ids) == ["provider-1", "provider-2"] - assert middleware_call_ids == (["provider-1", "provider-2"] if with_middleware else []) + assert sorted(observed_identities) == expected_identities + assert middleware_identities == (expected_identities if with_middleware else []) assert [ (content.call_id, content.id, content.result) for message in messages for content in message.contents if content.type == "function_result" - ] == [("provider-1", "occurrence-1", "same"), ("provider-2", "occurrence-2", "same")] + ] == [(provider_call_id, occurrence_id, "same") for provider_call_id, occurrence_id in expected_identities] async def test_base_client_with_function_calling(chat_client_base: SupportsChatGetResponse): diff --git a/python/packages/core/tests/core/test_middleware.py b/python/packages/core/tests/core/test_middleware.py index 0fb235861ec..ab473306b5f 100644 --- a/python/packages/core/tests/core/test_middleware.py +++ b/python/packages/core/tests/core/test_middleware.py @@ -99,16 +99,6 @@ def test_init_with_defaults(self, mock_function: FunctionTool) -> None: assert context.function is mock_function assert context.arguments == arguments assert context.metadata == {} - assert context.call_id is None - - def test_call_id_is_read_only(self, mock_function: FunctionTool) -> None: - """Applications cannot overwrite the framework-owned call ID through the public property.""" - context = FunctionInvocationContext(function=mock_function, arguments={}) - - with pytest.raises(AttributeError): - setattr(context, "call_id", "replacement") # noqa: B010 - Exercise runtime rejection, not typed assignment. - - assert context.call_id is None def test_init_with_custom_metadata(self, mock_function: FunctionTool) -> None: """Test FunctionInvocationContext initialization with custom metadata.""" diff --git a/python/packages/core/tests/core/test_tools.py b/python/packages/core/tests/core/test_tools.py index 3a68dc6886c..89b4745faec 100644 --- a/python/packages/core/tests/core/test_tools.py +++ b/python/packages/core/tests/core/test_tools.py @@ -1610,13 +1610,15 @@ def tool_with_kwargs(x: int, **kwargs: Any) -> str: @pytest.mark.parametrize("explicit_context", [False, True]) @pytest.mark.parametrize("tool_call_id", [None, "manual-call"]) -async def test_invoke_exposes_tool_call_id_to_context(explicit_context: bool, tool_call_id: str | None) -> None: +async def test_invoke_exposes_tool_call_id_metadata(explicit_context: bool, tool_call_id: str | None) -> None: """Standalone invocation exposes the supplied ID without fabricating one.""" observed_call_ids: list[str | None] = [] @tool(approval_mode="never_require") def lookup(context: FunctionInvocationContext) -> str: - observed_call_ids.append(context.call_id) + observed_call_ids.append(context.metadata.get("call_id")) + assert "function_call_occurrence_id" not in context.metadata + assert ("call_id" in context.metadata) == (tool_call_id is not None) return "found" context = FunctionInvocationContext(function=lookup, arguments={}) if explicit_context else None @@ -1627,20 +1629,50 @@ def lookup(context: FunctionInvocationContext) -> str: assert lookup.parameters()["properties"] == {} -async def test_invoke_clears_call_id_when_reusing_context_without_an_id() -> None: - """A reused manual context must not retain the previous invocation's call ID.""" - observed_call_ids: list[str | None] = [] +@pytest.mark.parametrize("tool_call_id", [None, "second-call", ""]) +async def test_invoke_clears_stale_identity_metadata(tool_call_id: str | None) -> None: + """A changed or omitted call ID must not retain identity from an earlier call.""" + observed_identities: list[tuple[str | None, str | None]] = [] @tool(approval_mode="never_require") def lookup(context: FunctionInvocationContext) -> str: - observed_call_ids.append(context.call_id) + observed_identities.append(( + context.metadata.get("call_id"), + context.metadata.get("function_call_occurrence_id"), + )) return "found" - context = FunctionInvocationContext(function=lookup, arguments={}) - await lookup.invoke(context=context, tool_call_id="first-call") - await lookup.invoke(context=context) + context = FunctionInvocationContext( + function=lookup, + arguments={}, + metadata={"call_id": "first-call", "function_call_occurrence_id": "first-occurrence", "application": "kept"}, + ) + await lookup.invoke(context=context, tool_call_id=tool_call_id) + + assert observed_identities == [(tool_call_id, None)] + assert ("call_id" in context.metadata) == (tool_call_id is not None) + assert "function_call_occurrence_id" not in context.metadata + assert context.metadata["application"] == "kept" + + +@pytest.mark.parametrize("tool_call_id", ["manual-call", ""]) +async def test_invoke_preserves_matching_occurrence_metadata(tool_call_id: str) -> None: + """A custom loop can supply canonical occurrence metadata for the same provider call.""" + observed_identities: list[tuple[str, str]] = [] + + @tool(approval_mode="never_require") + def lookup(context: FunctionInvocationContext) -> str: + observed_identities.append((context.metadata["call_id"], context.metadata["function_call_occurrence_id"])) + return "found" + + context = FunctionInvocationContext( + function=lookup, + arguments={}, + metadata={"call_id": tool_call_id, "function_call_occurrence_id": "manual-occurrence"}, + ) + await lookup.invoke(context=context, tool_call_id=tool_call_id) - assert observed_call_ids == ["first-call", None] + assert observed_identities == [(tool_call_id, "manual-occurrence")] @pytest.mark.parametrize("tool_call_id", [None, "second-call"]) @@ -1651,7 +1683,7 @@ def lookup(context: FunctionInvocationContext) -> str: ({"item": 1}, {"unexpected": True}, "Unexpected keyword argument"), ], ) -async def test_invoke_updates_call_id_before_argument_validation( +async def test_invoke_updates_call_metadata_before_argument_validation( tool_call_id: str | None, arguments: dict[str, Any], invocation_kwargs: dict[str, Any], @@ -1667,17 +1699,19 @@ def lookup(item: int) -> str: context = FunctionInvocationContext(function=lookup, arguments={"item": 1}) await lookup.invoke(context=context, tool_call_id="first-call") - assert context.call_id == "first-call" + assert context.metadata["call_id"] == "first-call" + context.metadata["function_call_occurrence_id"] = "first-occurrence" with pytest.raises(TypeError, match=error_message): await lookup.invoke(arguments=arguments, context=context, tool_call_id=tool_call_id, **invocation_kwargs) - assert context.call_id == tool_call_id + assert context.metadata.get("call_id") == tool_call_id + assert "function_call_occurrence_id" not in context.metadata assert executed_items == [1] @pytest.mark.parametrize("tool_call_id", [None, "second-call"]) -async def test_invoke_updates_call_id_before_security_validation(tool_call_id: str | None) -> None: +async def test_invoke_updates_call_metadata_before_security_validation(tool_call_id: str | None) -> None: """Security rejection must preserve the failed invocation's ID without executing it.""" executed_items: list[int] = [] @@ -1691,12 +1725,14 @@ def lookup(item: int) -> str: {"item": 1}, boundary="security policy" ) await lookup.invoke(context=context, tool_call_id="first-call") - assert context.call_id == "first-call" + assert context.metadata["call_id"] == "first-call" + context.metadata["function_call_occurrence_id"] = "first-occurrence" with pytest.raises(MiddlewareFailure, match="Function arguments changed after security middleware"): await lookup.invoke(arguments={"item": 2}, context=context, tool_call_id=tool_call_id) - assert context.call_id == tool_call_id + assert context.metadata.get("call_id") == tool_call_id + assert "function_call_occurrence_id" not in context.metadata assert executed_items == [1]