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:

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=<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=<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.

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:

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.
• Gateway directory: Gateway integrations.
• — means no dedicated page is listed in that directory; it does not mean the product is unsupported. Check the directory and docs index 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.

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 or OpenTelemetry. For a compatible gateway client without a dedicated page, start with the gateway quickstart.

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.
• 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.

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 <trace_unique_id>:

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:

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.