Add LlamaIndex agent and workflow instrumentation

[eternalcuriouslearner]

Adds invoke_workflow, invoke_agent, and execute_tool spans for LlamaIndex AgentWorkflow, FunctionAgent, and ReActAgent executions, with conformance and composition coverage. Provider model calls remain owned by the corresponding provider instrumentation.

[Copilot]

🟡 Changes recommended

A regression risk was found in tool-span deduplication that can reintroduce duplicate execute_tool spans when callbacks cross threads/tasks.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR extends the opentelemetry-instrumentation-genai-llama-index package to instrument LlamaIndex’s AgentWorkflow executions in addition to existing agent/tool tracing, and updates tests/docs/changelog accordingly while keeping provider model-call spans owned by provider instrumentations.

Changes:

• Add invoke_workflow spans for AgentWorkflow.run and ensure workflow-member invoke_agent and execute_tool spans form a correct nesting hierarchy.
• Add conformance coverage for workflow spans and expand composition tests to validate nesting with provider (OpenAI) instrumentation.
• Add targeted regression tests for workflow handoff/tool-loop behavior and context/locking edge cases in the span handler.

File summaries

File	Description
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/test_conformance.py	Runs both agent and workflow conformance scenarios.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/test_composition.py	Validates workflow/agent/tool span nesting alongside provider inference spans; adds standalone agent nesting coverage.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/test_agent.py	Adds extensive workflow span hierarchy, handoff/tool-loop lifecycle, and context/locking regression tests.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/conformance/workflow.py	New workflow conformance scenario emitting invoke_workflow, invoke_agent, and execute_tool.
instrumentation/opentelemetry-instrumentation-genai-llama-index/src/opentelemetry/instrumentation/genai/llama_index/_handler.py	Implements AgentWorkflow span creation plus member-agent lifecycle/tool nesting logic.
instrumentation/opentelemetry-instrumentation-genai-llama-index/README.rst	Documents new workflow tracing behavior.
instrumentation/opentelemetry-instrumentation-genai-llama-index/.changelog/495.fixed	Changelog fragment for workflow tool-loop/handoff parenting behavior.
instrumentation/opentelemetry-instrumentation-genai-llama-index/.changelog/495.added	Changelog fragment for adding AgentWorkflow tracing.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Early-stopping output handling is incorrect, and workflow streaming and metric coverage remain incomplete.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 3
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

Failed handoffs can prematurely close member-agent spans as successful, producing incorrect telemetry.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/test_agent.py:1726

• This adds a type-check suppression instead of expressing the test double's compatible mapping type. Please type _RecordingSpans/values() explicitly and remove the new type: ignore; repository guidance prohibits adding these suppressions because they hide future type regressions.

• Files reviewed: 8/8 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🟡 Changes recommended

The latest supported LlamaIndex lifecycle bypasses the new workflow branch, and mixed handoff failures can produce an incorrect successful agent span.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

instrumentation/opentelemetry-instrumentation-genai-llama-index/src/opentelemetry/instrumentation/genai/llama_index/_handler.py:788

• This dispatch branch is not reached by the currently resolved LlamaIndex stack. The lock resolves llama-index-core 0.14.23 with llama-index-workflows 2.22.2; that workflow implementation's Workflow.run() is no longer dispatcher-wrapped and returns an awaitable WorkflowHandler, while only step functions emit dispatcher spans. Consequently no workflow adapter is inserted into open_spans, and run_agent_step later returns at line 844 because its parent cannot be found, so neither the new workflow nor member-agent telemetry is emitted for the supported latest environment. Hook the workflow runtime/handler lifecycle (without eagerly awaiting or changing the returned handler) or otherwise add a version-compatible entry point.

• Files reviewed: 8/8 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

🔵 Needs a closer look

The instrumentation directly manages invocation span contexts instead of using a supported opentelemetry-util-genai API.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

instrumentation/opentelemetry-instrumentation-genai-llama-index/src/opentelemetry/instrumentation/genai/llama_index/_handler.py:715

• This manually reads the invocation's span and owns its context lifecycle. Instrumentations are required to treat opentelemetry-util-genai invocations as the telemetry boundary rather than attach/detach their spans directly; otherwise this code is coupled to invocation internals and cross-task context behavior. Please add a supported activation/reactivation API to the util and use it here.

This issue also appears on line 951 of the same file.

instrumentation/opentelemetry-instrumentation-genai-llama-index/src/opentelemetry/instrumentation/genai/llama_index/_handler.py:954

• Tool parenting also bypasses opentelemetry-util-genai by attaching active_invocation.span directly. Move this parent-context activation behind the same public util API used for member-agent reactivation so the instrumentation does not own raw span/context tokens.

            agent_context_token = (
                attach(set_span_in_context(active_invocation.span))
                if active_invocation is not None
                else None

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[lmolkova]

A couple of nits, lgtm otherwise!

[lmolkova]

#672 to fix the CI

[opentelemetry-pr-dashboard]

Pull request dashboard status

Merged · refreshed 2026-09-11 00:21 UTC

Status above doesn't look right?

• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.