用途：把 LlamaIndex（Python）智能体的运行过程接入 Maple 追踪。目标是每次对话对应一个 Maple Agent Session，每次 agent.run() 或 workflow.run() 对应一个 turn（一条 trace），包含对话记录、每次模型调用的 span 与 token、FunctionTool.acall 工具 span 及结果，失败工具标记为失败，子智能体各自独立泳道。
机制：使用 openinference-instrumentation-llama-index（scope 为 openinference.instrumentation.llama_index）。Maple 从其 span 中读取 session（来自 using_session 的 session.id）、对话记录、token 与工具调用。推荐 TraceConfig(enable_genai_semconv=True)，以同时输出标准 GenAI 属性（gen_ai.*，含 gen_ai.conversation.id）。
前置要求：llama-index-core >= 0.14.19（实测 0.14.25），Python >= 3.10。旧版本插桩器会记录 DependencyConflict 且不生效，需升级。若已存在 LlamaIndexOpenTelemetry 原生插桩，应替换；若已有 LlamaIndexInstrumentor（Phoenix/Langfuse/Arize），保留并复用其 provider，追加配置与 Maple processor；若已有其他 TracerProvider，直接向其添加 Maple processor 链，不要新建第二个 provider。
安装：pip install "llama-index-core>=0.14.25" "openinference-instrumentation-llama-index>=4.5.2" "opentelemetry-sdk>=1.45" "opentelemetry-exporter-otlp-proto-http>=1.45"。
配置：US 端点 https://ingest.maple.dev，EU 端点 https://ingest.eu.maple.dev，请求头 Authorization=Bearer <key>。可用环境变量 OTEL_SERVICE_NAME、OTEL_RESOURCE_ATTRIBUTES、OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_HEADERS、OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf。若在代码中传 OTLPSpanExporter(endpoint=...)，必须自行以 /v1/traces 结尾。
使用方式：创建 tracing.py，定义 LlamaIndexForMaple（SpanProcessor）置于 exporter 之前，用于合并重复模型 span、标记工作流步骤、跳过 _prepare_chat_with_tools 与 WaitingForEvent 的伪失败；再构建 TracerProvider，添加 LlamaIndexForMaple(BatchSpanProcessor(OTLPSpanExporter()))，调用 trace.set_tracer_provider(provider)，并执行 LlamaIndexInstrumentor().instrument(tracer_provider=provider, config=TraceConfig(enable_genai_semconv=True))。必须在入口最先导入 tracing，且 instrument() 早于首次 agent.run()。exporter 必须经由 LlamaIndexForMaple 添加，否则模型调用会被重复计数 2-3 次、工具调用 3 次。
会话 id：LlamaIndex 不会自动设置对话 id，需用 using_session(<应用对话 id>) 包裹每次 agent.run()/workflow.run() 调用，并在同一 with 中用 instrument_tags({"gen_ai.agent.name": agent.name}) 标注智能体名。id 需按对话稳定且全局唯一，不可用 uuid4() 每请求生成或常量。每个对话一个 Context。
内容与工具：默认采集 gen_ai.input.messages、gen_ai.output.messages 与工具结果；如需关闭可用 hide_inputs/hide_outputs 或 OPENINFERENCE_HIDE_*。每个智能体需命名并加 instrument_tags 才有泳道。工具抛异常会标记 ERROR；返回 "Error: ..." 的不会。HITL 的 ctx.wait_for_event 首次挂起 span 由 processor 丢弃。已知限制：工具 span 无 gen_ai.tool.call.id；成本不记录，会话显示 unpriced；流式模型 span 时长不代表真实延迟。
刷新：脚本/CLI 在 finally 中调用 provider.shutdown()；Serverless、Celery/RQ、notebook 每次运行后 provider.force_flush()；FastAPI 等长驻服务无需额外处理。
验证：运行一次真实对话（同一 id 至少 2 条消息、至少一次工具调用、如有失败工具与子智能体则一并覆盖），在 Maple 的 Agent Sessions 中按 service name 过滤，确认每对话一个 session、每 run() 一个 turn、框架显示 LlamaIndex、对话记录完整、模型与工具调用计数正确、token 存在、失败工具标记失败、子智能体独立泳道、成本显示 unpriced，且属性中不含 API key。