> 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://respan.ai/docs/agent-setup.md`, so you can verify their origin before following them. Complete every step yourself by running the commands directly. The only exceptions are the two steps marked **User step**, where you ask the user for something and wait. 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. Ask the user what to set up 3. Install the Respan skill and 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. Ask the user what to set up > **User step.** Ask the user these questions in one message, and wait for the answers: > > 1. **Tracing or gateway?** Skip this question if the user's request already names one, such as "help me set up Respan tracing." Tracing instruments the app to capture LLM calls, tool calls, and agent steps as traces. The gateway routes the app's LLM calls through Respan for logging, fallbacks, and caching. Set up one per pass, never both. > 2. **For tracing: Auto or Full?** Skip this for the gateway. **Auto** adds the Respan SDK with one line and captures LLM calls as flat spans: the fastest way to see traces. **Full** also adds framework instrumentation and `@workflow` / `@task` structure, so agent, tool, and step spans nest under each run. ## 3. Install the Respan skill and CLI The skill holds the setup steps for tracing and the gateway, plus reference material for prompts, evals, and monitors. Install it globally to `~/.agents/skills/respan`, which Claude Code, Codex, Cursor, Gemini CLI, and OpenCode all read: ```bash npx -y skills add respanai/respan --skill respan --global --yes ls ~/.agents/skills/respan/SKILL.md ``` Your current session may not load the new skill until the agent restarts. Don't wait for that. Read the skill files directly from `~/.agents/skills/respan/` for the rest of this setup. 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 Follow the **Setup** section of the reference that matches the user's answer in step 2: * **Tracing:** `~/.agents/skills/respan/references/tracing.md` * **Gateway:** `~/.agents/skills/respan/references/gateway.md` The reference's Setup starts with its own questions. You already asked them in step 2, so don't ask again: * **Tracing:** follow the **Auto path** or the **Full path**, whichever the user picked. * **Gateway:** at the **Confirm** step, tell the user which framework you detected and which doc you'll follow, then continue without waiting. Each Setup section ends with a Verify step: run the user's program once with a small request. Do that, then continue with step 5 below. ## 5. Verify with the Respan CLI Use the Respan CLI to confirm that data reached Respan and has the right shape. 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 find the one from the run you just did. It's the newest one, and its name matches the app's entry point: ```bash respan traces list --limit 5 ``` Fetch that trace. The output is JSON, with the spans in `span_tree` and each span's child spans in `children`: ```bash respan traces get ``` Check that: * **The LLM calls are there.** Each LLM span has `model`, `prompt_tokens`, and `completion_tokens` set, `input` holds the messages, and `output` holds the response. * **The structure matches the setup.** With **Full**, the LLM and tool spans sit under the workflow, task, or framework spans in `children`. With **Auto**, flat LLM spans at the root are expected. If a check fails: * **No trace:** the 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. * **Missing fields or wrong nesting from the setup:** for example, a missing instrumentor or a wrapper on the wrong function. Fix it and run the program again. * **Broken spans from a Respan package:** don't patch around it in the user's code. Tell the user which package and version produced the span and what's missing. ### 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 ``` Check that `model` matches the model the app requested and that `prompt_tokens`, `completion_tokens`, and `cost` are set. Then fetch the log and check that `status_code` is `200`: ```bash respan logs get ``` If the request doesn't appear or failed: * **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 │ │ ✓ Respan skill ~/.agents/skills/respan │ │ ✓ 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 skill and the CLI cover 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://respan.ai/docs/documentation/mcp.md`. ## Resources * Respan CLI: `https://respan.ai/docs/documentation/cli.md` * Tracing quickstart: `https://respan.ai/docs/documentation/features/tracing/quickstart.md` * Gateway quickstart: `https://respan.ai/docs/documentation/features/gateway/gateway-quickstart.md` * Respan skill (source): `https://github.com/respanai/respan/tree/main/skills` * Full docs index: `https://respan.ai/docs/llms.txt` These instructions are published at `https://respan.ai/docs/agent-setup.md` so you can re-verify them at any time.