Install
llama-index-core>=0.12.0.
Use
llamaindex-agent unless you say otherwise. To name the
agent for the whole process, install by hand instead of through the flag:
instrument() once. LlamaIndex’s dispatcher takes span handlers
additively and never gives one back, so a second call double-traces every query
from then on — one query, two traces.
Several agents in one process
Because there is one handler for the whole process, the install-time name can’t be the answer for a service that answers for more than one agent — a multi-tenant API, or a router that picks between a support index and a billing index. Name the run instead:asyncio task and eight in-flight requests produce eight
correctly-labelled traces. Open it inside the worker, not around the dispatch —
a ThreadPoolExecutor worker starts from a fresh context.
instrument() was given.
LlamaIndex’s own
instrument_tags({"agent_name": "..."}) names a run the same
way, and wins over agent_run when both are set. Use whichever you already
reach for; agent_run is the one that works identically across every
DecimalAI rail.What gets captured
- Query engine, retriever, and synthesizer spans
- Embedding calls with token counts
- LLM calls with the full resolved prompt
- Auto-detected manifest from the query engine config, per agent
Caveats
- Auto-detected manifest captures tool names only — not full schemas. If you need schema-aware manifests, register them explicitly with
register_manifest(). - The floor is
llama-index-core>=0.12.0— earlier releases either lack the instrumentation dispatcher entirely (pre-0.10.20) or drive span handlers with an incompatible early signature, so spans never reach the handler.
What’s next
Tracing guide
Conceptual model: what a span is and how trees are built.
Manifests
Register a manifest explicitly to capture tool schemas.