Trace LlamaIndex calls with Future AGI

Send LlamaIndex spans to Observe with traceAI-llamaindex. This guide starts with a text chat request; retrieval and agent spans depend on the LlamaIndex components your application runs.

Install

Use Python 3.10–3.13. The traceAI-llamaindex package requires llama-index-core>=0.10.43; the OpenAI integration supplies the model client used below.

pip install 'traceAI-llamaindex==0.1.10' 'llama-index-core>=0.10.43' llama-index-llms-openai

Set credentials and capture preferences

Set these in your shell, then run the Python blocks below in one script. Choose a chat model supported by your installed LlamaIndex OpenAI integration and available to your OpenAI account.

export FI_API_KEY="your-futureagi-api-key"
export FI_SECRET_KEY="your-futureagi-secret-key"
export OPENAI_API_KEY="your-openai-api-key"
export OPENAI_MODEL="your-available-openai-chat-model"

Tracing can send prompts, responses, tool data and retrieved text to Future AGI. To hide input and output values and messages, set FI_HIDE_INPUTS=true and FI_HIDE_OUTPUTS=true before instrumentation. See mask span attributes. These switches are not a general scrubber for custom attributes or exception text; keep secrets out of retrieved data and error messages. Use the default event/span handler below; the legacy callback handler does not support TraceConfig masking.

Register the trace provider

from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType

trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="llamaindex_project",
)

Instrument LlamaIndex

Initialize instrumentation before running LlamaIndex calls.

from traceai_llamaindex import LlamaIndexInstrumentor

LlamaIndexInstrumentor().instrument(tracer_provider=trace_provider)

Run a chat request

This uses LlamaIndex’s OpenAI chat interface.

import os
from llama_index.core.llms import ChatMessage
from llama_index.llms.openai import OpenAI

try:
    llm = OpenAI(model=os.environ["OPENAI_MODEL"])
    response = llm.chat([
        ChatMessage(role="user", content="Suggest a name for a community garden."),
    ])
    print(response.message.content)
finally:
    trace_provider.shutdown()

shutdown() sends pending spans before this short-lived process exits.

View the trace

Open Observe in Future AGI and select llamaindex_project to inspect the chat span and its available model usage. The example does not invoke retrieval or tools; those appear only when your application uses them.