From f9d8dd6af4bf7676d88e3117500938eaf124df37 Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Tue, 28 Apr 2026 13:39:05 -0700 Subject: [PATCH 1/4] Update README.md --- sdk/ai/azure-ai-projects/README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/sdk/ai/azure-ai-projects/README.md b/sdk/ai/azure-ai-projects/README.md index b2f754b91fd2..64e5218f7873 100644 --- a/sdk/ai/azure-ai-projects/README.md +++ b/sdk/ai/azure-ai-projects/README.md @@ -1,6 +1,6 @@ # Azure AI Projects client library for Python -The AI Projects client library (in preview) is part of the Microsoft Foundry SDK, and provides easy access to +The AI Projects client library is part of the Microsoft Foundry SDK, and provides easy access to resources in your Microsoft Foundry Project. Use it to: * **Create and run Agents** using methods on the `.agents` client property. @@ -55,8 +55,7 @@ To report an issue with the client library, or request additional features, plea * An [Azure subscription][azure_sub]. * A [project in Microsoft Foundry](https://learn.microsoft.com/azure/foundry/how-to/create-projects). * A Foundry project endpoint URL of the form `https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name`. It can be found in your Microsoft Foundry Project home page. Below we will assume the environment variable `FOUNDRY_PROJECT_ENDPOINT` was defined to hold this value. -* To authenticate using API key, you will need the "Project API key" as shown in your Microsoft Foundry Project home page. -* To authenticate using Entra ID, your application needs an object that implements the [TokenCredential](https://learn.microsoft.com/python/api/azure-core/azure.core.credentials.tokencredential) interface. Code samples here use [DefaultAzureCredential](https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential). To get that working, you will need: +* Client authentication is done using Entra ID. To authenticate, your application needs an object that implements the [TokenCredential](https://learn.microsoft.com/python/api/azure-core/azure.core.credentials.tokencredential) interface. Code samples here use [DefaultAzureCredential](https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential). To get that working, you will need: * An appropriate role assignment. See [Role-based access control in Microsoft Foundry portal](https://learn.microsoft.com/azure/foundry/concepts/rbac-foundry). Role assignment can be done via the "Access Control (IAM)" tab of your Azure AI Project resource in the Azure portal. * [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) installed. * You are logged into your Azure account by running `az login`. @@ -116,12 +115,12 @@ async with ( For comprehensive examples covering Agents, tool usage, evaluation, fine-tuning, datasets, indexes, and more, see: -* **[Microsoft Foundry Agents overview](https://learn.microsoft.com/azure/foundry/agents/overview)** — concepts, setup, and quickstarts. +* **[Microsoft Foundry Agents overview](https://learn.microsoft.com/azure/foundry/agents/overview)** — concepts, setup, and quick-starts. * **[Runtime components](https://learn.microsoft.com/azure/foundry/agents/concepts/runtime-components?tabs=python)** — deep-dive into agent architecture. * **[Tool catalog](https://learn.microsoft.com/azure/foundry/agents/concepts/tool-catalog)** — all available tools and agent capabilities. * **[SDK samples folder][samples]** — fully runnable Python code for synchronous and asynchronous clients covering all operations below. -The sections below cover SDK-specific behaviours (authentication variants, exception handling, logging, tracing) that are not documented in the above Learn pages. +The sections below cover SDK-specific behaviors (authentication variants, exception handling, logging, tracing) that are not documented in the above Learn pages. ### Performing Responses operations using OpenAI client From 4eacd85e05a028cec99c849cda475bc8a9b2d5da Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Tue, 28 Apr 2026 13:56:19 -0700 Subject: [PATCH 2/4] Update changelog.md --- sdk/ai/azure-ai-projects/CHANGELOG.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/sdk/ai/azure-ai-projects/CHANGELOG.md b/sdk/ai/azure-ai-projects/CHANGELOG.md index 2428c6112449..1d028d1e1014 100644 --- a/sdk/ai/azure-ai-projects/CHANGELOG.md +++ b/sdk/ai/azure-ai-projects/CHANGELOG.md @@ -4,8 +4,14 @@ ### Features Added +* New `FabricIQPreviewTool` and `FabricIQPreviewToolParameters` model classes, supporting the new `fabric_iq_preview` tool type. +* New `ToolType.FABRIC_IQ_PREVIEW` enum value added to the `ToolType` enum. +* New read-only property `content_hash` on `CodeConfiguration`, returning the SHA-256 hex digest of the uploaded code zip. + ### Breaking Changes +* Agent Endpoint beta operations: Remove required parameters `user_isolation_key` and `chat_isolation_key` from the `HeaderIsolationKeySource` class constructor. + ### Bugs Fixed ### Sample updates From 8854f0ee43a2c221b4a0a8618f61c7cc23d9c532 Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Tue, 28 Apr 2026 14:17:20 -0700 Subject: [PATCH 3/4] Remove tracing section --- sdk/ai/azure-ai-projects/README.md | 214 +---------------------------- 1 file changed, 4 insertions(+), 210 deletions(-) diff --git a/sdk/ai/azure-ai-projects/README.md b/sdk/ai/azure-ai-projects/README.md index 64e5218f7873..3d97497b9db8 100644 --- a/sdk/ai/azure-ai-projects/README.md +++ b/sdk/ai/azure-ai-projects/README.md @@ -178,219 +178,13 @@ For product guidance, see: For SDK usage examples in this package, see `samples/hosted_agents/`, including CRUD, file upload/download, and skills scenarios. -## Tracing +## Client-side tracing -### Experimental Feature Gate +See [Add client-side tracing to Foundry agents (preview)](https://learn.microsoft.com/azure/foundry/observability/how-to/trace-agent-client-side?tabs=python). -**Important:** GenAI tracing instrumentation is an experimental preview feature. Spans, attributes, and events may be modified in future versions. To use it, you must explicitly opt in by setting the environment variable: +**Important:** GenAI tracing instrumentation is an experimental preview feature. Spans, attributes, and events may be modified in future versions. -```bash -AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true -``` - -This environment variable must be set before calling `AIProjectInstrumentor().instrument()`. If the environment variable is not set or is set to any value other than `true` (case-insensitive), tracing instrumentation will not be enabled and a warning will be logged. - -Only enable this feature after reviewing your requirements and understanding that the tracing behavior may change in future versions. - -### Getting Started with Tracing - -You can add an Application Insights Azure resource to your Microsoft Foundry project. See the Tracing tab in your Microsoft Foundry project. If one was enabled, you can get the Application Insights connection string, configure your AI Projects client, and observe traces in Azure Monitor. Typically, you might want to start tracing before you create a client or Agent. - -For tracing concepts in Microsoft Foundry, see [Trace an agent](https://learn.microsoft.com/azure/foundry/observability/concepts/trace-agent-concept). - -### Installation - -Make sure to install OpenTelemetry and the Azure SDK tracing plugin via - -```bash -pip install "azure-ai-projects>=2.0.0b4" opentelemetry-sdk azure-core-tracing-opentelemetry azure-monitor-opentelemetry -``` - -You will also need an exporter to send telemetry to your observability backend. You can print traces to the console or use a local viewer such as [Aspire Dashboard](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash). - -To connect to Aspire Dashboard or another OpenTelemetry compatible backend, install OTLP exporter: - -```bash -pip install opentelemetry-exporter-otlp -``` - -### How to enable tracing - -**Remember:** Before enabling tracing, ensure you have set the `AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true` environment variable as described in the [Experimental Feature Gate](#experimental-feature-gate) section. - -Here is a code sample that shows how to enable Azure Monitor tracing: - - - -```python -# Enable Azure Monitor tracing -application_insights_connection_string = project_client.telemetry.get_application_insights_connection_string() -configure_azure_monitor(connection_string=application_insights_connection_string) -``` - - - -You may also want to create a span for your scenario: - - - -```python -tracer = trace.get_tracer(__name__) -scenario = os.path.basename(__file__) - -with tracer.start_as_current_span(scenario): -``` - - - -See the full sample in file `\agents\telemetry\sample_agent_basic_with_azure_monitor_tracing.py` in the [Samples][samples] folder. - -**Note:** In order to view the traces in the Microsoft Foundry portal, the agent ID should be passed in as part of the response generation request. - -In addition, you might find it helpful to see the tracing logs in the console. Remember to set `AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true` before running the following code: - - - -```python -# Setup tracing to console -# Requires opentelemetry-sdk -span_exporter = ConsoleSpanExporter() -tracer_provider = TracerProvider() -tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter)) -trace.set_tracer_provider(tracer_provider) -tracer = trace.get_tracer(__name__) - -# Enable instrumentation with content tracing -AIProjectInstrumentor().instrument() -``` - - - -See the full sample in file `\agents\telemetry\sample_agent_basic_with_console_tracing.py` in the [Samples][samples] folder. - -### Enabling trace context propagation - -Trace context propagation allows client-side spans generated by the Projects SDK to be correlated with server-side spans from Azure OpenAI and other Azure services. When enabled, the SDK automatically injects W3C Trace Context headers (`traceparent` and `tracestate`) into HTTP requests made by OpenAI clients obtained via `get_openai_client()`. - -This feature ensures that all operations within a distributed trace share the same trace ID, providing end-to-end visibility across your application and Azure services in your observability backend (such as Azure Monitor). - -Trace context propagation is **enabled by default** when tracing is enabled (for example through `configure_azure_monitor` or the `AIProjectInstrumentor().instrument()` call). To disable it, set the `AZURE_TRACING_GEN_AI_ENABLE_TRACE_CONTEXT_PROPAGATION` environment variable to `false`, or pass `enable_trace_context_propagation=False` to the `AIProjectInstrumentor().instrument()` call. - -**When does the change take effect?** -- Changes to `enable_trace_context_propagation` (whether via `instrument()` or the environment variable) only affect OpenAI clients obtained via `get_openai_client()` **after** the change is applied. Previously acquired clients are unaffected. -- To apply the new setting to all clients, call `AIProjectInstrumentor().instrument(enable_trace_context_propagation=)` before acquiring your OpenAI clients, or re-acquire the clients after making the change. - -**Security and Privacy Considerations:** -- **Trace IDs are sent to external services**: The `traceparent` and `tracestate` headers from your client-side originating spans are injected into requests sent to service. This enables end-to-end distributed tracing, but note that the trace identifier may be shared beyond the initial API call. -- **Enabled by Default**: If you have privacy or compliance requirements that prohibit sharing trace identifiers with services, disable trace context propagation by setting `enable_trace_context_propagation=False` or the environment variable to `false`. - -#### Controlling baggage propagation - -When trace context propagation is enabled, you can separately control whether the baggage header is included. By default, only `traceparent` and `tracestate` headers are propagated. To also include the `baggage` header, set the `AZURE_TRACING_GEN_AI_TRACE_CONTEXT_PROPAGATION_INCLUDE_BAGGAGE` environment variable to `true`: - -If no value is provided for the `enable_baggage_propagation` parameter with the `AIProjectInstrumentor.instrument()` call and the environment variable is not set, the value defaults to `false` and baggage is not included. - -**Note:** The `enable_baggage_propagation` flag is evaluated dynamically on each request, so changes take effect **immediately** for all clients that have the trace context propagation hook registered. However, the hook is only registered on clients acquired via `get_openai_client()` **while trace context propagation was enabled**. Clients acquired when trace context propagation was disabled will never propagate baggage, regardless of the `enable_baggage_propagation` value. - -**Why is baggage propagation separate?** - -The baggage header can contain arbitrary key-value pairs added anywhere in your application's trace context. Unlike trace IDs (which are randomly generated identifiers), baggage may contain: - -- User identifiers or session information -- Authentication tokens or credentials -- Business-specific data or metadata -- Personally identifiable information (PII) - -Baggage is automatically propagated through your entire application's call chain, meaning data added in one part of your application will be included in requests to Azure OpenAI unless explicitly controlled. - -**Important Security Considerations:** - -- **Review Baggage Contents**: Before enabling baggage propagation, audit what data your application (and any third-party libraries) adds to OpenTelemetry baggage. -- **Sensitive Data Risk**: Baggage is sent to Azure OpenAI and may be logged or processed by Microsoft services. Never add sensitive information to baggage when baggage propagation is enabled. -- **Opt-in by Design**: Baggage propagation is disabled by default (even when trace context propagation is enabled) to prevent accidental exposure of sensitive data. -- **Minimal Propagation**: `traceparent` and `tracestate` headers are generally sufficient for distributed tracing. Only enable baggage propagation if your specific observability requirements demand it. - -### Enabling content recording - -Content recording controls whether message contents and tool call related details, such as parameters and return values, are captured with the traces. This data may include sensitive user information. - -To enable content recording, set the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` environment variable to `true`. If the environment variable is not set and no value is provided with the `AIProjectInstrumentor().instrument()` call for the content recording parameter, content recording defaults to `false`. - -**Important:** The environment variable only controls content recording for built-in traces. When you use custom tracing decorators on your own functions, all parameters and return values are always traced. - -### Disabling automatic instrumentation - -The AI Projects client library automatically instruments OpenAI responses and conversations operations through `AiProjectInstrumentation`. You can disable this instrumentation by setting the environment variable `AZURE_TRACING_GEN_AI_INSTRUMENT_RESPONSES_API` to `false`. If the environment variable is not set, the responses and conversations APIs will be instrumented by default. - -### Tracing Binary Data - -Binary data are images and files sent to the service as input messages. When you enable content recording (`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` set to `true`), by default you only trace file IDs and filenames. To enable full binary data tracing, set `AZURE_TRACING_GEN_AI_INCLUDE_BINARY_DATA` to `true`. In this case: - -* **Images**: Image URLs (including data URIs with base64-encoded content) are included -* **Files**: File data is included if sent via the API - -**Important:** Binary data can contain sensitive information and may significantly increase trace size. Some trace backends and tracing implementations may have limitations on the maximum size of trace data that can be sent to and/or supported by the backend. Ensure your observability backend and tracing implementation support the expected trace payload sizes when enabling binary data tracing. - -### How to trace your own functions - -The decorator `trace_function` is provided for tracing your own function calls using OpenTelemetry. By default the function name is used as the name for the span. Alternatively you can provide the name for the span as a parameter to the decorator. - -**Note:** The `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` environment variable does not affect custom function tracing. When you use the `trace_function` decorator, all parameters and return values are always traced by default. - -This decorator handles various data types for function parameters and return values, and records them as attributes in the trace span. The supported data types include: - -* Basic data types: str, int, float, bool -* Collections: list, dict, tuple, set - * Special handling for collections: - * If a collection (list, dict, tuple, set) contains nested collections, the entire collection is converted to a string before being recorded as an attribute. - * Sets and dictionaries are always converted to strings to ensure compatibility with span attributes. - -Object types are omitted, and the corresponding parameter is not traced. - -The parameters are recorded in attributes `code.function.parameter.` and the return value is recorder in attribute `code.function.return.value` - -#### Adding custom attributes to spans - -You can add custom attributes to spans by creating a custom span processor. Here's how to define one: - - - -```python -class CustomAttributeSpanProcessor(SpanProcessor): - def __init__(self) -> None: - pass - - def on_start(self, span: Span, parent_context=None): - # Add this attribute to all spans - span.set_attribute("trace_sample.sessionid", "123") - - # Add another attribute only to create_thread spans - if span.name == "create_thread": - span.set_attribute("trace_sample.create_thread.context", "abc") - - def on_end(self, span: ReadableSpan): - # Clean-up logic can be added here if necessary - pass -``` - - - -Then add the custom span processor to the global tracer provider: - - - -```python -provider = cast(TracerProvider, trace.get_tracer_provider()) -provider.add_span_processor(CustomAttributeSpanProcessor()) -``` - - - -See the full sample in file `\agents\telemetry\sample_agent_basic_with_console_tracing_custom_attributes.py` in the [Samples][samples] folder. - -### Additional resources - -For more information see [Agent tracing overview (preview)](https://learn.microsoft.com/azure/foundry/observability/concepts/trace-agent-concept). +Samples can be found in the sub-folders `agents/telemetry` and `telemetry` in the [Samples][samples] folder. ## Troubleshooting From 6245701ff716be66df01cb3e1ca41ea51dde0b78 Mon Sep 17 00:00:00 2001 From: Darren Cohen <39422044+dargilco@users.noreply.github.com> Date: Tue, 28 Apr 2026 14:32:22 -0700 Subject: [PATCH 4/4] More --- sdk/ai/azure-ai-projects/CHANGELOG.md | 6 +++--- sdk/ai/azure-ai-projects/README.md | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/sdk/ai/azure-ai-projects/CHANGELOG.md b/sdk/ai/azure-ai-projects/CHANGELOG.md index 1d028d1e1014..fdd3ba74147e 100644 --- a/sdk/ai/azure-ai-projects/CHANGELOG.md +++ b/sdk/ai/azure-ai-projects/CHANGELOG.md @@ -4,13 +4,12 @@ ### Features Added -* New `FabricIQPreviewTool` and `FabricIQPreviewToolParameters` model classes, supporting the new `fabric_iq_preview` tool type. -* New `ToolType.FABRIC_IQ_PREVIEW` enum value added to the `ToolType` enum. +* New `FabricIQPreviewTool`. * New read-only property `content_hash` on `CodeConfiguration`, returning the SHA-256 hex digest of the uploaded code zip. ### Breaking Changes -* Agent Endpoint beta operations: Remove required parameters `user_isolation_key` and `chat_isolation_key` from the `HeaderIsolationKeySource` class constructor. +* Agent Endpoint beta operations: Removed required parameters `user_isolation_key` and `chat_isolation_key` from the `HeaderIsolationKeySource` class constructor. ### Bugs Fixed @@ -24,6 +23,7 @@ ### Features Added +* New `WorkIQPreviewTool`. * `get_openai_client()` on `AIProjectClient` now takes an optional input argument `agent_name`. If provided, the returned OpenAI client will use a base URL of Agent endpoint instead of Foundry Project endpoint. As Agent endpoints are a preview feature, you need to set `allow_preview=True` on the `AIProjectClient` constructor. diff --git a/sdk/ai/azure-ai-projects/README.md b/sdk/ai/azure-ai-projects/README.md index 3d97497b9db8..a442f76d91fc 100644 --- a/sdk/ai/azure-ai-projects/README.md +++ b/sdk/ai/azure-ai-projects/README.md @@ -13,6 +13,7 @@ resources in your Microsoft Foundry Project. Use it to: * Browser Automation (Preview) * Code Interpreter * Computer Use (Preview) + * Fabric IQ (Preview) * File Search * Function Tool * Image Generation @@ -23,6 +24,7 @@ resources in your Microsoft Foundry Project. Use it to: * OpenAPI * Web Search * Web Search (Preview) + * Work IQ (Preview) * **Get an OpenAI client** using `.get_openai_client()` method to run Responses, Conversations, Evaluations and Fine-Tuning operations with your Agent. * **Manage memory stores (preview)** for Agent conversations, using `.beta.memory_stores` operations. * **Explore additional evaluation tools (some in preview)** to assess the performance of your generative AI application, using `.evaluation_rules`,