feat: Add LlamaIndex agent and tool instrumentation

[eternalcuriouslearner]

Adds invoke_agent spans for LlamaIndex FunctionAgent and ReActAgent runs and execute_tool spans for tool calls, while deduplicating nested FunctionTool.call/acall callbacks. Provider inference remains delegated to the provider SDK instrumentation.

Includes VCR-backed tests, provider composition, conformance scenarios, examples, and documentation.

Known gap: AgentWorkflow is intentionally handled by the next PR in this stack.

[Copilot]

Pull request overview

This PR extends the opentelemetry-instrumentation-genai-llama-index package from a scaffold into a working instrumentation that maps LlamaIndex agent/tool lifecycle events into GenAI semantic-convention spans via opentelemetry-util-genai, and wires the package into the repo’s conformance test matrix.

Changes:

• Add a LlamaIndex dispatcher BaseSpanHandler bridge that emits invoke_agent spans for agent runs and execute_tool spans for tool executions, while delegating provider inference spans to provider SDK instrumentations.
• Add VCR-backed unit/composition tests plus conformance scenario + runner, and wire a new llama-index conformance tox env.
• Add documentation and runnable manual/zero-code examples (including completion hook documentation/example).

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tox.ini	Adds llama-index conformance env wiring (deps + commands).
instrumentation/opentelemetry-instrumentation-genai-llama-index/src/opentelemetry/instrumentation/genai/llama_index/init.py	Registers a LlamaIndex span handler via the dispatcher when instrumented.
instrumentation/opentelemetry-instrumentation-genai-llama-index/src/opentelemetry/instrumentation/genai/llama_index/_handler.py	Implements the dispatcher span handler bridging LlamaIndex agent/tool events to util-genai invocations.
instrumentation/opentelemetry-instrumentation-genai-llama-index/pyproject.toml	Raises opentelemetry-util-genai lower bound to match new functionality usage.
instrumentation/opentelemetry-instrumentation-genai-llama-index/README.rst	Documents emitted spans and completion-hook configuration.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/conftest.py	Adds shared fixtures/plugins + VCR scrubbing and helper fixtures for provider composition.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/test_instrumentor.py	Verifies dispatcher span handler registration/unregistration.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/test_agent.py	Adds extensive unit tests for agent/tool spans, error handling, streaming, and content capture.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/test_composition.py	Validates cross-package span composition with provider instrumentation (OpenAI).
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/test_conformance.py	Adds conformance test entrypoint invoking shared conformance runner.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/conformance/init.py	Marks conformance package for scenario imports.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/conformance/agent.py	Defines conformance scenario emitting invoke_agent/execute_tool telemetry (and metrics expectation).
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/requirements.oldest.txt	Pins additional test deps for oldest matrix (incl. temporary util-genai editable).
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/requirements.latest.txt	Adds latest-matrix deps for provider composition (incl. editable OpenAI instrumentation).
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/cassettes/inference.yaml	VCR cassette for provider inference call.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/cassettes/rate_limit.yaml	VCR cassette for provider rate-limit error (non-streaming).
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/cassettes/rate_limit_streaming.yaml	VCR cassette for provider rate-limit error (streaming).
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/cassettes/react_malformed.yaml	AI-generated placeholder cassette for malformed ReAct flow.
instrumentation/opentelemetry-instrumentation-genai-llama-index/tests/cassettes/tool_error_recovery.yaml	VCR cassette covering tool error recovery flow.
instrumentation/opentelemetry-instrumentation-genai-llama-index/examples/manual/requirements.txt	Manual example dependency set.
instrumentation/opentelemetry-instrumentation-genai-llama-index/examples/manual/README.rst	Manual example instructions + completion hook notes.
instrumentation/opentelemetry-instrumentation-genai-llama-index/examples/manual/agent.py	Manual SDK setup example that instruments both LlamaIndex and OpenAI.
instrumentation/opentelemetry-instrumentation-genai-llama-index/examples/manual/custom_hook.py	Demonstrates programmatic completion hook usage.
instrumentation/opentelemetry-instrumentation-genai-llama-index/examples/zero-code/requirements.txt	Zero-code example dependency set (opentelemetry-instrument CLI).
instrumentation/opentelemetry-instrumentation-genai-llama-index/examples/zero-code/README.rst	Zero-code example instructions.
instrumentation/opentelemetry-instrumentation-genai-llama-index/examples/zero-code/agent.py	Minimal LlamaIndex agent app for auto-instrumentation demo.
instrumentation/opentelemetry-instrumentation-genai-llama-index/.changelog/494.added	Towncrier fragment describing the added instrumentation.

Suppressed comments (1)

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

• Same issue as above: start_event.get(..., default=None) will raise on dict-like events because default is not a supported keyword parameter. Prefer the positional default argument.

    user_message = start_event.get("user_msg", default=None)

---

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

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on the author · refreshed 2026-09-01 12:25 UTC

Respond to 1 review item (e.g. link a commit, explain why not, ask a follow-up):

• Inline threads: 1

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Should this be with reviewers? Comment /dashboard route:reviewers to route it to them.
• Anything wrong — including the routing? Report it with what you expected; it helps us improve the dashboard.