docs(samples): add Python samples for integrating with existing OpenTelemetry by juliomenendez · Pull Request #288 · microsoft/Agent365-Samples

juliomenendez · 2026-04-28T23:41:11Z

Summary

Two new lean Python samples under python/ that show how to add the Microsoft Agent 365 SDK to an app that already has OpenTelemetry initialized — a scenario the existing samples don't cover. Each sample is a single-file CLI that runs a tool-calling agent end-to-end so users can see Agent 365 spans flowing alongside their existing telemetry.

python/observability-with-azure-monitor/ — pairs Azure Monitor / Application Insights (azure-monitor-opentelemetry) with the OpenAI Agents SDK and auto-instrumentation via microsoft-agents-a365-observability-extensions-openai.
python/observability-with-otlp/ — pairs a manual OpenTelemetry SDK setup (defaults to ConsoleSpanExporter for zero external setup; OTLPSpanExporter swap-in shown as a commented block) with a raw openai client and manual instrumentation using InvokeAgentScope / InferenceScope / ExecuteToolScope.

The two samples deliberately cover different cells of the (backend × instrumentation-style) matrix so a customer can find their case quickly.

What's intentionally NOT in these samples

No M365 Agents SDK host / Playground / agent registration — covered by python/openai/sample-agent. These samples are laser-focused on the OTel-init + A365-configure() integration pattern.
No real Azure auth / token caching — _stub_token_resolver returns a placeholder so users can run the sample with just an OpenAI key.
No third sample for the auto-on-OTLP or manual-on-AzureMonitor cells — the integration guide explains those axes are independent and points readers at the matrix.

Companion PR

A companion PR on microsoft/Agent365-python adds the integration guide that both sample READMEs link to (docs/integrating-with-existing-opentelemetry.md). The samples reference the guide via a main-pointing GitHub URL; that link resolves once the docs PR merges.

Test plan

Verify each sample's main.py parses
Run python -m venv .venv && pip install -e . in python/observability-with-azure-monitor/ with a real App Insights connection string + OpenAI key, run python main.py, confirm invoke_agent, Chat <model>, execute_tool spans appear in App Insights Transaction search
Run the same in python/observability-with-otlp/ with just an OpenAI key, confirm the four-span tree (invoke_agent WeatherAgent → two Chat <model> + one execute_tool get_weather) prints to stdout via ConsoleSpanExporter
Verify both READMEs render correctly on GitHub

🤖 Generated with Claude Code

Lean greenfield CLI sample showing how to add the Agent 365 SDK to an app that already has Azure Monitor OpenTelemetry initialized. Uses the OpenAI Agents SDK with auto-instrumentation via microsoft-agents-a365-observability-extensions-openai. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Said "four numbered sections" while listing five (Step 1, 2, 2b, 3, 4). Reword to acknowledge Step 2b as a sub-step. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…sample The previous wording told users to filter Transaction search by "Operation name invoke_agent" — but invoke_agent / inference / execute_tool are values of the gen_ai.operation.name *attribute*, not the App Insights operation name. Reword to point at the right field. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Lean greenfield CLI sample showing how to add the Agent 365 SDK to an app that already has the OpenTelemetry SDK initialized, demonstrating manual instrumentation with InvokeAgentScope / InferenceScope / ExecuteToolScope around a raw OpenAI client (no agent framework). Defaults to ConsoleSpanExporter for zero-setup; a commented OTLPSpanExporter block shows the swap-in for real backends. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

InferenceScope uses InferenceOperationType.value (e.g. "Chat") for both the gen_ai.operation.name attribute and the span name; "inference" is not what users will actually see in their backend. Update both sample READMEs to reflect the real SDK behavior and clarify where the value comes from. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

github-actions · 2026-04-28T23:41:23Z

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

The following issues were found:

✅ 0 vulnerable package(s)
✅ 0 package(s) with incompatible licenses
✅ 0 package(s) with invalid SPDX license definitions
⚠️ 19 package(s) with unknown licenses.

See the Details below.

License Issues

python/observability-with-azure-monitor/pyproject.toml

Package	Version	License	Issue Type
azure-monitor-opentelemetry	>= 1.6.0	Null	Unknown License
microsoft-agents-a365-observability-core		Null	Unknown License
microsoft-agents-a365-observability-extensions-openai		Null	Unknown License
openai-agents	>= 0.2.6	Null	Unknown License
python-dotenv	>= 1.0.0	Null	Unknown License

python/observability-with-langgraph/pyproject.toml

Package	Version	License	Issue Type
langchain-core	>= 0.3.0	Null	Unknown License
langchain-openai	>= 0.3.0	Null	Unknown License
langgraph	>= 0.3.0	Null	Unknown License
microsoft-agents-a365-observability-core		Null	Unknown License
microsoft-agents-a365-observability-extensions-langchain		Null	Unknown License
opentelemetry-exporter-otlp-proto-grpc	>= 1.27.0	Null	Unknown License
opentelemetry-sdk	>= 1.27.0	Null	Unknown License
python-dotenv	>= 1.0.0	Null	Unknown License
wrapt	< 2	Null	Unknown License

python/observability-with-otlp/pyproject.toml

Package	Version	License	Issue Type
microsoft-agents-a365-observability-core		Null	Unknown License
openai	>= 1.40.0	Null	Unknown License
opentelemetry-exporter-otlp-proto-http	>= 1.27.0	Null	Unknown License
opentelemetry-sdk	>= 1.27.0	Null	Unknown License
python-dotenv	>= 1.0.0	Null	Unknown License

Denied Licenses:
GPL-3.0-only, AGPL-3.0-only

OpenSSF Scorecard

Scorecard details

Package	Version	Score	Details
pip/azure-monitor-opentelemetry	>= 1.6.0	Unknown	Unknown
pip/microsoft-agents-a365-observability-core		Unknown	Unknown
pip/microsoft-agents-a365-observability-extensions-openai		Unknown	Unknown
pip/openai-agents	>= 0.2.6	Unknown	Unknown
pip/python-dotenv	>= 1.0.0	Unknown	Unknown
pip/langchain-core	>= 0.3.0	Unknown	Unknown
pip/langchain-openai	>= 0.3.0	Unknown	Unknown
pip/langgraph	>= 0.3.0	Unknown	Unknown
pip/microsoft-agents-a365-observability-core		Unknown	Unknown
pip/microsoft-agents-a365-observability-extensions-langchain		Unknown	Unknown
pip/opentelemetry-exporter-otlp-proto-grpc	>= 1.27.0	Unknown	Unknown
pip/opentelemetry-sdk	>= 1.27.0	Unknown	Unknown
pip/python-dotenv	>= 1.0.0	Unknown	Unknown
pip/wrapt	< 2	Unknown	Unknown
pip/microsoft-agents-a365-observability-core		Unknown	Unknown
pip/openai	>= 1.40.0	Unknown	Unknown
pip/opentelemetry-exporter-otlp-proto-http	>= 1.27.0	Unknown	Unknown
pip/opentelemetry-sdk	>= 1.27.0	Unknown	Unknown
pip/python-dotenv	>= 1.0.0	Unknown	Unknown

Scanned Files

python/observability-with-azure-monitor/pyproject.toml
python/observability-with-langgraph/pyproject.toml
python/observability-with-otlp/pyproject.toml

Copilot

Pull request overview

Adds two lean Python CLI samples under python/ demonstrating how to integrate the Microsoft Agent 365 Python SDK into applications that already have OpenTelemetry initialized, covering both Azure Monitor and vendor-neutral OTLP setups (auto vs manual instrumentation).

Changes:

Added observability-with-azure-monitor sample using azure-monitor-opentelemetry + OpenAI Agents SDK auto-instrumentation.
Added observability-with-otlp sample using a manual OTel SDK setup + manual Agent 365 scope instrumentation.
Included per-sample pyproject.toml, README, .env.template, and .gitignore.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
python/observability-with-otlp/pyproject.toml	Defines a minimal, installable sample with OpenAI + OTel deps.
python/observability-with-otlp/main.py	Manual OTel init + manual Agent 365 scopes around OpenAI tool-calling loop.
python/observability-with-otlp/README.md	Documents how to run locally with ConsoleSpanExporter and swap to OTLP.
python/observability-with-otlp/.gitignore	Ignores env/venv/build artifacts for the sample.
python/observability-with-otlp/.env.template	Provides environment variable template for local runs.
python/observability-with-azure-monitor/pyproject.toml	Defines a minimal, installable sample with Azure Monitor + OpenAI Agents deps.
python/observability-with-azure-monitor/main.py	Azure Monitor OTel init + Agent 365 configure + OpenAI Agents instrumentor.
python/observability-with-azure-monitor/README.md	Documents setup/run and what spans to look for in App Insights.
python/observability-with-azure-monitor/.gitignore	Ignores env/venv/build artifacts for the sample.
python/observability-with-azure-monitor/.env.template	Provides environment variable template for local runs.

- Replace OPENAI_API_KEY=sk-... placeholder with a non-secret form so secret scanners don't false-positive. - Capture and check configure() return status in both samples; exit cleanly with a clear message when configuration fails. - Validate APPLICATIONINSIGHTS_CONNECTION_STRING up front in the AM sample with a friendly error pointing at .env.template. - Guard tool_calls indexing in the OTLP sample so the manual-loop doesn't crash when the model answers without calling the tool. - Add "Demonstrates" and "Troubleshooting" sections to both sample READMEs to make setup and failure-mode diagnosis easier. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The Agent 365 SDK gates span creation behind ENABLE_OBSERVABILITY (or ENABLE_A365_OBSERVABILITY) env var — without one set to a truthy value, scopes silently produce zero spans. Both .env.template files now include ENABLE_OBSERVABILITY=true, and the READMEs surface the requirement in Setup plus a Troubleshooting bullet at the top of each sample's troubleshooting list (it's the most common silent-failure mode). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Auto-instrumentation via the openai extension produces gen_ai.operation .name="chat" (lowercase) per the OTel GenAI semantic conventions, not "Chat" as previously documented. The OTLP sample's manual instrumentation correctly produces "Chat" (the InferenceOperationType.CHAT.value); the AM sample uses auto-instrumentation and emits the spec-conformant lowercase form. Fixing the AM README to reflect what users will actually see in App Insights. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Mirrors Google Cloud's LangGraph + OpenTelemetry reference sample, adapted for the Agent 365 SDK: existing OTel TracerProvider first, then `configure()`, then `CustomLangChainInstrumentor` for auto-instrumented LLM/tool spans, with `InvokeAgentScope` wrapping `agent.invoke(...)` for the top-level span. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

alexlu4250

Approving with one concern (see my comment)

juliomenendez and others added 5 commits April 28, 2026 16:44

docs(samples): fix section-count phrasing in azure-monitor README

082edd4

Said "four numbered sections" while listing five (Step 1, 2, 2b, 3, 4). Reword to acknowledge Step 2b as a sub-step. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Copilot AI review requested due to automatic review settings April 28, 2026 23:41

juliomenendez requested a review from a team as a code owner April 28, 2026 23:41

Copilot started reviewing on behalf of juliomenendez April 28, 2026 23:41 View session

Copilot AI reviewed Apr 28, 2026

View reviewed changes

juliomenendez and others added 3 commits April 29, 2026 07:18

juliomenendez mentioned this pull request Apr 29, 2026

InferenceOperationType.value casing inconsistent with OTel GenAI semantic conventions microsoft/Agent365-python#249

Open

juliomenendez enabled auto-merge (squash) April 29, 2026 18:21

fpfp100 approved these changes Apr 29, 2026

View reviewed changes

alexlu4250 reviewed Apr 29, 2026

View reviewed changes

Comment thread python/observability-with-azure-monitor/pyproject.toml

alexlu4250 approved these changes Apr 29, 2026

View reviewed changes

gwharris7 approved these changes Apr 29, 2026

View reviewed changes

Merge branch 'main' into samples/observability-existing-otel

15ede07

juliomenendez merged commit 7eee7fa into main Apr 29, 2026
34 checks passed

juliomenendez deleted the samples/observability-existing-otel branch April 29, 2026 22:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(samples): add Python samples for integrating with existing OpenTelemetry#288

docs(samples): add Python samples for integrating with existing OpenTelemetry#288
juliomenendez merged 10 commits intomainfrom
samples/observability-existing-otel

juliomenendez commented Apr 28, 2026

Uh oh!

github-actions Bot commented Apr 28, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alexlu4250 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

juliomenendez commented Apr 28, 2026

Summary

What's intentionally NOT in these samples

Companion PR

Test plan

Uh oh!

github-actions Bot commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Dependency Review

License Issues

python/observability-with-azure-monitor/pyproject.toml

python/observability-with-langgraph/pyproject.toml

python/observability-with-otlp/pyproject.toml

OpenSSF Scorecard

Scanned Files

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

alexlu4250 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions Bot commented Apr 28, 2026 •

edited

Loading