agent-framework-foundry 1.13.0__tar.gz → 1.14.0__tar.gz

{agent_framework_foundry-1.13.0 → agent_framework_foundry-1.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-foundry
-Version: 1.13.0
+Version: 1.14.0
 Summary: Microsoft Foundry integrations for Microsoft Agent Framework.
 Author-email: Microsoft <af-support@microsoft.com>
 Requires-Python: >=3.10
@@ -16,11 +16,11 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 License-File: LICENSE
-Requires-Dist: agent-framework-core>=1.17.0,<2
-Requires-Dist: agent-framework-openai>=1.14.2,<2
+Requires-Dist: agent-framework-core>=1.20.0,<2
+Requires-Dist: agent-framework-openai>=1.15.0,<2
 Requires-Dist: aiohttp>=3.9,<4
 Requires-Dist: azure-ai-inference>=1.0.0b9,<1.0.0b10
-Requires-Dist: azure-ai-projects>=2.2.0,<2.7.0
+Requires-Dist: azure-ai-projects>=2.2.0,<2.8.0
 Requires-Dist: httpx>=0.28,<1
 Project-URL: homepage, https://aka.ms/agent-framework
 Project-URL: issues, https://github.com/microsoft/agent-framework/issues
@@ -33,10 +33,56 @@ This package contains the Microsoft Foundry integrations for Microsoft Agent Fra
 
 ## SDK compatibility
 
-This package supports `azure-ai-projects>=2.2.0,<2.7.0`. Projects 2.5 and later require
+This package supports `azure-ai-projects>=2.2.0,<2.8.0`. Projects 2.5 and later require
 `openai>=3.0.0`, so `agent-framework-foundry` requires `agent-framework-openai>=1.14.2`,
 which supports both OpenAI 2.x and 3.x.
 
+## Tracing an existing Foundry agent
+
+Install Azure Monitor to connect client and service traces:
+
+```shell
+pip install --upgrade agent-framework-foundry "azure-monitor-opentelemetry>=1.8.10,<2"
+```
+
+With Application Insights connected to your project, call
+`await agent.configure_azure_monitor()` before invoking a `FoundryAgent`.
+See [the tracing sample](../../samples/02-agents/observability/foundry_agent_tracing.py)
+for streaming and non-streaming examples.
+
+## Embeddings
+
+`FoundryEmbeddingClient` supports OpenAI text embedding deployments exposed through a Microsoft Foundry project.
+Pass an existing `AIProjectClient`, or provide the project endpoint and an async Azure credential:
+
+```python
+import os
+
+from agent_framework.foundry import FoundryEmbeddingClient
+from azure.identity.aio import AzureCliCredential
+
+async with AzureCliCredential() as credential:
+    async with FoundryEmbeddingClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_EMBEDDING_MODEL"],
+        credential=credential,
+    ) as client:
+        result = await client.get_embeddings(["Hello, world!"])
+        print(result[0].dimensions)
+```
+
+Set `FOUNDRY_PROJECT_ENDPOINT` to the project endpoint and `FOUNDRY_EMBEDDING_MODEL` to the embedding deployment
+name. When an `AIProjectClient` is already available, pass it as `project_client` and omit the endpoint and
+credential.
+
+The client uses the project for authentication and converts a
+`https://<resource>.services.ai.azure.com/api/projects/<project>` endpoint to the documented resource-scoped
+`https://<resource>.openai.azure.com/openai/v1/` model route. The existing `FOUNDRY_MODELS_ENDPOINT` and
+`FOUNDRY_MODELS_API_KEY` configuration remains available for Foundry Models inference endpoints. A Models endpoint is
+required for image embedding models. If both project and Models endpoints are configured only through environment
+variables, the Models endpoint is retained for backward compatibility; pass `project_endpoint` explicitly to select
+the project OpenAI deployment.
+
 ## Evaluations
 
 `FoundryEvals` implements the provider-neutral `Evaluator` protocol with
@@ -134,10 +180,42 @@ agent = Agent(
 )
 ```
 
-Generally available factories: `get_code_interpreter_tool`,
+Non-preview factories: `get_computer_tool`, `get_code_interpreter_tool`,
 `get_file_search_tool`, `get_web_search_tool`,
 `get_image_generation_tool`, `get_mcp_tool`.
 
+`get_computer_tool()` returns the Foundry SDK's `ComputerTool` (available in
+`azure-ai-projects>=2.3.0`). The package still supports 2.2.x for other tools:
+only calling this factory on an older SDK raises `ImportError` with upgrade guidance.
+`get_computer_use_tool(...)` remains available for the separate preview API.
+The OpenAI Responses client also exposes `OpenAIChatClient.get_computer_tool()`.
+The new `ComputerSafetyCheck` type and `Content.from_computer_tool_call` /
+`Content.from_computer_tool_result` constructors are experimental Agent Framework APIs,
+even though Foundry's `ComputerTool` is a non-preview SDK model.
+
+Computer calls arrive as `Content` with `type="computer_tool_call"`, a
+provider item `id`, a distinct `call_id`, ordered `actions`, and optional
+`pending_safety_checks`. Unanswered calls require application input: inspect
+`AgentResponse.user_input_requests` (or `ChatResponse.messages[*].contents`),
+show the actions and warnings to the user, and execute actions only after
+approval. To continue, return `Content.from_computer_tool_result(call_id=...,
+screenshot=Content.from_data(image_bytes, "image/png"))` in a tool message;
+`Content.from_uri(...)` and `Content.from_hosted_file(...)` also work for
+screenshots. Shared `Content` allows a result without a screenshot for other
+providers, but OpenAI and Foundry Responses require one. If checks were pending,
+explicitly pass *only* those the
+application has confirmed as `acknowledged_safety_checks=[{"id": "..."}]`.
+The framework never acknowledges warnings on your behalf. Calls and results
+can be persisted as `Content.to_dict()` and restored with `Content.from_dict()`.
+A call already paired with a completed screenshot result stays in the transcript
+for audit (`informational_only=True`), but does not appear in
+`AgentResponse.user_input_requests`. When a workflow pauses on a computer call
+alongside locally executable functions, it sends their completed results with
+the screenshot in the original call order after the application responds. If
+any computer request in a workflow batch is cancelled, the remaining requests
+in that agent's batch are cancelled too; the terminal output retains already
+resolved results, and the next turn starts with a fresh agent session.
+
 > **Choosing a web grounding tool.** `get_web_search_tool` is the recommended
 > default — it requires no separate Bing resource and works with Azure OpenAI
 > models out of the box. Reach for `get_bing_grounding_tool` (experimental,

{agent_framework_foundry-1.13.0 → agent_framework_foundry-1.14.0}/README.md

@@ -4,10 +4,56 @@ This package contains the Microsoft Foundry integrations for Microsoft Agent Fra
 
 ## SDK compatibility
 
-This package supports `azure-ai-projects>=2.2.0,<2.7.0`. Projects 2.5 and later require
+This package supports `azure-ai-projects>=2.2.0,<2.8.0`. Projects 2.5 and later require
 `openai>=3.0.0`, so `agent-framework-foundry` requires `agent-framework-openai>=1.14.2`,
 which supports both OpenAI 2.x and 3.x.
 
+## Tracing an existing Foundry agent
+
+Install Azure Monitor to connect client and service traces:
+
+```shell
+pip install --upgrade agent-framework-foundry "azure-monitor-opentelemetry>=1.8.10,<2"
+```
+
+With Application Insights connected to your project, call
+`await agent.configure_azure_monitor()` before invoking a `FoundryAgent`.
+See [the tracing sample](../../samples/02-agents/observability/foundry_agent_tracing.py)
+for streaming and non-streaming examples.
+
+## Embeddings
+
+`FoundryEmbeddingClient` supports OpenAI text embedding deployments exposed through a Microsoft Foundry project.
+Pass an existing `AIProjectClient`, or provide the project endpoint and an async Azure credential:
+
+```python
+import os
+
+from agent_framework.foundry import FoundryEmbeddingClient
+from azure.identity.aio import AzureCliCredential
+
+async with AzureCliCredential() as credential:
+    async with FoundryEmbeddingClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_EMBEDDING_MODEL"],
+        credential=credential,
+    ) as client:
+        result = await client.get_embeddings(["Hello, world!"])
+        print(result[0].dimensions)
+```
+
+Set `FOUNDRY_PROJECT_ENDPOINT` to the project endpoint and `FOUNDRY_EMBEDDING_MODEL` to the embedding deployment
+name. When an `AIProjectClient` is already available, pass it as `project_client` and omit the endpoint and
+credential.
+
+The client uses the project for authentication and converts a
+`https://<resource>.services.ai.azure.com/api/projects/<project>` endpoint to the documented resource-scoped
+`https://<resource>.openai.azure.com/openai/v1/` model route. The existing `FOUNDRY_MODELS_ENDPOINT` and
+`FOUNDRY_MODELS_API_KEY` configuration remains available for Foundry Models inference endpoints. A Models endpoint is
+required for image embedding models. If both project and Models endpoints are configured only through environment
+variables, the Models endpoint is retained for backward compatibility; pass `project_endpoint` explicitly to select
+the project OpenAI deployment.
+
 ## Evaluations
 
 `FoundryEvals` implements the provider-neutral `Evaluator` protocol with
@@ -105,10 +151,42 @@ agent = Agent(
 )
 ```
 
-Generally available factories: `get_code_interpreter_tool`,
+Non-preview factories: `get_computer_tool`, `get_code_interpreter_tool`,
 `get_file_search_tool`, `get_web_search_tool`,
 `get_image_generation_tool`, `get_mcp_tool`.
 
+`get_computer_tool()` returns the Foundry SDK's `ComputerTool` (available in
+`azure-ai-projects>=2.3.0`). The package still supports 2.2.x for other tools:
+only calling this factory on an older SDK raises `ImportError` with upgrade guidance.
+`get_computer_use_tool(...)` remains available for the separate preview API.
+The OpenAI Responses client also exposes `OpenAIChatClient.get_computer_tool()`.
+The new `ComputerSafetyCheck` type and `Content.from_computer_tool_call` /
+`Content.from_computer_tool_result` constructors are experimental Agent Framework APIs,
+even though Foundry's `ComputerTool` is a non-preview SDK model.
+
+Computer calls arrive as `Content` with `type="computer_tool_call"`, a
+provider item `id`, a distinct `call_id`, ordered `actions`, and optional
+`pending_safety_checks`. Unanswered calls require application input: inspect
+`AgentResponse.user_input_requests` (or `ChatResponse.messages[*].contents`),
+show the actions and warnings to the user, and execute actions only after
+approval. To continue, return `Content.from_computer_tool_result(call_id=...,
+screenshot=Content.from_data(image_bytes, "image/png"))` in a tool message;
+`Content.from_uri(...)` and `Content.from_hosted_file(...)` also work for
+screenshots. Shared `Content` allows a result without a screenshot for other
+providers, but OpenAI and Foundry Responses require one. If checks were pending,
+explicitly pass *only* those the
+application has confirmed as `acknowledged_safety_checks=[{"id": "..."}]`.
+The framework never acknowledges warnings on your behalf. Calls and results
+can be persisted as `Content.to_dict()` and restored with `Content.from_dict()`.
+A call already paired with a completed screenshot result stays in the transcript
+for audit (`informational_only=True`), but does not appear in
+`AgentResponse.user_input_requests`. When a workflow pauses on a computer call
+alongside locally executable functions, it sends their completed results with
+the screenshot in the original call order after the application responds. If
+any computer request in a workflow batch is cancelled, the remaining requests
+in that agent's batch are cancelled too; the terminal output retains already
+resolved results, and the next turn starts with a fresh agent session.
+
 > **Choosing a web grounding tool.** `get_web_search_tool` is the recommended
 > default — it requires no separate Bing resource and works with Azure OpenAI
 > models out of the box. Reach for `get_bing_grounding_tool` (experimental,

{agent_framework_foundry-1.13.0 → agent_framework_foundry-1.14.0}/agent_framework_foundry/_agent.py

@@ -658,6 +658,14 @@ class RawFoundryAgent(
     """
 
     service_session_state_keys: ClassVar[frozenset[str]] = frozenset({FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY})
+    """Session-state keys this agent owns, which untrusted input must never supply.
+
+    Holds the Foundry hosted-agent session ID. Despite the attribute name, that value is not a conversation or
+    an ``AgentSession.service_session_id``: it identifies the hosted agent's *runtime session*, a VM-isolated
+    sandbox with a persistent filesystem. Hosts such as AG-UI read this to reject client-supplied values, since
+    honouring one would run the server's own credentialed call inside another session's sandbox. Hosts are
+    expected to reserve this key independently as well, because a wrapper agent may not forward this attribute.
+    """
 
     def __init__(
         self,
@@ -848,6 +856,8 @@ class RawFoundryAgent(
 
         This method configures Azure Monitor for telemetry collection using the
         connection string from the Foundry project client (accessed via the internal client).
+        Use azure-monitor-opentelemetry>=1.8.10,<2 for HTTPX/HTTPX2
+        auto-instrumentation that connects client and service traces.
 
         Args:
             enable_sensitive_data: Enable sensitive data logging (prompts, responses).
@@ -855,7 +865,7 @@ class RawFoundryAgent(
             **kwargs: Additional arguments passed to configure_azure_monitor().
 
         Raises:
-            ImportError: If azure-monitor-opentelemetry-exporter is not installed.
+            ImportError: If azure-monitor-opentelemetry is not installed.
         """
         from agent_framework.observability import (
             OBSERVABILITY_SETTINGS,
@@ -892,7 +902,7 @@ class RawFoundryAgent(
         except ImportError as exc:
             raise ImportError(
                 "azure-monitor-opentelemetry is required for Azure Monitor integration. "
-                "Install it with: pip install azure-monitor-opentelemetry"
+                'Install it with: pip install "azure-monitor-opentelemetry>=1.8.10,<2"'
             ) from exc
 
         if "resource" not in kwargs:

{agent_framework_foundry-1.13.0 → agent_framework_foundry-1.14.0}/agent_framework_foundry/_chat_client.py

@@ -5,10 +5,11 @@ from __future__ import annotations
 import logging
 import sys
 from collections.abc import Awaitable, Callable, Mapping, Sequence
-from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, cast
 
 from agent_framework import (
     ChatMiddlewareLayer,
+    ChatResponse,
     ChatResponseUpdate,
     Content,
     FunctionInvocationConfiguration,
@@ -84,6 +85,16 @@ logger: logging.Logger = logging.getLogger("agent_framework.foundry")
 
 AzureTokenProvider = Callable[[], str | Awaitable[str]]
 AzureCredentialTypes = TokenCredential | AsyncTokenCredential
+_FOUNDRY_REASONING_REPLAY_ITEM_KEY = "__foundry_reasoning_replay_item__"
+_FOUNDRY_REASONING_REPLAY_FIELDS = frozenset({
+    "type",
+    "id",
+    "response_id",
+    "status",
+    "summary",
+    "content",
+    "encrypted_content",
+})
 
 
 class FoundrySettings(TypedDict, total=False):
@@ -270,6 +281,73 @@ class RawFoundryChatClient(
                 run_options.pop("include")
         return run_options
 
+    @override
+    def _prepare_provider_reasoning_item_for_openai(
+        self,
+        reasoning_id: str,
+        contents: Sequence[Content],
+    ) -> dict[str, Any] | None:
+        for content in reversed(contents):
+            raw_item = content.additional_properties.get(_FOUNDRY_REASONING_REPLAY_ITEM_KEY)
+            if isinstance(raw_item, Mapping):
+                payload = self._prepare_foundry_reasoning_replay_item(raw_item)
+                if payload is not None and payload["id"] == reasoning_id:
+                    return payload
+        return None
+
+    @classmethod
+    def _prepare_foundry_reasoning_replay_item(cls, item: Any) -> dict[str, Any] | None:
+        payload = cls._serialize_provider_payload(item)
+        if not isinstance(payload, Mapping):
+            return None
+        typed_payload = cast("Mapping[str, Any]", payload)
+        if typed_payload.get("type") != "reasoning":
+            return None
+        reasoning_id = typed_payload.get("id")
+        if not isinstance(reasoning_id, str) or not reasoning_id:
+            return None
+        response_id = typed_payload.get("response_id")
+        if not isinstance(response_id, str) or not response_id:
+            return None
+        if not isinstance(typed_payload.get("summary"), list) or not isinstance(typed_payload.get("content"), list):
+            return None
+        return {key: typed_payload[key] for key in _FOUNDRY_REASONING_REPLAY_FIELDS if key in typed_payload}
+
+    @classmethod
+    def _attach_foundry_reasoning_replay_item(cls, contents: list[Content], item: Any) -> None:
+        payload = cls._prepare_foundry_reasoning_replay_item(item)
+        if payload is None:
+            return
+
+        reasoning_id = cast(str, payload["id"])
+        for content in reversed(contents):
+            if content.type == "text_reasoning" and content.id == reasoning_id:
+                content.additional_properties[_FOUNDRY_REASONING_REPLAY_ITEM_KEY] = payload
+                return
+
+        contents.append(
+            Content.from_text_reasoning(
+                id=reasoning_id,
+                text="",
+                raw_representation=item,
+                additional_properties={_FOUNDRY_REASONING_REPLAY_ITEM_KEY: payload},
+            )
+        )
+
+    @override
+    def _parse_response_from_openai(
+        self,
+        response: Any,
+        options: dict[str, Any],
+    ) -> ChatResponse:
+        chat_response = super()._parse_response_from_openai(response, options)
+        if chat_response.messages:
+            for item in getattr(response, "output", ()):
+                if getattr(item, "type", None) != "reasoning":
+                    continue
+                self._attach_foundry_reasoning_replay_item(chat_response.messages[0].contents, item)
+        return chat_response
+
     @override
     def _check_model_presence(self, options: dict[str, Any]) -> None:
         if not options.get("model"):
@@ -297,7 +375,10 @@ class RawFoundryChatClient(
         update = try_parse_oauth_consent_event(event, self.model)
         if update is not None:
             return update
-        return super()._parse_chunk_from_openai(event, options, function_call_ids, seen_reasoning_delta_item_ids)
+        update = super()._parse_chunk_from_openai(event, options, function_call_ids, seen_reasoning_delta_item_ids)
+        if event.type == "response.output_item.done" and getattr(event.item, "type", None) == "reasoning":
+            self._attach_foundry_reasoning_replay_item(update.contents, event.item)
+        return update
 
     async def configure_azure_monitor(
         self,
@@ -308,6 +389,8 @@ class RawFoundryChatClient(
 
         This method configures Azure Monitor for telemetry collection using the
         connection string from the Foundry project client.
+        Use azure-monitor-opentelemetry>=1.8.10,<2 for HTTPX/HTTPX2
+        auto-instrumentation that connects client and service traces.
 
         Args:
             enable_sensitive_data: Enable sensitive data logging (prompts, responses).
@@ -319,7 +402,7 @@ class RawFoundryChatClient(
                 - resource (Resource): Custom OpenTelemetry resource
 
         Raises:
-            ImportError: If azure-monitor-opentelemetry-exporter is not installed.
+            ImportError: If azure-monitor-opentelemetry is not installed.
         """
         from agent_framework.observability import (
             OBSERVABILITY_SETTINGS,
@@ -352,7 +435,7 @@ class RawFoundryChatClient(
         except ImportError as exc:
             raise ImportError(
                 "azure-monitor-opentelemetry is required for Azure Monitor integration. "
-                "Install it with: pip install azure-monitor-opentelemetry"
+                'Install it with: pip install "azure-monitor-opentelemetry>=1.8.10,<2"'
             ) from exc
 
         if "resource" not in kwargs:
@@ -672,6 +755,7 @@ class RawFoundryChatClient(
             description: A description of what the MCP server provides.
             approval_mode: Tool approval mode ("always_require", "never_require", or dict).
             allowed_tools: List of allowed tool names from this MCP server.
+                None omits the filter; an empty list is sent unchanged.
             headers: HTTP headers to include in requests to the MCP server.
             project_connection_id: Foundry connection ID for managed MCP connections.
             **kwargs: Additional arguments passed to the SDK MCPTool constructor.
@@ -697,7 +781,7 @@ class RawFoundryChatClient(
             mcp["project_connection_id"] = project_connection_id
         elif headers:
             mcp["headers"] = headers
-        if allowed_tools:
+        if allowed_tools is not None:
             mcp["allowed_tools"] = allowed_tools
         if approval_mode:
             if isinstance(approval_mode, str):
@@ -840,6 +924,23 @@ class RawFoundryChatClient(
             params["update_delay"] = update_delay
         return MemorySearchPreviewTool(**params)
 
+    @staticmethod
+    def get_computer_tool() -> Any:
+        """Create a non-preview Foundry computer tool (requires azure-ai-projects >= 2.3.0).
+
+        Older supported SDK releases can still import this client; calling this
+        factory on those releases raises ``ImportError`` with upgrade guidance.
+        """
+        try:
+            from azure.ai.projects.models import ComputerTool
+        except ImportError as exc:
+            raise ImportError(
+                "FoundryChatClient.get_computer_tool() requires ComputerTool from azure-ai-projects>=2.3.0. "
+                "Upgrade azure-ai-projects to >=2.3.0 to use this tool."
+            ) from exc
+
+        return ComputerTool()
+
     @staticmethod
     @experimental(feature_id=ExperimentalFeature.FOUNDRY_PREVIEW_TOOLS)
     def get_computer_use_tool(

agent_framework_foundry-1.14.0/agent_framework_foundry/_constants.py

@@ -0,0 +1,10 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY = "foundry_hosted_agent_session_id"
+"""``AgentSession.state`` key holding the Foundry hosted-agent session ID.
+
+This is the hosted agent's runtime session, a VM-isolated sandbox with a persistent filesystem, sent as
+``extra_body["agent_session_id"]``. It is distinct from ``AgentSession.service_session_id``, which continues the
+model-side response or conversation chain. The value is server-owned; see
+``RawFoundryAgent.service_session_state_keys``.
+"""