Skip to content

Commit 2f38e19

Browse files
CopilotCopilot
andcommitted
docs: add GeminiChatClient to MCP scope note and add learn-site observability doc (microsoft#5547)
- Add GeminiChatClient.get_mcp_tool(...) to the hosted/provider-managed list in the MCP trace propagation scope note; Gemini's get_mcp_tool() returns a types.Tool with an McpServer entry executed by the Gemini service runtime, so it belongs alongside FoundryChatClient, OpenAIChatClient, and AnthropicClient in that list. - Create docs/features/observability/README.md as the learn-site documentation surface for observability, covering telemetry setup and MCP trace propagation with the same scope note (including GeminiChatClient) so that both doc surfaces are consistent. Co-authored-by: Copilot <[email protected]>
1 parent d385735 commit 2f38e19

2 files changed

Lines changed: 40 additions & 1 deletion

File tree

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Observability
2+
3+
## Overview
4+
5+
Agent Framework emits comprehensive OpenTelemetry **traces**, **logs**, and **metrics** for every agent run, chat-client call, and tool execution. These signals follow the [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/) and integrate with any OpenTelemetry-compatible backend — Application Insights, Aspire Dashboard, Jaeger, Grafana, etc.
6+
7+
## Enabling telemetry
8+
9+
Call `configure_otel_providers()` once at application startup:
10+
11+
```python
12+
from agent_framework.observability import configure_otel_providers
13+
14+
configure_otel_providers()
15+
```
16+
17+
The function reads standard OpenTelemetry environment variables (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_SERVICE_NAME`, etc.) to configure exporters automatically. Pass custom exporters for more control:
18+
19+
```python
20+
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
21+
from agent_framework.observability import configure_otel_providers
22+
23+
configure_otel_providers(exporters=[OTLPSpanExporter(endpoint="http://localhost:4317")])
24+
```
25+
26+
For Azure Foundry projects, use `client.configure_azure_monitor()` which retrieves the Application Insights connection string from the project automatically.
27+
28+
> [!NOTE]
29+
> If you configure providers manually (e.g., Azure Monitor SDK), call `enable_instrumentation()` instead of `configure_otel_providers()` to activate the Agent Framework telemetry code paths without replacing your existing exporters.
30+
31+
## MCP trace propagation
32+
33+
Whenever there is an active OpenTelemetry span context, Agent Framework automatically propagates trace context to MCP servers via the `params._meta` field of `tools/call` requests. It uses the globally-configured OpenTelemetry propagator(s) (W3C Trace Context by default, producing `traceparent` and `tracestate`), so custom propagators (B3, Jaeger, etc.) are also supported. This enables distributed tracing across agent-to-MCP-server boundaries, compliant with the [MCP `_meta` specification](https://modelcontextprotocol.io/specification/2025-11-25/basic#_meta).
34+
35+
**Scope:** automatic `_meta` injection applies only to MCP sessions that the agent process itself opens — `MCPStreamableHTTPTool`, `MCPStdioTool`, and `MCPWebsocketTool` (or any other client-opened `MCPTool` subclass). It does **not** apply to hosted/provider-managed MCP tool configurations such as `FoundryChatClient.get_mcp_tool(...)`, `OpenAIChatClient.get_mcp_tool(...)`, `AnthropicClient.get_mcp_tool(...)`, `GeminiChatClient.get_mcp_tool(...)`, or toolbox-fetched tools (for example, `toolbox = await client.get_toolbox(...)`, then passing `toolbox.tools` into `Agent(tools=...)`), because in those cases the `tools/call` message is issued by the provider service runtime rather than by the agent process. As a result, the framework has no opportunity to inject trace context into those requests, and propagating `traceparent`/`tracestate` across that hosted-service boundary is the responsibility of the service runtime, not Agent Framework. If end-to-end distributed tracing to the downstream MCP server is required, use a client-opened MCP transport instead of a hosted connector.
36+
37+
## Samples
38+
39+
See [python/samples/02-agents/observability](../../../python/samples/02-agents/observability/) for runnable examples covering all configuration patterns.

‎python/samples/02-agents/observability/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Next to what happens in the code when you run, we also make setting up observabi
2626

2727
Whenever there is an active OpenTelemetry span context, Agent Framework automatically propagates trace context to MCP servers via the `params._meta` field of `tools/call` requests. It uses the globally-configured OpenTelemetry propagator(s) (W3C Trace Context by default, producing `traceparent` and `tracestate`), so custom propagators (B3, Jaeger, etc.) are also supported. This enables distributed tracing across agent-to-MCP-server boundaries, compliant with the [MCP `_meta` specification](https://modelcontextprotocol.io/specification/2025-11-25/basic#_meta).
2828

29-
**Scope:** automatic `_meta` injection applies only to MCP sessions that the agent process itself opens — `MCPStreamableHTTPTool`, `MCPStdioTool`, and `MCPWebsocketTool` (or any other client-opened `MCPTool` subclass). It does **not** apply to hosted/provider-managed MCP tool configurations such as `FoundryChatClient.get_mcp_tool(...)`, `OpenAIChatClient.get_mcp_tool(...)`, `AnthropicClient.get_mcp_tool(...)`, or toolbox-fetched tools (for example, `toolbox = await client.get_toolbox(...)`, then passing `toolbox.tools` into `Agent(tools=...)`), because in those cases the `tools/call` message is issued by the provider service runtime rather than by the agent process. As a result, the framework has no opportunity to inject trace context into those requests, and propagating `traceparent`/`tracestate` across that hosted-service boundary is the responsibility of the service runtime, not Agent Framework. If end-to-end distributed tracing to the downstream MCP server is required, use a client-opened MCP transport instead of a hosted connector.
29+
**Scope:** automatic `_meta` injection applies only to MCP sessions that the agent process itself opens — `MCPStreamableHTTPTool`, `MCPStdioTool`, and `MCPWebsocketTool` (or any other client-opened `MCPTool` subclass). It does **not** apply to hosted/provider-managed MCP tool configurations such as `FoundryChatClient.get_mcp_tool(...)`, `OpenAIChatClient.get_mcp_tool(...)`, `AnthropicClient.get_mcp_tool(...)`, `GeminiChatClient.get_mcp_tool(...)`, or toolbox-fetched tools (for example, `toolbox = await client.get_toolbox(...)`, then passing `toolbox.tools` into `Agent(tools=...)`), because in those cases the `tools/call` message is issued by the provider service runtime rather than by the agent process. As a result, the framework has no opportunity to inject trace context into those requests, and propagating `traceparent`/`tracestate` across that hosted-service boundary is the responsibility of the service runtime, not Agent Framework. If end-to-end distributed tracing to the downstream MCP server is required, use a client-opened MCP transport instead of a hosted connector.
3030

3131
### Five patterns for configuring observability
3232

0 commit comments

Comments
 (0)