> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PROMPT

# Arize AX Tracing — Agent Setup Prompt

You are helping a developer add **Arize AX tracing** to their application.
Follow the two-phase approach below: first analyze, then implement.

## Core principles

* **Prefer inspection over mutation** — understand the codebase before changing it
* **Do not change business logic** — tracing is purely additive
* **Use auto-instrumentation where available** — add manual spans only for custom logic not covered by integrations
* **Never hand-roll OpenTelemetry** — always configure the exporter via `arize-otel` (Python), `arize-otel-go` (Go), or the documented OpenInference setup (TS/Java). Do not construct a raw `TracerProvider` + OTLP exporter from scratch when a helper exists; that is the most common setup mistake.
* **Pin packages correctly** — `arize-otel` (the Python tracing helper) is a **separate package on its own `0.x` line**; it is *not* the `arize` platform SDK (which is `7.x`/`8.x`). Install `arize-otel` unpinned (`pip install arize-otel`) and **never** pin it to a `7.x`/`8.x` version — those releases do not exist and the install will fail. The two are different packages with independent version lines. The OpenInference instrumentors (`openinference-instrumentation-*` / `@arizeai/openinference-*`) are also pre-`1.0`: install them unpinned too and never invent a version constraint (e.g. `openinference-instrumentation-langchain>=0.2.0`) — a guessed pin will fail to resolve and abort the install.
* **Follow existing code style** and project conventions
* **Keep output concise and production-focused** — do not generate extra documentation or summary files

### Reference links

* **Arize AX Docs:** [https://arize.com/docs/ax](https://arize.com/docs/ax)
* **Full integration list:** [https://arize.com/docs/ax/integrations](https://arize.com/docs/ax/integrations)
* **llms.txt (doc discovery):** [https://arize.com/docs/llms.txt](https://arize.com/docs/llms.txt) — use this as a fallback if a routing table URL is unavailable or returns an error

***

## PHASE 1: ANALYSIS (read-only)

Scan the codebase and identify the developer's stack. **Do not write any code or create any files during this phase.**

### How to scan

1. **Check dependency manifests first** — these are the most reliable signals:
   * Python: `pyproject.toml`, `requirements.txt`, `setup.py`, `Pipfile`
   * TypeScript/JavaScript: `package.json`
   * Java: `pom.xml`, `build.gradle`, `build.gradle.kts`
   * Go: `go.mod`

2. **Then scan import statements** in source files to confirm what's actually used.

3. **Check for existing tracing/OTel setup** — look for:
   * `TracerProvider`, `register()`, `opentelemetry` imports
   * Environment variables: `ARIZE_*`, `OTEL_*`, `OTLP_*`
   * Config files for other observability vendors (Datadog, Honeycomb, New Relic, etc.)

4. **Identify the scope** — for monorepos or multi-service projects, ask the user which service(s) to instrument rather than guessing.

### What to identify

1. **Language** — Python, TypeScript/JavaScript, Java, C#/.NET, or Go
2. **Package manager** — pip/poetry/uv, npm/pnpm/yarn, maven/gradle, NuGet/dotnet, go modules
3. **LLM providers** — match against the LLM Providers table below
4. **Frameworks** — match against the Agent Frameworks / Platforms tables below. **For version-sensitive frameworks, record the resolved major version, not just the package name** — some frameworks split their tracing setup by major version (notably the **Vercel AI SDK**: the `ai` major decides between the v6 and v7 pages). Resolve the actual installed major from the lockfile when `package.json` only gives a range.
5. **Existing tracing** — any pre-existing OTel or observability setup (see guidance below)

### Key rule

> **When a framework is detected alongside an LLM provider, instrument both unless the framework already emits model-call spans.** Microsoft Agent Framework emits OpenTelemetry GenAI spans for agent, model, and tool operations; follow its integration guide and do not add a provider instrumentor that duplicates those spans.

### Phase 1 output

Return a concise summary:

* Detected language, package manager, providers, frameworks
* Proposed integration list (matched from the routing table below)
* Any existing OTel/tracing setup that needs consideration
* If monorepo: which service(s) you propose to instrument

**STOP. Present your analysis and wait for user confirmation before proceeding to Phase 2.**

***

## INTEGRATION ROUTING TABLE

This is the **canonical list** of supported integrations. Use these tables to map detected signals to documentation URLs. Fetch the matched doc pages for implementation details.

### LLM Providers

| Detection signal | Integration | Doc URL |
| - | - | - |
| `openai` | OpenAI | [https://arize.com/docs/ax/integrations/llm-providers/openai/openai-tracing](https://arize.com/docs/ax/integrations/llm-providers/openai/openai-tracing) |
| `prismml` or an OpenAI client with base\_url `localhost:8080/v1` | PrismML | [https://arize.com/docs/ax/integrations/llm-providers/prismml/prismml-tracing](https://arize.com/docs/ax/integrations/llm-providers/prismml/prismml-tracing) |
| `anthropic` | Anthropic | [https://arize.com/docs/ax/integrations/llm-providers/anthropic/anthropic-tracing](https://arize.com/docs/ax/integrations/llm-providers/anthropic/anthropic-tracing) |
| `google.generativeai` or `@google/generative-ai` | Google | [https://arize.com/docs/ax/integrations/llm-providers/google-gen-ai/google-genai-tracing](https://arize.com/docs/ax/integrations/llm-providers/google-gen-ai/google-genai-tracing) |
| `groq` | Groq | [https://arize.com/docs/ax/integrations/llm-providers/groq/groq-tracing](https://arize.com/docs/ax/integrations/llm-providers/groq/groq-tracing) |
| `boto3` + `bedrock` | Amazon Bedrock | [https://arize.com/docs/ax/integrations/llm-providers/amazon-bedrock/amazon-bedrock-tracing](https://arize.com/docs/ax/integrations/llm-providers/amazon-bedrock/amazon-bedrock-tracing) |
| `litellm` | LiteLLM | [https://arize.com/docs/ax/integrations/llm-providers/litellm/litellm-tracing](https://arize.com/docs/ax/integrations/llm-providers/litellm/litellm-tracing) |
| `ollama` | Ollama | [https://arize.com/docs/ax/integrations/llm-providers/llama/ollama-tracing](https://arize.com/docs/ax/integrations/llm-providers/llama/ollama-tracing) |
| `mistralai` | MistralAI | [https://arize.com/docs/ax/integrations/llm-providers/mistralai/mistralai-tracing](https://arize.com/docs/ax/integrations/llm-providers/mistralai/mistralai-tracing) |
| `openrouter` | OpenRouter | [https://arize.com/docs/ax/integrations/llm-providers/openrouter/openrouter-tracing](https://arize.com/docs/ax/integrations/llm-providers/openrouter/openrouter-tracing) |
| `baseten` or an OpenAI client with base\_url `inference.baseten.co` | Baseten | [https://arize.com/docs/ax/integrations/llm-providers/baseten/baseten-tracing](https://arize.com/docs/ax/integrations/llm-providers/baseten/baseten-tracing) |
| `cerebras` or an OpenAI client with base\_url `api.cerebras.ai` | Cerebras | [https://arize.com/docs/ax/integrations/llm-providers/cerebras/cerebras-tracing](https://arize.com/docs/ax/integrations/llm-providers/cerebras/cerebras-tracing) |
| `deepseek` or an OpenAI client with base\_url `api.deepseek.com` | DeepSeek | [https://arize.com/docs/ax/integrations/llm-providers/deepseek/deepseek-tracing](https://arize.com/docs/ax/integrations/llm-providers/deepseek/deepseek-tracing) |
| `fireworks` or an OpenAI client with base\_url `api.fireworks.ai` | Fireworks AI | [https://arize.com/docs/ax/integrations/llm-providers/fireworks-ai/fireworks-ai-tracing](https://arize.com/docs/ax/integrations/llm-providers/fireworks-ai/fireworks-ai-tracing) |
| `huggingface_hub`, `HF_TOKEN`, or an OpenAI client with base\_url `router.huggingface.co` | Hugging Face Inference Providers | [https://arize.com/docs/ax/integrations/llm-providers/hugging-face/hugging-face-inference-providers-tracing](https://arize.com/docs/ax/integrations/llm-providers/hugging-face/hugging-face-inference-providers-tracing) |
| `novita` or an OpenAI client with base\_url `api.novita.ai` | Novita AI | [https://arize.com/docs/ax/integrations/llm-providers/novita-ai/novita-ai-tracing](https://arize.com/docs/ax/integrations/llm-providers/novita-ai/novita-ai-tracing) |
| `qwen`, `dashscope`, or an OpenAI client with base\_url `dashscope` | Qwen | [https://arize.com/docs/ax/integrations/llm-providers/qwen/qwen-tracing](https://arize.com/docs/ax/integrations/llm-providers/qwen/qwen-tracing) |
| `vertexai` or `google.cloud.aiplatform` | VertexAI | [https://arize.com/docs/ax/integrations/llm-providers/vertexai/vertexai-tracing](https://arize.com/docs/ax/integrations/llm-providers/vertexai/vertexai-tracing) |
| `orcarouter` (or an OpenAI client with base\_url `api.orcarouter.ai`) | OrcaRouter | [https://arize.com/docs/ax/integrations/llm-providers/orcarouter/orcarouter-tracing](https://arize.com/docs/ax/integrations/llm-providers/orcarouter/orcarouter-tracing) |
| `truefoundry` (or an OpenAI client with a TrueFoundry `base_url`) | TrueFoundry | [https://arize.com/docs/ax/integrations/llm-providers/truefoundry/truefoundry-tracing](https://arize.com/docs/ax/integrations/llm-providers/truefoundry/truefoundry-tracing) |
| `doubleword` (or an OpenAI client with a Doubleword `base_url`) | Doubleword | [https://arize.com/docs/ax/integrations/llm-providers/doubleword/doubleword-tracing](https://arize.com/docs/ax/integrations/llm-providers/doubleword/doubleword-tracing) |
| `cohere` | Cohere | [https://arize.com/docs/ax/integrations/llm-providers/cohere/cohere-tracing](https://arize.com/docs/ax/integrations/llm-providers/cohere/cohere-tracing) |
| `together` | Together AI | [https://arize.com/docs/ax/integrations/llm-providers/together-ai/together-ai-tracing](https://arize.com/docs/ax/integrations/llm-providers/together-ai/together-ai-tracing) |
| `xai`, `grok`, or an OpenAI client with base\_url `api.x.ai` | xAI Grok | [https://arize.com/docs/ax/integrations/llm-providers/xai/xai-grok-tracing](https://arize.com/docs/ax/integrations/llm-providers/xai/xai-grok-tracing) |
| `z.ai`, `zai`, `glm`, or an OpenAI client with base\_url `api.z.ai` | Z.ai | [https://arize.com/docs/ax/integrations/llm-providers/z-ai/z-ai-tracing](https://arize.com/docs/ax/integrations/llm-providers/z-ai/z-ai-tracing) |
| An OpenAI client with an `X-Gravitee-Api-Key` header, or a Gravitee AI Gateway `base_url` | Gravitee | [https://arize.com/docs/ax/integrations/llm-providers/gravitee/gravitee-tracing](https://arize.com/docs/ax/integrations/llm-providers/gravitee/gravitee-tracing) |
| An OpenAI-compatible client routed through `gateway.ai.cloudflare.com`, or Cloudflare AI Gateway OTEL exporter config | Cloudflare AI Gateway | [https://arize.com/docs/ax/integrations/llm-providers/cloudflare-ai-gateway/cloudflare-ai-gateway-tracing](https://arize.com/docs/ax/integrations/llm-providers/cloudflare-ai-gateway/cloudflare-ai-gateway-tracing) |
| `vllm` or an OpenAI client with base\_url `localhost:8000/v1` | vLLM | [https://arize.com/docs/ax/integrations/llm-providers/vllm/vllm-tracing](https://arize.com/docs/ax/integrations/llm-providers/vllm/vllm-tracing) |

> **Note:** The Ollama doc URL slug is `/llama`, not `/ollama`. This is intentional.

### Python Agent Frameworks

| Detection signal | Integration | Doc URL |
| - | - | - |
| `langchain` | LangChain | [https://arize.com/docs/ax/integrations/python-agent-frameworks/langchain/langchain-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/langchain/langchain-tracing) |
| `langgraph` | LangGraph | [https://arize.com/docs/ax/integrations/python-agent-frameworks/langgraph/langgraph-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/langgraph/langgraph-tracing) |
| `llama_index` | LlamaIndex | [https://arize.com/docs/ax/integrations/python-agent-frameworks/llamaindex/llamaindex-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/llamaindex/llamaindex-tracing) |
| `crewai` | CrewAI | [https://arize.com/docs/ax/integrations/python-agent-frameworks/crewai/crewai-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/crewai/crewai-tracing) |
| `dspy` | DSPy | [https://arize.com/docs/ax/integrations/python-agent-frameworks/dspy/dspy-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/dspy/dspy-tracing) |
| `autogen` (legacy API, via AG2) | AutoGen legacy API | [https://arize.com/docs/ax/integrations/python-agent-frameworks/autogen/autogen-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/autogen/autogen-tracing) |
| `ag2` (which exposes the `autogen` module) | AG2 | [https://arize.com/docs/ax/integrations/python-agent-frameworks/ag2/ag2-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/ag2/ag2-tracing) |
| `autogen_agentchat` | AutoGen AgentChat | [https://arize.com/docs/ax/integrations/python-agent-frameworks/autogen/autogen-agentchat-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/autogen/autogen-agentchat-tracing) |
| `semantic_kernel` | Semantic Kernel | [https://arize.com/docs/ax/integrations/python-agent-frameworks/semantic-kernel/semantic-kernel-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/semantic-kernel/semantic-kernel-tracing) |
| `pydantic_ai` | Pydantic AI | [https://arize.com/docs/ax/integrations/python-agent-frameworks/pydantic/pydantic-ai-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/pydantic/pydantic-ai-tracing) |
| `haystack` | Haystack | [https://arize.com/docs/ax/integrations/python-agent-frameworks/haystack/haystack-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/haystack/haystack-tracing) |
| `guardrails` | Guardrails AI | [https://arize.com/docs/ax/integrations/python-agent-frameworks/guardrails-ai/guardrails-ai-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/guardrails-ai/guardrails-ai-tracing) |
| `smolagents` | Hugging Face Smolagents | [https://arize.com/docs/ax/integrations/python-agent-frameworks/hugging-face-smolagents/smolagents-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/hugging-face-smolagents/smolagents-tracing) |
| `instructor` | Instructor | [https://arize.com/docs/ax/integrations/python-agent-frameworks/instructor/instructor-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/instructor/instructor-tracing) |
| `agno` | Agno | [https://arize.com/docs/ax/integrations/python-agent-frameworks/agno/agno-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/agno/agno-tracing) |
| `google.adk` or `google_adk` | Google ADK | [https://arize.com/docs/ax/integrations/python-agent-frameworks/google-adk/google-adk-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/google-adk/google-adk-tracing) |
| `agents` (the `openai-agents` package) | OpenAI Agents SDK | [https://arize.com/docs/ax/integrations/python-agent-frameworks/openai-agents/openai-agents-sdk-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/openai-agents/openai-agents-sdk-tracing) |
| `mcp` or `modelcontextprotocol` | Model Context Protocol | [https://arize.com/docs/ax/integrations/python-agent-frameworks/model-context-protocol/mcp-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/model-context-protocol/mcp-tracing) |
| `portkey` | Portkey | [https://arize.com/docs/ax/integrations/python-agent-frameworks/portkey/portkey-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/portkey/portkey-tracing) |
| `beeai` | BeeAI | [https://arize.com/docs/ax/integrations/python-agent-frameworks/beeai/beeai-tracing-python](https://arize.com/docs/ax/integrations/python-agent-frameworks/beeai/beeai-tracing-python) |
| `strands` (the `strands-agents` package) | AWS Strands Agents | [https://arize.com/docs/ax/integrations/python-agent-frameworks/aws-strands/aws-strands-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/aws-strands/aws-strands-tracing) |
| `bedrock-agentcore` or `bedrock-agentcore-starter-toolkit` (a Strands/CrewAI/LangGraph/etc. agent deployed on AWS Bedrock AgentCore Runtime) | AWS Bedrock AgentCore | [https://arize.com/docs/ax/integrations/python-agent-frameworks/aws-strands/bedrock-agentcore](https://arize.com/docs/ax/integrations/python-agent-frameworks/aws-strands/bedrock-agentcore) |
| `claude_agent_sdk` (the `claude-agent-sdk` package) | Claude Agent SDK | [https://arize.com/docs/ax/integrations/python-agent-frameworks/claude-agent-sdk/claude-agent-sdk-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/claude-agent-sdk/claude-agent-sdk-tracing) |
| `agent_framework` (the `agent-framework` package) | Microsoft Agent Framework | [https://arize.com/docs/ax/integrations/python-agent-frameworks/microsoft/microsoft-agent-framework](https://arize.com/docs/ax/integrations/python-agent-frameworks/microsoft/microsoft-agent-framework) |
| `nat` (the `nvidia-nat` package) | NVIDIA NeMo Agent Toolkit | [https://arize.com/docs/ax/integrations/python-agent-frameworks/nvidia/nemo-agent-toolkit-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/nvidia/nemo-agent-toolkit-tracing) |
| `pipecat` | Pipecat | [https://arize.com/docs/ax/integrations/python-agent-frameworks/pipecat/pipecat-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/pipecat/pipecat-tracing) |
| `pyagentspec` (Oracle Open Agent Spec) | Open Agent Spec | [https://arize.com/docs/ax/integrations/python-agent-frameworks/agentspec/agentspec-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/agentspec/agentspec-tracing) |
| `boto3` + `bedrock-agent` | AWS Bedrock Agents | [https://arize.com/docs/ax/integrations/llm-providers/amazon-bedrock/amazon-bedrock-agents-tracing](https://arize.com/docs/ax/integrations/llm-providers/amazon-bedrock/amazon-bedrock-agents-tracing) |
| `livekit.agents` or the `livekit-agents` package | LiveKit Agents | [https://arize.com/docs/ax/integrations/python-agent-frameworks/livekit/livekit-agents-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/livekit/livekit-agents-tracing) |
| `temporalio` | Temporal | [https://arize.com/docs/ax/integrations/python-agent-frameworks/temporal/temporal-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/temporal/temporal-tracing) |
| `restate` (the `restate-sdk` package) | Restate | [https://arize.com/docs/ax/integrations/python-agent-frameworks/restate/restate-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/restate/restate-tracing) |
| `typesafe_sdk` (the `typesafe-sdk` package) | TypeSafe AI | [https://arize.com/docs/ax/integrations/python-agent-frameworks/typesafe/typesafe-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/typesafe/typesafe-tracing) |
| `grafi` (Graphite) | Graphite | [https://arize.com/docs/ax/integrations/python-agent-frameworks/graphite/graphite-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/graphite/graphite-tracing) |

### .NET Agent Frameworks

| Detection signal | Integration | Doc URL |
| - | - | - |
| `Microsoft.Agents.AI.OpenAI` in a `.csproj`, or `Microsoft.Agents.AI` in C# source | Microsoft Agent Framework for C# | [https://arize.com/docs/ax/integrations/dotnet-agent-frameworks/microsoft/microsoft-agent-framework](https://arize.com/docs/ax/integrations/dotnet-agent-frameworks/microsoft/microsoft-agent-framework) |

> **Note:** LlamaIndex Workflows use the **same instrumentor** as core LlamaIndex. If you detect `llama_index`, the LlamaIndex row already covers workflows — no extra instrumentation is needed. When the app uses Workflows specifically (`from llama_index.core.workflow import Workflow, step`, or the `@step` decorator), also point the user to the workflow-focused guide: [https://arize.com/docs/ax/integrations/python-agent-frameworks/llamaindex/llamaindex-workflows-tracing](https://arize.com/docs/ax/integrations/python-agent-frameworks/llamaindex/llamaindex-workflows-tracing)

### TypeScript/JavaScript Frameworks

| Detection signal | Integration | Doc URL |
| - | - | - |
| `langchain` or `@langchain/core` (in `package.json`) | LangChain JS | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/langchain/langchain-js](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/langchain/langchain-js) |
| `@mastra/core` (in `package.json`) | Mastra | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/mastra/mastra-tracing](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/mastra/mastra-tracing) |
| `ai` major is **7** (`ai@^7` / `ai@7.x` in `package.json` or lockfile) — even if `@ai-sdk/otel` is absent | Vercel AI SDK v7 | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/vercel/vercel-ai-sdk-v7-tracing](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/vercel/vercel-ai-sdk-v7-tracing) |
| `ai` major is **6 or earlier** (`ai@^6`, `3.3`–`6.x` in `package.json` — corroborated by `import { ... } from 'ai'` in source) | Vercel AI SDK (v6 and earlier) | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/vercel/vercel-ai-sdk-v6-tracing](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/vercel/vercel-ai-sdk-v6-tracing) |
| `eve` (in `package.json`, or an `eve/instrumentation` import) | Vercel Eve | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/vercel/eve-tracing](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/vercel/eve-tracing) |
| `@openai/agents` (in `package.json`) | OpenAI Agents (JS) | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/openai-agents/openai-agents-js](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/openai-agents/openai-agents-js) |
| `@tanstack/ai` (in `package.json`) | TanStack AI | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/tanstack/tanstack-ai-tracing](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/tanstack/tanstack-ai-tracing) |
| `@typesafe-ai/sdk` (in `package.json`) | TypeSafe AI | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/typesafe/typesafe-tracing-js](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/typesafe/typesafe-tracing-js) |
| `@i-am-bee` (in `package.json`) | BeeAI JS | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/beeai/beeai-tracing-js](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/beeai/beeai-tracing-js) |
| `@anthropic-ai/claude-agent-sdk` (in `package.json`) | Claude Agent SDK (JS) | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/claude-agent-sdk/claude-agent-sdk-js](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/claude-agent-sdk/claude-agent-sdk-js) |
| `@aws-sdk/client-bedrock-agent-runtime` (in `package.json`) | Amazon Bedrock Agents (JS) | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/amazon-bedrock/amazon-bedrock-agents-js](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/amazon-bedrock/amazon-bedrock-agents-js) |
| `@modelcontextprotocol/sdk` (in `package.json`) | MCP (JS) | [https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/model-context-protocol/mcp-tracing-js](https://arize.com/docs/ax/integrations/ts-js-agent-frameworks/model-context-protocol/mcp-tracing-js) |

> **Note:** Vercel AI SDK v6 and v7 wire telemetry differently and are **not** interchangeable — v6 emits OpenTelemetry spans natively; v7 requires the `@ai-sdk/otel` integration. **Route by the `ai` major version only.** `@ai-sdk/otel` is installed *during* setup — it is **not** a detection signal, and a not-yet-instrumented v7 app won't have it, so never gate the v7 page on its presence. If `package.json` only gives a range (`^7`, `>=7`), read the resolved major from `package-lock.json` / `pnpm-lock.yaml` / `yarn.lock`, or ask the user; **do not default to the v6 page.** The v6 setup produces **zero spans** on `ai@7`, and the v7 setup produces zero spans on `ai@6`.

### Java

| Detection signal | Integration | Doc URL |
| - | - | - |
| `langchain4j` (in `pom.xml` or `build.gradle`) | LangChain4j | [https://arize.com/docs/ax/integrations/java/langchain4j/langchain4j-tracing](https://arize.com/docs/ax/integrations/java/langchain4j/langchain4j-tracing) |
| `spring-ai` (in `pom.xml` or `build.gradle`) | Spring AI | [https://arize.com/docs/ax/integrations/java/spring-ai/spring-ai-tracing](https://arize.com/docs/ax/integrations/java/spring-ai/spring-ai-tracing) |
| `arconia` (in `pom.xml` or `build.gradle`) | Arconia | [https://arize.com/docs/ax/integrations/java/arconia/arconia-tracing](https://arize.com/docs/ax/integrations/java/arconia/arconia-tracing) |
| `com.google.adk:google-adk` (in `pom.xml` or `build.gradle`) | Google ADK for Java | [https://arize.com/docs/ax/integrations/java/google-adk/google-adk-tracing](https://arize.com/docs/ax/integrations/java/google-adk/google-adk-tracing) |
| Hand-built Java agent/pipeline with no matched framework (annotate methods with `@Chain`/`@LLM`/`@Tool`/`@Agent`) | Annotations | [https://arize.com/docs/ax/integrations/java/annotation/annotation-tracing](https://arize.com/docs/ax/integrations/java/annotation/annotation-tracing) |

> **Note:** Google ADK for Java is instrumented by a **`-javaagent`**, not a library — it is the only Java integration where the application imports no OpenInference class. Two traps. First, the agent advises `com.google.adk.Telemetry`, which ADK renamed to `com.google.adk.telemetry.Tracing` in **0.6.0**, so **`com.google.adk:google-adk` must be pinned to `0.5.0` or lower** (the doc pins `0.4.0`). On `0.6.0`+ the agent installs but its matchers silently miss: ADK's own spans still export, so traces *look* fine while carrying no `openinference.span.kind`, no messages and no token counts. **Do not "helpfully" bump ADK to the latest version** — that is the failure. Second, the global OpenTelemetry SDK must be registered before *any* ADK class loads, because ADK captures `GlobalOpenTelemetry` when `Telemetry` is first loaded; an `LlmAgent` built in a static initializer or an eagerly-constructed DI graph traces to a no-op.

### Go

Requires **Go 1.25+** (floor of the OpenInference Go modules; `arize-otel-go` itself is Go 1.23+). Wire tracing with [`arize-otel-go`](https://github.com/Arize-ai/arize-otel-go) and attach a per-provider auto-instrumentor when one exists, or set OpenInference attributes manually for clients that don't.

| Detection signal | Integration | Doc URL |
| - | - | - |
| `github.com/openai/openai-go` in `go.mod` | OpenAI (auto) | [https://arize.com/docs/ax/integrations/llm-providers/openai/openai-tracing](https://arize.com/docs/ax/integrations/llm-providers/openai/openai-tracing) |
| `github.com/anthropics/anthropic-sdk-go` in `go.mod` | Anthropic (auto) | [https://arize.com/docs/ax/integrations/llm-providers/anthropic/anthropic-tracing](https://arize.com/docs/ax/integrations/llm-providers/anthropic/anthropic-tracing) |
| `go.mod` present, no matched provider | Manual OTel + OpenInference | [https://arize.com/docs/ax/instrument/manual-instrumentation](https://arize.com/docs/ax/instrument/manual-instrumentation) |

### Platforms

These are UI-based platforms, not code libraries. They cannot be auto-detected from imports. If the user mentions using one, or you find platform-specific config files (e.g., Docker Compose references, deployment manifests), match them here:

| Platform | Doc URL |
| - | - |
| LangFlow | [https://arize.com/docs/ax/integrations/platforms/langflow/langflow-tracing](https://arize.com/docs/ax/integrations/platforms/langflow/langflow-tracing) |
| Flowise | [https://arize.com/docs/ax/integrations/platforms/flowise/flowise-tracing](https://arize.com/docs/ax/integrations/platforms/flowise/flowise-tracing) |
| Dify | [https://arize.com/docs/ax/integrations/platforms/dify/dify-tracing](https://arize.com/docs/ax/integrations/platforms/dify/dify-tracing) |
| Prompt flow | [https://arize.com/docs/ax/integrations/platforms/prompt-flow/prompt-flow-tracing](https://arize.com/docs/ax/integrations/platforms/prompt-flow/prompt-flow-tracing) |
| n8n | [https://arize.com/docs/ax/integrations/platforms/n8n/n8n-tracing](https://arize.com/docs/ax/integrations/platforms/n8n/n8n-tracing) |
| Open WebUI | [https://arize.com/docs/ax/integrations/platforms/openwebui/openwebui-tracing](https://arize.com/docs/ax/integrations/platforms/openwebui/openwebui-tracing) |

### Fallback

If no integration matches, or for advanced use cases:

* **Manual instrumentation:** [https://arize.com/docs/ax/instrument/manual-instrumentation](https://arize.com/docs/ax/instrument/manual-instrumentation)
* **All integrations:** [https://arize.com/docs/ax/integrations](https://arize.com/docs/ax/integrations)

***

## PHASE 2: IMPLEMENTATION

After the user confirms your Phase 1 analysis, implement tracing.

### 1. Fetch integration docs

Read the matched doc URLs from the routing table above. Follow the installation and instrumentation steps from those pages.

### 2. Install packages

Install the required packages using the detected package manager **before** writing any code.

* **Python:** `pip install arize-otel` plus instrumentors (see naming convention below)
* **TypeScript/JavaScript:** `npm install @opentelemetry/sdk-trace-node` plus the relevant `@arizeai/openinference-*` package
* **Java:** Add OpenTelemetry SDK and the relevant `openinference-instrumentation-*` dependency to `pom.xml` or `build.gradle`
* **Go:** core packages, then exactly one provider instrumentor matched to the detected SDK:
  ```
  go get \
    github.com/Arize-ai/arize-otel-go \
    github.com/Arize-ai/openinference/go/openinference-instrumentation \
    github.com/Arize-ai/openinference/go/openinference-semantic-conventions

  # plus one of:
  go get github.com/Arize-ai/openinference/go/openinference-instrumentation-openai-go        # openai/openai-go
  go get github.com/Arize-ai/openinference/go/openinference-instrumentation-anthropic-sdk-go # anthropics/anthropic-sdk-go
  ```

### 3. Get credentials

**No Arize account yet?** Sign the user up for free first — they cannot get credentials without one. Point them to [https://app.arize.com/auth/join](https://app.arize.com/auth/join) to create a free account, then have them create (or select) a space before continuing. Once they have an account, get the Space ID and API Key below.

The user needs their **Arize Space ID** and **API Key** from:
[https://app.arize.com/organizations/-/settings/space-api-keys](https://app.arize.com/organizations/-/settings/space-api-keys)

Set as environment variables:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
ARIZE_SPACE_ID=<space-id>
ARIZE_API_KEY=<api-key>
```

### 4. Core setup patterns

Create a **single centralized instrumentation module** (e.g., `instrumentation.py`, `instrumentation.ts`). Initialize tracing **before** any LLM client is created.

#### Python

The universal Python pattern uses `arize-otel` to configure OpenTelemetry:

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
from arize.otel import register

tracer_provider = register(
    space_id="YOUR_SPACE_ID",  # or os.environ["ARIZE_SPACE_ID"]
    api_key="YOUR_API_KEY",    # or os.environ["ARIZE_API_KEY"]
    project_name="your-project-name",
)
```

Then attach instrumentors for each detected integration:

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
from openinference.instrumentation.openai import OpenAIInstrumentor
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)
```

##### Python instrumentor naming convention

Instrumentor packages follow a predictable pattern:

| | Pattern | Example (OpenAI) | Example (LlamaIndex) |
| - | - | - | - |
| **pip package** | `openinference-instrumentation-{name}` | `openinference-instrumentation-openai` | `openinference-instrumentation-llama-index` |
| **Import** | `openinference.instrumentation.{name}` | `openinference.instrumentation.openai` | `openinference.instrumentation.llama_index` |
| **Class** | `{Name}Instrumentor` | `OpenAIInstrumentor` | `LlamaIndexInstrumentor` |

> **Note:** pip package names use hyphens; Python module names use underscores. For multi-word names (e.g., `llama-index` → `llama_index`), convert hyphens to underscores in the import path.

> **Exception — span-processor integrations.** A few integrations do **not** ship an `{Name}Instrumentor` and are **not** wired with `register()` + `.instrument()`. Instead they add a reshaping `SpanProcessor` to a manually built `TracerProvider` (because they need the Arize exporter *and* a span reshaper to coexist, which `register()`'s single default processor can't host). Known cases: **Semantic Kernel** (OpenLIT → `OpenInferenceSpanProcessor` + `openlit.init()`), **AWS Strands** (`StrandsAgentsToOpenInferenceProcessor` + `StrandsTelemetry`), and **Microsoft Agent Framework** (`AgentFrameworkToOpenInferenceProcessor` + `enable_instrumentation`). For these, follow the matched doc page's setup verbatim rather than applying the instrumentor convention above.

#### TypeScript / JavaScript

TS/JS integrations use `@opentelemetry/sdk-trace-node` as the tracing backbone, with a framework-specific `@arizeai/openinference-*` package. The setup varies by framework:

**LangChain JS:**

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
import { SEMRESATTRS_PROJECT_NAME } from "@arizeai/openinference-semantic-conventions";
import { LangChainInstrumentation } from "@arizeai/openinference-instrumentation-langchain";
import * as CallbackManagerModule from "@langchain/core/callbacks/manager";

const projectName = process.env.ARIZE_PROJECT_NAME ?? "langchain-js-app";

const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: projectName,
    [SEMRESATTRS_PROJECT_NAME]: projectName,
  }),
  spanProcessors: [
    new SimpleSpanProcessor(
      new OTLPTraceExporter({
        url: "https://otlp.arize.com/v1/traces",
        headers: {
          "arize-space-id": process.env.ARIZE_SPACE_ID ?? "",
          "arize-api-key": process.env.ARIZE_API_KEY ?? "",
        },
      }),
    ),
  ],
});
provider.register();

const lcInstrumentation = new LangChainInstrumentation();
lcInstrumentation.manuallyInstrument(CallbackManagerModule);
```

**Vercel AI SDK:**

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { OpenInferenceSimpleSpanProcessor, isOpenInferenceSpan } from "@arizeai/openinference-vercel";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";

const provider = new NodeTracerProvider({
  spanProcessors: [
    new OpenInferenceSimpleSpanProcessor({
      exporter: new OTLPTraceExporter({
        url: "https://otlp.arize.com/v1/traces",
        headers: {
          "arize-space-id": process.env.ARIZE_SPACE_ID || "",
          "arize-api-key": process.env.ARIZE_API_KEY || "",
        },
      }),
      spanFilter: isOpenInferenceSpan,
    }),
  ],
});
provider.register();
```

Then enable telemetry at each AI SDK call site:

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const result = streamText({
  model: openai("gpt-4o"),
  messages,
  experimental_telemetry: { isEnabled: true },
});
```

**Mastra:**

Mastra registers tracing through its observability layer using the first-party `@mastra/arize` exporter (`npm install @mastra/arize @mastra/observability @mastra/core`). The `ArizeExporter` reads `ARIZE_SPACE_ID`, `ARIZE_API_KEY`, and `ARIZE_PROJECT_NAME` from the environment.

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { ArizeExporter } from "@mastra/arize";

export const mastra = new Mastra({
  agents: { /* your agents */ },
  observability: new Observability({
    configs: {
      arize: {
        serviceName: process.env.ARIZE_PROJECT_NAME ?? "my-mastra-app",
        exporters: [new ArizeExporter()],
      },
    },
  }),
});
```

For other TS/JS frameworks, fetch the matched doc URL for framework-specific details. The common elements across all TS/JS setups are:

* OTLP export endpoint: `https://otlp.arize.com/v1/traces`
* Auth headers: `arize-space-id` and `arize-api-key`
* All Arize TS/JS packages live under the `@arizeai/openinference-*` npm scope

#### Java

Java integrations use the OpenTelemetry Java SDK with OTLP/gRPC export. The level of automation varies:

**Arconia** (zero-code — recommended for Spring Boot projects):

Add dependencies and Arconia auto-configures tracing via its Spring Boot starter. No explicit OTel setup code needed — just set environment variables.

**LangChain4j** (one-liner):

```java theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// After OpenTelemetry SDK initialization:
LangChain4jInstrumentor.instrument();
// All LangChain4j calls are automatically traced from this point.
```

**Google ADK for Java** (zero-code, but needs a JVM flag):

Resolve the shaded agent jar and pass it to the JVM — the application itself imports no OpenInference class. There is no instrumentor call to add.

```groovy theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
configurations { openinferenceAgent }
dependencies {
    openinferenceAgent(
        'com.arize:openinference-instrumentation-adk-java:0.1.1:all@jar')
}
tasks.named('run') {
    doFirst {
        jvmArgs "-javaagent:${configurations.openinferenceAgent.singleFile}"
    }
}
```

Without the `-javaagent` flag there is no instrumentation at all. Confirm the line `OpenInference ADK instrumentation installed` appears at startup.

**Spring AI** (manual wiring):

```java theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
OITracer tracer = new OITracer(tracerProvider.get("com.example.springai"), TraceConfig.getDefault());
ObservationRegistry registry = ObservationRegistry.create();
registry.observationConfig().observationHandler(new SpringAIInstrumentor(tracer));

// Pass registry to model builder:
OpenAiChatModel model = OpenAiChatModel.builder()
    .openAiApi(openAiApi)
    .observationRegistry(registry)
    .build();
```

All Java integrations share these OTel SDK initialization fundamentals:

```java theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
OtlpGrpcSpanExporter otlpExporter = OtlpGrpcSpanExporter.builder()
    .setEndpoint("https://otlp.arize.com:443")
    .setHeaders(() -> Map.of(
        "authorization", System.getenv("ARIZE_API_KEY"),
        "arize-space-id", System.getenv("ARIZE_SPACE_ID"),
        "arize-interface", "java"))
    .build();
```

For full setup details, fetch the matched doc URL.

#### Go

Wire the exporter with [`arize-otel-go`](https://github.com/Arize-ai/arize-otel-go) and attach the per-provider auto-instrumentor for the detected SDK. The `arize-otel-go` `Register` call reads `ARIZE_SPACE_ID`, `ARIZE_API_KEY`, and `ARIZE_PROJECT_NAME` from the environment when the matching `Options` fields are unset, and sets the required `openinference.project.name` resource attribute on the TracerProvider.

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
package main

import (
    "context"
    "log"
    "os"
    "time"

    arizeotel "github.com/Arize-ai/arize-otel-go"
    openaiotel "github.com/Arize-ai/openinference/go/openinference-instrumentation-openai-go"
    "github.com/openai/openai-go"
    "github.com/openai/openai-go/option"
    "go.opentelemetry.io/otel"
)

func main() {
    ctx := context.Background()

    tp, err := arizeotel.Register(ctx, arizeotel.Options{
        ProjectName: "your-go-app",
    })
    if err != nil {
        log.Printf("register tracer: %v", err)
        return
    }
    defer func() {
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()
        _ = tp.Shutdown(shutdownCtx)
    }()

    // Every /v1/chat/completions call emits an LLM span automatically.
    client := openai.NewClient(
        option.WithAPIKey(os.Getenv("OPENAI_API_KEY")),
        option.WithMiddleware(openaiotel.Middleware(otel.Tracer("your-go-app"))),
    )

    _ = client
    // ... your app ...
}
```

For `anthropics/anthropic-sdk-go`, swap the import and middleware:

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import (
    "github.com/anthropics/anthropic-sdk-go"
    "github.com/anthropics/anthropic-sdk-go/option"
    anthropicotel "github.com/Arize-ai/openinference/go/openinference-instrumentation-anthropic-sdk-go"
)

client := anthropic.NewClient(
    option.WithMiddleware(anthropicotel.Middleware(otel.Tracer("your-go-app"))),
)
```

For clients without an auto-instrumentor, create spans manually with OpenInference [semantic-conventions constants](https://github.com/Arize-ai/openinference/tree/main/go/openinference-semantic-conventions):

```go theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import (
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/attribute"

    semconv "github.com/Arize-ai/openinference/go/openinference-semantic-conventions"
)

tracer := otel.Tracer("your-go-app")
ctx, span := tracer.Start(ctx, "run-agent")
defer span.End()
span.SetAttributes(
    attribute.String(semconv.OpenInferenceSpanKind, semconv.SpanKindChain),
    attribute.String(semconv.InputValue, userInput),
    attribute.String(semconv.OutputValue, finalReply),
)
```

EU spaces: pass `Endpoint: arizeotel.EndpointArizeEurope` to `arizeotel.Options`. CLI/short-lived processes **must** keep the `defer tp.Shutdown(ctx)` block — and never call `log.Fatalf` or `os.Exit` after a span has started — or batched spans will be dropped. For full setup details, see [https://arize.com/docs/ax/instrument/manual-instrumentation](https://arize.com/docs/ax/instrument/manual-instrumentation).

### 5. Handling existing OTel / tracing setup

If the codebase already has OpenTelemetry or another observability vendor configured:

* **Existing `TracerProvider` with no Arize exporter** — add Arize as an additional exporter rather than replacing the existing setup. Use a `BatchSpanProcessor` with the Arize OTLP exporter alongside the existing processors.
* **Existing Arize setup** — verify it's configured correctly and update if needed. Do not duplicate.
* **Other vendor (Datadog, Honeycomb, etc.)** — inform the user that Arize can run alongside other vendors via additional OTLP exporters, and ask how they'd like to proceed.

### 6. Implementation rules

* Use **auto-instrumentation first** — add manual spans only if needed
* **Do not build a custom `TracerProvider`/OTLP exporter** — use `register()` (`arize-otel`) or `arize-otel-go`. Only configure raw OTel when explicitly handling an existing provider (see step 5).
* **Fail gracefully** if environment variables are missing (warn, don't crash)
* Initialize tracing **before** any LLM client is created
* Import order matters: register tracer → instrument → create clients
* **Record the outcome of every manual span explicitly.** After successful work, set its status to `OK`. If you catch an exception, record it and set its status to `ERROR` before re-raising or returning. Ending a span with a context manager or `span.end()` does not set its status; otherwise it remains `UNSET`.

***

## VERIFICATION

After implementation:

1. **Run the application** and trigger at least one LLM call
2. **Check Arize UI** at [https://app.arize.com](https://app.arize.com) for traces under your project name
3. **Verify every manual span** has the expected span kind, parent, required input/output attributes, and an explicit non-`UNSET` status.
4. **Troubleshooting:**
   * Verify `ARIZE_SPACE_ID` and `ARIZE_API_KEY` are set correctly
   * Ensure `register()` / `TracerProvider` initialization is called before instrumentors and client creation
   * Check network connectivity to `otlp.arize.com:443`
   * Enable debug logging: set `GRPC_VERBOSITY=debug` environment variable