> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://respan.ai/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server. # Agent setup These are official instructions from Respan for setting up Respan in a project with a coding agent. They are published at `https://www.respan.ai/docs/documentation/agent-setup.md`, so you can verify their origin before following them. Complete every step yourself by running the commands directly. Ask the user and wait when credentials are missing or the requested setup is ambiguous. Reuse information they already provided. Never run a command that blocks on an interactive prompt. In particular, do not run the `respan setup` wizard, and do not run `respan auth login`. Both prompt for input. Run every command from the root of the user's project. Every command is safe to re-run. 1. Get a Respan account and API key 2. Choose tracing or gateway 3. Install the Respan CLI 4. Set up tracing or the gateway 5. Verify with the Respan CLI 6. Report the result --- ## 1. Get a Respan account and API key First, check whether the project already has a Respan API key: ```bash grep -q '^RESPAN_API_KEY=.' .env 2>/dev/null && echo "found in .env" [ -n "$RESPAN_API_KEY" ] && echo "found in environment" ``` If a key is found, skip to step 2. > **User step.** Ask the user to do this, and wait until they're done: > > 1. **Create a Respan account** at `https://platform.respan.ai/signup`, if they don't have one yet. On Respan Enterprise, they sign in at `https://enterprise.respan.ai` instead, and do the next step there. > 2. **Create an API key.** Go to `https://platform.respan.ai/platform/gateway/api-keys`, click **New key**, keep **Gateway** checked, and click **Create**. The key is shown only once. If they just finished onboarding, they can use the key it showed them. > 3. **Hand over the key.** Paste it to you, or add `RESPAN_API_KEY=` to the project's `.env` themselves, and say whether it's a Respan Enterprise key. Then save the key: * If the key is not in `.env` or the environment yet, add `RESPAN_API_KEY=` to `.env` on its own line. * Make sure `.env` is listed in `.gitignore`. * For Respan Enterprise, also add `RESPAN_BASE_URL=https://endpoint.respan.ai/api` to `.env`. * Never print the key in your replies or in command output. ## 2. Choose tracing or gateway Use the user's request to choose the setup. If it already says tracing, observability, or gateway, don't ask them to choose again. If it is ambiguous, ask which they want and wait. | Setup | Changes in the app | Verify with | | ----------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | Observability / tracing | Initialize the Respan SDK and instrument the existing framework or LLM SDK. Keep the current provider routing. | Traces and their spans; direct auto-instrumented LLM calls can arrive as flat spans. | | Gateway | Configure the framework or SDK's LLM client to call the Respan gateway. | LLM request logs. A gateway log does not prove framework tracing is installed. | Set up the requested path only. Gateway logging and framework tracing are different integrations, even when they use the same API key. Don't install tracing packages for a gateway-only request or change provider routing for a tracing-only request. If the user explicitly wants both, complete and verify each path separately. For tracing, inspect the app first. Use its framework instrumentation page when it has a supported framework; use the tracing quickstart for direct LLM SDK auto-instrumentation. Honor an explicit Auto or Framework instrumentation preference. Explain the selected approach and continue; the user doesn't need to choose an instrumentation method unless their intent is unclear. ## 3. Install the Respan CLI The CLI is how you verify the setup in step 5. It needs Node.js 18 or later: ```bash npm install -g @respan/cli respan --version ``` If the global install fails with a permissions error, do not use `sudo`. Use `npx -y @respan/cli` in place of `respan` for every command in step 5. ## 4. Set up tracing or the gateway Before you change anything: * Read the code and find where the app creates its LLM clients. * Check whether Respan is already set up, such as an existing `respan` import or a base URL that points at `api.respan.ai`. Don't set it up twice. * Select the matching column in the integration map below. If the app uses a framework on top of an LLM SDK, such as CrewAI on top of the OpenAI SDK, use the framework's page. Fetch that page before editing; it owns the exact packages, initialization, and client wiring. Some tracing pages also mention optional gateway routing: skip that part for tracing-only setup. * Tell the user which framework or SDK you detected and which page you'll follow, then continue without waiting. While you make changes: * Use only the code from the docs page you follow. Don't guess package names or APIs. * Pin exact versions of every package you install. * Only add Respan code. Don't refactor unrelated code. ### Integration page map Read the page in the column for the selected setup. These are distinct pages: do not infer a gateway URL from a tracing slug (for example, OpenAI SDK uses `openai-sdk` for tracing and `open-ai-sdk` for gateway). * Tracing directory: [Observability integrations](https://www.respan.ai/docs/integrations/overview.md). * Gateway directory: [Gateway integrations](https://www.respan.ai/docs/integrations/gateway/overview.md). * `—` means no dedicated page is listed in that directory; it does not mean the product is unsupported. Check the directory and [docs index](https://www.respan.ai/docs/llms.txt) before choosing a fallback. * The observability directory also includes notification, memory, migration, and other tool guides. Follow their stated purpose; they are not all app instrumentation recipes. | Integration | Observability / tracing page | Gateway page | | ------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Respan SDK | [Observability](https://www.respan.ai/docs/documentation/features/tracing/quickstart.md) | — | | OpenTelemetry | [Observability](https://www.respan.ai/docs/integrations/opentelemetry.md) | — | | OpenAI Agents | [Observability](https://www.respan.ai/docs/integrations/openai-agents-sdk.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/open-ai-agents.md) | | Claude Agent SDK | [Observability](https://www.respan.ai/docs/integrations/claude-agents-sdk.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/claude-agent-sdk.md) | | Vercel AI SDK | [Observability](https://www.respan.ai/docs/integrations/vercel-ai-sdk.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/vercel-ai-sdk.md) | | Pydantic AI | [Observability](https://www.respan.ai/docs/integrations/pydantic-ai.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/pydantic-ai.md) | | CrewAI | [Observability](https://www.respan.ai/docs/integrations/crewai.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/crew-ai.md) | | Haystack | [Observability](https://www.respan.ai/docs/integrations/haystack.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/haystack.md) | | LangChain | [Observability](https://www.respan.ai/docs/integrations/langchain.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/lang-chain.md) | | LangGraph | [Observability](https://www.respan.ai/docs/integrations/langgraph.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/lang-graph.md) | | Langflow | [Observability](https://www.respan.ai/docs/integrations/langflow.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/langflow.md) | | Mirascope | [Observability](https://www.respan.ai/docs/integrations/mirascope.md) | — | | LlamaIndex | [Observability](https://www.respan.ai/docs/integrations/llama-index.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/llama-index.md) | | Temporal | [Observability](https://www.respan.ai/docs/integrations/temporal.md) | — | | AgentOps | [Observability](https://www.respan.ai/docs/integrations/agentops.md) | — | | OpenLIT | [Observability](https://www.respan.ai/docs/integrations/openlit.md) | — | | Apache Burr | [Observability](https://www.respan.ai/docs/integrations/burr.md) | — | | Restate | [Observability](https://www.respan.ai/docs/integrations/restate.md) | — | | AutoGen | [Observability](https://www.respan.ai/docs/integrations/autogen.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/auto-gen.md) | | DSPy | [Observability](https://www.respan.ai/docs/integrations/dspy.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/ds-py.md) | | Google ADK | [Observability](https://www.respan.ai/docs/integrations/google-adk.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/google-adk.md) | | Microsoft Agent Framework | [Observability](https://www.respan.ai/docs/integrations/microsoft-agent-framework.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/microsoft-agent-framework.md) | | Semantic Kernel | [Observability](https://www.respan.ai/docs/integrations/semantic-kernel.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/semantic-kernel.md) | | AgentScope | [Observability](https://www.respan.ai/docs/integrations/agentscope.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/agent-scope.md) | | Watson Orchestrate ADK | [Observability](https://www.respan.ai/docs/integrations/watson-orchestrate-adk.md) | — | | Smolagents | [Observability](https://www.respan.ai/docs/integrations/smolagents.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/smolagents.md) | | Strands Agents | [Observability](https://www.respan.ai/docs/integrations/strands-agents.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/strands-agents.md) | | AgentSpec | [Observability](https://www.respan.ai/docs/integrations/agent-spec.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/agent-spec.md) | | Guardrails | [Observability](https://www.respan.ai/docs/integrations/guardrails.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/guardrails.md) | | Agno | [Observability](https://www.respan.ai/docs/integrations/agno.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/agno.md) | | MCP | [Observability](https://www.respan.ai/docs/integrations/mcp.md) | — | | BeeAI | [Observability](https://www.respan.ai/docs/integrations/bee-ai.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/bee-ai.md) | | Flue | [Observability](https://www.respan.ai/docs/integrations/flue.md) | — | | Pipecat | [Observability](https://www.respan.ai/docs/integrations/pipecat.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/pipecat.md) | | Mastra | [Observability](https://www.respan.ai/docs/integrations/mastra.md) | — | | Superagent | [Observability](https://www.respan.ai/docs/integrations/superagent.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/superagent.md) | | BAML | [Observability](https://www.respan.ai/docs/integrations/baml.md) | — | | Arize | [Observability](https://www.respan.ai/docs/integrations/arize.md) | — | | Dify | [Observability](https://www.respan.ai/docs/integrations/dify.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/dify.md) | | LiveKit | [Observability](https://www.respan.ai/docs/integrations/livekit.md) | — | | OpenRouter | [Observability](https://www.respan.ai/docs/integrations/openrouter-tracing.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/openrouter.md) | | Codex SDK | [Observability](https://www.respan.ai/docs/integrations/codex-sdk.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/codex-sdk.md) | | Cursor SDK | [Observability](https://www.respan.ai/docs/integrations/cursor-sdk.md) | — | | Pi Coding Agent SDK | [Observability](https://www.respan.ai/docs/integrations/pi-sdk.md) | — | | Eve | [Observability](https://www.respan.ai/docs/integrations/eve.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/eve.md) | | OpenAI SDK | [Observability](https://www.respan.ai/docs/integrations/openai-sdk.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/open-ai-sdk.md) | | Azure OpenAI | [Observability](https://www.respan.ai/docs/integrations/azure-openai-tracing.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/azure-open-ai.md) | | Instructor | [Observability](https://www.respan.ai/docs/integrations/instructor.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/instructor.md) | | Anthropic SDK | [Observability](https://www.respan.ai/docs/integrations/anthropic.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/anthropic-sdk.md) | | Google GenAI | [Observability](https://www.respan.ai/docs/integrations/google-genai.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/google-gen-ai.md) | | LiteLLM | [Observability](https://www.respan.ai/docs/integrations/litellm.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/lite-llm.md) | | RubyLLM | [Observability](https://www.respan.ai/docs/integrations/ruby-llm.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/ruby-llm.md) | | Vertex AI | [Observability](https://www.respan.ai/docs/integrations/vertex-ai.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/vertex-ai.md) | | AWS Bedrock | [Observability](https://www.respan.ai/docs/integrations/aws-bedrock.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/aws-bedrock.md) | | Cohere | [Observability](https://www.respan.ai/docs/integrations/cohere.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/cohere.md) | | Groq | [Observability](https://www.respan.ai/docs/integrations/groq-tracing.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/groq.md) | | Mistral AI | [Observability](https://www.respan.ai/docs/integrations/mistral-tracing.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/mistral-ai.md) | | Ollama | [Observability](https://www.respan.ai/docs/integrations/ollama.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/ollama.md) | | Portkey | [Observability](https://www.respan.ai/docs/integrations/portkey.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/portkey.md) | | Watsonx | [Observability](https://www.respan.ai/docs/integrations/watsonx.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/watsonx.md) | | Together AI | [Observability](https://www.respan.ai/docs/integrations/together-ai.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/together-ai.md) | | Aleph Alpha | [Observability](https://www.respan.ai/docs/integrations/aleph-alpha.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/aleph-alpha.md) | | HuggingFace | [Observability](https://www.respan.ai/docs/integrations/huggingface.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/huggingface.md) | | Replicate | [Observability](https://www.respan.ai/docs/integrations/replicate.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/replicate.md) | | SageMaker | [Observability](https://www.respan.ai/docs/integrations/sagemaker.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/sage-maker.md) | | Writer | [Observability](https://www.respan.ai/docs/integrations/writer.md) | — | | Respan API | [Observability](https://www.respan.ai/docs/integrations/respan-api.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/respan-api.md) | | Claude Code | [Observability](https://www.respan.ai/docs/integrations/claude-code.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/claude-code.md) | | Codex CLI | [Observability](https://www.respan.ai/docs/integrations/codex-cli.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/codex-cli.md) | | Gemini CLI | [Observability](https://www.respan.ai/docs/integrations/gemini-cli.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/gemini-cli.md) | | OpenCode | [Observability](https://www.respan.ai/docs/integrations/open-code.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/open-code.md) | | Cursor | [Observability](https://www.respan.ai/docs/integrations/cursor.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/cursor.md) | | pi | [Observability](https://www.respan.ai/docs/integrations/pi.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/pi.md) | | Chroma | [Observability](https://www.respan.ai/docs/integrations/chroma.md) | — | | Elasticsearch | [Observability](https://www.respan.ai/docs/integrations/elasticsearch.md) | — | | LanceDB | [Observability](https://www.respan.ai/docs/integrations/lance-db.md) | — | | Marqo | [Observability](https://www.respan.ai/docs/integrations/marqo.md) | — | | Milvus | [Observability](https://www.respan.ai/docs/integrations/milvus.md) | — | | Pinecone | [Observability](https://www.respan.ai/docs/integrations/pinecone.md) | — | | pgvector | [Observability](https://www.respan.ai/docs/integrations/pgvector.md) | — | | Qdrant | [Observability](https://www.respan.ai/docs/integrations/qdrant.md) | — | | Weaviate | [Observability](https://www.respan.ai/docs/integrations/weaviate.md) | — | | Pytest | [Observability](https://www.respan.ai/docs/integrations/pytest.md) | — | | Ragas | [Observability](https://www.respan.ai/docs/integrations/ragas.md) | — | | Mem0 | [Observability](https://www.respan.ai/docs/integrations/mem0.md) | — | | Hyperspell | [Observability](https://www.respan.ai/docs/integrations/hyperspell.md) | — | | Cognee | [Observability](https://www.respan.ai/docs/integrations/cognee.md) | — | | Slack | [Observability](https://www.respan.ai/docs/integrations/slack.md) | — | | Microsoft Teams | [Observability](https://www.respan.ai/docs/integrations/microsoft-teams.md) | — | | n8n | [Observability](https://www.respan.ai/docs/integrations/n-8-n.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/n-8-n.md) | | Exa | [Observability](https://www.respan.ai/docs/integrations/exa.md) | — | | Linkup | [Observability](https://www.respan.ai/docs/integrations/linkup.md) | — | | PostHog | [Observability](https://www.respan.ai/docs/integrations/posthog.md) | — | | Moda | [Observability](https://www.respan.ai/docs/integrations/moda.md) | — | | AssemblyAI | [Observability](https://www.respan.ai/docs/integrations/assemblyai.md) | — | | Zapier | [Observability](https://www.respan.ai/docs/integrations/zapier.md) | — | | Braintrust | [Observability](https://www.respan.ai/docs/integrations/braintrust.md) | — | | Helicone | [Observability](https://www.respan.ai/docs/integrations/helicone.md) | [Gateway](https://www.respan.ai/docs/integrations/gateway/helicone.md) | | Langfuse | [Observability](https://www.respan.ai/docs/integrations/langfuse.md) | — | | Hermes Agent | — | [Gateway](https://www.respan.ai/docs/integrations/gateway/hermes-agent.md) | | OpenClaw | — | [Gateway](https://www.respan.ai/docs/integrations/gateway/open-claw.md) | | Kilo Code | — | [Gateway](https://www.respan.ai/docs/integrations/gateway/kilo-code.md) | | Cline | — | [Gateway](https://www.respan.ai/docs/integrations/gateway/cline.md) | | Roo Code | — | [Gateway](https://www.respan.ai/docs/integrations/gateway/roo-code.md) | | Aider | — | [Gateway](https://www.respan.ai/docs/integrations/gateway/aider.md) | | OpenHands | — | [Gateway](https://www.respan.ai/docs/integrations/gateway/open-hands.md) | | omp | — | [Gateway](https://www.respan.ai/docs/integrations/gateway/omp.md) | | Qwen Code | — | [Gateway](https://www.respan.ai/docs/integrations/gateway/qwen-code.md) | | goose | — | [Gateway](https://www.respan.ai/docs/integrations/gateway/goose.md) | | Zed | — | [Gateway](https://www.respan.ai/docs/integrations/gateway/zed.md) | | DeepSeek Harness | — | [Gateway](https://www.respan.ai/docs/integrations/gateway/deep-seek-harness.md) | The map mirrors the published integration directories. If a page moves or a new integration is added, use the docs index rather than guessing a path. For a stack without a dedicated tracing page, start with the [tracing quickstart](https://www.respan.ai/docs/documentation/features/tracing/quickstart.md) or [OpenTelemetry](https://www.respan.ai/docs/integrations/opentelemetry.md). For a compatible gateway client without a dedicated page, start with the [gateway quickstart](https://www.respan.ai/docs/documentation/features/gateway/gateway-quickstart.md). ### Coding-agent tracing If the user wants to trace the coding agent itself (Codex CLI, Gemini CLI, OpenCode, or pi), configure that agent's native hooks or extension instead of adding an application SDK. A copyable setup prompt on its integration page is the user-facing entry point, not another setup procedure to invoke: do not follow it back to this guide in a loop. * **Codex CLI and Gemini CLI:** the installed `@respan/cli` package includes the tracing runtimes at `dist/hooks/codex-cli.cjs` and `dist/hooks/gemini-cli.cjs`. Locate the installed package, read its hook runtime and the coding agent's hook documentation for the installed version, then register the runtime in the agent's native configuration. Preserve unrelated hooks and settings. The runtime source is maintained under `javascript-sdks/respan-cli/src/hooks/` in [respanai/respan](https://github.com/respanai/respan/tree/main/javascript-sdks/respan-cli/src/hooks). * **OpenCode:** follow the `opencode-otel` plugin's current installation and configuration instructions, using the Respan export endpoint and credentials. Read the plugin's supported configuration before editing it. * **pi:** follow the native `pi install npm:@respan/instrumentation-pi` instructions and configuration options on the [pi integration page](https://www.respan.ai/docs/integrations/pi.md). Do not install an old CLI or run `respan integrate`. After configuring the agent, run one small session and verify its actual traces or spans with step 5. ### Tracing * **Auto:** follow the tracing quickstart, `https://www.respan.ai/docs/documentation/features/tracing/quickstart.md`. Install the Respan SDK and initialize it once in the entry point, before the first LLM call. Skip the quickstart's workflow wrapper. If the app calls the Vercel AI SDK directly, also add the Vercel instrumentation from its **(tracing)** page. The Respan SDK doesn't pick up the Vercel AI SDK on its own. * **Framework instrumentation:** follow the framework's **(tracing)** page. Install the Respan SDK and the framework's instrumentation package, and register the instrumentor the way the page shows. Don't add `@workflow` / `@task` decorators by default. Add them only when the framework instrumentation can't group a run's spans into one trace, such as an app that calls an LLM SDK directly from its own orchestration code, or when the user asks to customize the trace structure. ### Gateway Follow the framework or SDK's **(gateway)** page: * Point only the clients that make completion calls, such as chat completions, Anthropic messages, or Gemini content generation, at the gateway. Use the exact base URL from the page. Leave clients for embeddings, images, audio, batch, and other operations as they are. The gateway doesn't serve them. * Apply the page's wiring exactly. For example, some SDKs need the client set in code instead of through environment variables, and some need switching from the OpenAI Responses API to chat completions. * Don't install Respan instrumentation packages. Those are for tracing. Then run the user's program once with a small request, and continue with step 5. ## 5. Verify with the Respan CLI Use the Respan CLI to confirm that the run from step 4 reached Respan. The CLI reads `RESPAN_API_KEY` from the project's `.env`, so you don't need to log in. For Enterprise, add `--base-url https://endpoint.respan.ai` to every command below. ### Tracing List recent traces and match the run you just made by time, name, and available identifiers. Don't assume the newest trace belongs to this run. Retrieve the matching trace with `respan traces get `: ```bash respan traces list --limit 5 --json ``` Check that: * **The trace is there,** and its `error_count` is `0`. * **`span_count` matches the setup.** With **Framework instrumentation**, one run is one trace, and `span_count` covers its agent, tool, and LLM spans. With **Auto**, each LLM call can arrive as its own small trace. That's expected. If a check fails: * **No trace:** first check whether auto-instrumented calls arrived as logs with `respan logs list --limit 5 --all-envs true --json`. Also check the time range, project, and environment before concluding instrumentation isn't taking effect. Check where tracing is initialized, whether short-lived scripts flush before exit, and whether you ran the right entry point. Fix it and run the program again. * **Errors, or one run split across several traces:** for example, a missing instrumentor, or a direct LLM SDK call outside the framework. Fix the setup, adding decorators only if step 4 calls for them, and run the program again. * **A Respan package looks broken:** don't patch around it in the user's code. Tell the user which package and version, and what went wrong. ### Gateway List logs from the last hour, in every environment, and find the request from the run you just did. Without `--all-envs true`, the list shows only production data, and requests sent with a test API key don't appear: ```bash respan logs list --limit 5 --all-envs true --json ``` Check that `model` matches the model the app requested and that `prompt_tokens`, `completion_tokens`, and `cost` are set. If the request doesn't appear, or the app's run in step 4 failed with an error from the gateway: * **401 with code `activation_required`:** the organization has no credits and no provider key for this model. Ask the user to add credits at `https://platform.respan.ai/platform/gateway/credits`, or add their provider key. * **Any other 401:** a provider key the organization added was rejected. Ask the user to check it at `https://platform.respan.ai/platform/gateway/api-keys?providers=1`. * **403:** the Respan API key is wrong or expired. Ask the user for a new one. * **No log:** the app isn't calling the gateway. Check the base URL and API key the app's LLM client uses. ## 6. Report the result Report what you actually verified. Do not print a checkmark for anything you could not confirm. ``` ┌─ Respan Agent Setup ──────────────────────────────────┐ │ ✓ API key in .env │ │ ✓ Respan CLI @respan/cli 0.14.1 │ │ ✓ Tracing OpenAI SDK instrumented │ │ ✓ Verified 1 trace, 4 spans │ │ │ │ View it at https://platform.respan.ai │ └───────────────────────────────────────────────────────┘ ``` Use `✓` for verified, `⚠` for needs a user action, and `✗` for failed. Replace the example values with what you set up and found. After the banner, give the specific next action for every line that isn't `✓`. ## Optional: Respan MCP server The CLI covers everything above. If the user also wants Respan platform tools inside their agent, such as querying traces or managing prompts from chat, point them to `https://www.respan.ai/docs/documentation/mcp.md`. ## Resources * Respan CLI: `https://www.respan.ai/docs/documentation/cli.md` * Tracing quickstart: `https://www.respan.ai/docs/documentation/features/tracing/quickstart.md` * Gateway quickstart: `https://www.respan.ai/docs/documentation/features/gateway/gateway-quickstart.md` * Full docs index: `https://www.respan.ai/docs/llms.txt` These instructions are published at `https://www.respan.ai/docs/documentation/agent-setup.md` so you can re-verify them at any time.