Respan

https://www.respan.ai/docs/documentation/
Admin
Respan is a full-stack AI engineering platform that enables teams to trace agent workflows in...
Tokens:63,408
Snippets:718
Trust Score:7.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Run Respan CLI Setup

Source: https://www.respan.ai/docs/documentation/get-started/quickstart

Execute this command in your project directory to automatically instrument your application with the Respan SDK. It handles language detection, SDK installation, and API key setup if needed.

```bash
npx @respan/cli setup
```

--------------------------------

### Install Pydantic AI Instrumentation (Python)

Source: https://www.respan.ai/docs/documentation/features/tracing/traces

Install Respan and Pydantic AI packages for Python.

```bash
pip install respan-ai respan-instrumentation-pydantic-ai pydantic-ai
```

--------------------------------

### Python SDK Configuration for OTLP Traces

Source: https://www.respan.ai/docs/documentation/features/tracing/spans

Set up the OpenTelemetry Python SDK to export traces to Respan's OTLP endpoint. This example demonstrates initializing the exporter, tracer provider, and starting a span with attributes.

```python
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://api.respan.ai/api/v2/traces",
    headers={"Authorization": "Bearer YOUR_RESPAN_API_KEY"},
)

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("my-service")
with tracer.start_as_current_span("my-operation") as span:
    span.set_attribute("gen_ai.request.model", "gpt-4")
    # Your code here
```

--------------------------------

### Install Vercel AI Instrumentation (TypeScript)

Source: https://www.respan.ai/docs/documentation/features/tracing/traces

Install Respan and Vercel AI packages for TypeScript.

```bash
npm install ai @ai-sdk/openai @respan/respan @respan/tracing @respan/instrumentation-vercel
```

--------------------------------

### Install Respan SDK

Source: https://www.respan.ai/docs/documentation/features/tracing/traces

Install the Respan AI SDK for Python or the Respan package for TypeScript to enable automatic tracing of LLM calls.

```bash
pip install respan-ai
```

```bash
npm install @respan/respan
```

--------------------------------

### Install OpenAI Agents Instrumentation (Python)

Source: https://www.respan.ai/docs/documentation/features/tracing/traces

Install the necessary Respan and OpenAI Agents packages for Python.

```bash
pip install respan-ai respan-instrumentation-openai-agents openai-agents
```

--------------------------------

### Install Python Dependencies

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/trace-a-rag-pipeline

Install the necessary Python packages for Respan tracing, OpenAI integration, and ChromaDB.

```python
pip install respan-tracing openai chromadb
```

--------------------------------

### Install Respan Tracing and LlamaIndex

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/trace-a-rag-pipeline

Install the necessary dependencies for Respan Tracing and LlamaIndex. Choose the appropriate package manager command based on your environment (Python or Node.js).

```bash
pip install respan-tracing llama-index llama-index-llms-openai
```

```bash
npm install @respan/tracing llamaindex
```

--------------------------------

### Install Claude Agents Instrumentation (Python)

Source: https://www.respan.ai/docs/documentation/features/tracing/traces

Install the necessary Respan and Claude Agent SDK packages for Python.

```bash
pip install claude-agent-sdk respan-ai respan-instrumentation-claude-agent-sdk
```

--------------------------------

### cURL Example

Source: https://www.respan.ai/docs/documentation/features/tracing/spans

Example of sending traces to Respan's OTLP endpoint using cURL.

```APIDOC
## cURL Example

### Description
Example of sending traces to Respan's OTLP endpoint using cURL.

### Command
```bash
curl -X POST "https://api.respan.ai/api/v2/traces" \
  -H "Authorization: Bearer YOUR_RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "resourceSpans": [{ \
      "resource": { \
        "attributes": [ \
          {"key": "service.name", "value": {"stringValue": "my-service"}} \
        ] \
      }, \
      "scopeSpans": [{ \
        "scope": {"name": "manual"}, \
        "spans": [{ \
          "traceId": "0af7651916cd43dd8448eb211c80319c", \
          "spanId": "b7ad6b7169203332", \
          "name": "my-operation", \
          "startTimeUnixNano": "1700000000000000000", \
          "endTimeUnixNano": "1700000001000000000", \
          "status": {"code": 1}, \
          "attributes": [] \
        }] \
      }] \
    }] \
  }'
```
```

--------------------------------

### Initialize RAG Components with Milvus

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/trace-a-rag-pipeline

Set up Respan Telemetry, OpenAI client, and Milvus client for a RAG pipeline. This example uses Milvus Lite for local development and creates a document collection.

```python
from openai import OpenAI
from respan_tracing import RespanTelemetry
from respan_tracing.decorators import workflow, task
from pymilvus import MilvusClient

# Initialize
telemetry = RespanTelemetry()
client = OpenAI()
milvus = MilvusClient("milvus_demo.db")  # Milvus Lite for local development

# Create collection
milvus.create_collection(collection_name="docs", dimension=1536)

docs = [
    "Respan supports 250+ LLM models through a unified API gateway.",
    "Traces organize logs into hierarchical workflows with parent-child spans.",
    "Evaluators can be LLM-based, code-based, or human reviewers.",
    "Automations run evaluators on production logs in real-time.",
]


def get_embeddings(texts: list[str]) -> list[list[float]]:
    """Embed texts using OpenAI."""
    response = client.embeddings.create(model="text-embedding-3-small", input=texts)

```

--------------------------------

### Install Dependencies for LangChain with Respan

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/trace-a-rag-pipeline

Install the necessary Respan tracing and LangChain packages for both Python and JavaScript environments.

```bash
pip install respan-tracing langchain langchain-openai langchain-chroma
```

```bash
npm install @respan/tracing @langchain/openai @langchain/core langchain
```

--------------------------------

### Install OpenAI Agents Instrumentation (TypeScript)

Source: https://www.respan.ai/docs/documentation/features/tracing/traces

Install the necessary Respan and OpenAI Agents packages for TypeScript.

```bash
npm install @respan/respan @respan/instrumentation-openai-agents @openai/agents
```

--------------------------------

### Setup Respan AI Client and Helper Function

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/gepa-self-improving-prompt-optimization

Initializes the Respan AI client and defines a helper function to fetch prompt details by name and version. Ensure you replace 'YOUR_RESPAN_API_KEY' with your actual API key.

```python
from openai import OpenAI
import requests

client = OpenAI(
    base_url="https://api.respan.ai/api/",
    api_key="YOUR_RESPAN_API_KEY",
)
headers = {"Authorization": "Bearer YOUR_RESPAN_API_KEY"}


def get_prompt(name, version=None):
    params = {"prompt_name": name}
    if version:
        params["version"] = version
    resp = requests.get(
        "https://api.respan.ai/api/prompts/",
        headers=headers,
        params=params,
    )
    return resp.json()
```

--------------------------------

### Install Respan CLI

Source: https://www.respan.ai/docs/documentation/get-started/cli

Install the Respan CLI globally using npm. This command makes the `respan` command available in your terminal.

```bash
npm install -g @respan/cli
```

--------------------------------

### Install JavaScript Dependencies

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/trace-a-rag-pipeline

Install the necessary npm packages for Respan tracing and OpenAI integration in a JavaScript environment.

```javascript
npm install @respan/tracing openai
```

--------------------------------

### Install Claude Agents Instrumentation (TypeScript)

Source: https://www.respan.ai/docs/documentation/features/tracing/traces

Install the necessary Respan and Claude Agent SDK packages for TypeScript.

```bash
npm install @anthropic-ai/claude-agent-sdk @respan/respan @respan/instrumentation-claude-agent-sdk
```

--------------------------------

### RAG Pipeline with Respan and OpenAI

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/trace-a-rag-pipeline

This example shows a complete RAG pipeline instrumented with Respan. It includes routing, retrieval from a mock document store, and generation using OpenAI. Ensure Respan and OpenAI are configured.

```typescript
      async function ragPipeline(query: string) {
          return await respan.withWorkflow(
              { name: 'rag_pipeline' },
              async () => {
                  // Route -decide whether to call the RAG tool
                  const routing = await respan.withTask(
                      { name: 'llm_routing' },
                      async () => {
                          const completion = await openai.chat.completions.create({
                              model: 'gpt-4o-mini',
                              messages: [
                                  {
                                      role: 'system',
                                      content:
                                          'You are a routing agent. Decide if this query requires ' +
                                          'looking up external knowledge. If it does, call the ' +
                                          'retrieve_context tool. Otherwise, respond directly.',
                                  },
                                  { role: 'user', content: query },
                              ],
                              tools: [
                                  {
                                      type: 'function',
                                      function: {
                                          name: 'retrieve_context',
                                          description: 'Search the knowledge base for relevant information',
                                          parameters: {
                                              type: 'object',
                                              properties: {
                                                  query: { type: 'string', description: 'The search query' },
                                              },
                                              required: ['query'],
                                          },
                                      },
                                  },
                              ],
                          });
                          return completion.choices[0].message;
                      }
                  );

                  // Retrieve -get relevant documents from ChromaDB
                  const context = await respan.withTask(
                      { name: 'rag_retrieval' },
                      async () => {
                          if (!routing.tool_calls) return [];
                          // In production, use a ChromaDB client
                          const queryWords = query.toLowerCase().split(' ');
                          return docs.filter(d =>
                              queryWords.some(w => d.toLowerCase().includes(w))
                          );
                      }
                  );

                  // Generate -produce the final answer
                  const answer = await respan.withTask(
                      { name: 'llm_generation' },
                      async () => {
                          const contextStr = context.map(d => `- ${d}`).join('\n');
                          const completion = await openai.chat.completions.create({
                              model: 'gpt-4o-mini',
                              messages: [
                                  { role: 'system', content: `Answer based on this context:\n${contextStr}` },
                                  { role: 'user', content: query },
                              ],
                          });
                          return completion.choices[0].message.content;
                      }
                  );

                  return answer;
              }
          );
      }

      ragPipeline("How does Respan handle tracing?").then(console.log);
```

--------------------------------

### Direct OpenAI API Call

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/migrate-from-open-ai-to-multi-model

Example of making a direct API call to OpenAI using their SDK.

```python
from openai import OpenAI

client = OpenAI(api_key="sk-...")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarize this article..."}],
)
```

--------------------------------

### Install RAG Pipeline Dependencies

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/trace-a-rag-pipeline

Install necessary Python packages for Respan tracing, OpenAI integration, and Milvus.

```bash
pip install respan-tracing openai pymilvus
```

--------------------------------

### Opt-in to Beta Features with X-Respan-Beta Header

Source: https://www.respan.ai/docs/documentation/features/gateway/gateway-quickstart

Enable experimental features by sending comma-separated flags in the X-Respan-Beta header. For example, 'token-breakdown-2026-03-26' adds per-part token estimates to the log's properties field.

```bash
curl -X POST https://api.respan.ai/api/chat/completions \
  -H "Authorization: Bearer YOUR_RESPAN_API_KEY" \
  -H "X-Respan-Beta: token-breakdown-2026-03-26" \
  -d '{"model": "gpt-4o", "messages": [...]}'
```

--------------------------------

### Call Prompt with Schema v2 (TypeScript)

Source: https://www.respan.ai/docs/documentation/features/prompt-management/prompt-management-quickstart

This TypeScript example demonstrates making a fetch request to use prompt schema v2. Replace placeholders with your API key and Prompt ID.

```TypeScript
fetch('https://api.respan.ai/api/chat/completions', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_RESPAN_API_KEY'
    },
    body: JSON.stringify({
        prompt: {
            prompt_id: 'YOUR_PROMPT_ID',
            schema_version: 2,
            variables: {
                task_description: 'Square a number',
                specific_library: 'math'
            }
        }
    })
})
.then(response => response.json())
.then(data => console.log(data));
```

--------------------------------

### OpenAI Agents SDK Integration

Source: https://www.respan.ai/docs/documentation/features/gateway/gateway-quickstart

Example of using the OpenAI Agents SDK with the Respan AI Gateway for agent-based interactions.

```APIDOC
## OpenAI Agents SDK Integration

### Description
Integrate with the OpenAI Agents SDK, configuring it to use the Respan API for agent operations.

### Method
```python
from agents import Agent, Runner
from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://api.respan.ai/api/",
    api_key="YOUR_RESPAN_API_KEY",
)

agent = Agent(name="Assistant", instructions="Reply in one sentence.", model="gpt-5.4")
result = Runner.run_sync(agent, "Explain tracing.", client=client)
print(result.final_output)
```
```

--------------------------------

### Add Credentials via Standard API Request (Python)

Source: https://www.respan.ai/docs/documentation/admin/llm-provider-keys

This Python example demonstrates how to send a request to the LLM proxy API, including custom credentials for a specific model like OpenAI.

```python
import requests
def demo_call(input, 
                  model="gpt-4o-mini",
                  token="YOUR_RESPAN_API_KEY",
                  ):
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {token}',
    }

    data = {
        'model': model,
        'messages': [{'role': 'user', 'content': input}],
        'customer_credentials': {
            "openai": {
                "api_key": "YOUR_OPENAI_API_KEY"
            }
        }
    }

    response = requests.post('https://api.respan.ai/api/chat/completions', headers=headers, json=data)
    return response

messages = "Say 'Hello World'"
print(demo_call(messages).json())
```

--------------------------------

### Use AI Gateway with Customer Parameters (TypeScript)

Source: https://www.respan.ai/docs/documentation/features/customer-identifier

This TypeScript example shows how to use the OpenAI client with the Respan API gateway, including customer parameters for user analytics. Note the use of `customer_params` in the client call.

```typescript
const response = await client.chat.completions.create({
    messages: [{ role: "user", content: "Tell me a story" }],
    model: "gpt-4o-mini",
    // @ts-expect-error
    customer_params: {
        customer_identifier: "customer_1",
        name: "Hendrix Liu",
        email: "hendrix@respan.ai"
    }
});
```

--------------------------------

### Integrate Tracing with Customer Parameters (Vercel AI SDK)

Source: https://www.respan.ai/docs/documentation/features/customer-identifier

This TypeScript example demonstrates how to enable telemetry and pass customer identifiers using the Vercel AI SDK. The `experimental_telemetry.metadata` object is used to provide the `customer_identifier`.

```typescript
const result = streamText({
    model: openai("gpt-4o"),
    messages,
    experimental_telemetry: {
        isEnabled: true,
        metadata: {
            customer_identifier: "customer_1",
        },
    },
});
```

--------------------------------

### Create and Deploy Prompt Version via API (Python)

Source: https://www.respan.ai/docs/documentation/features/prompt-management/advanced

Use the Prompt Versions API to create a new prompt version and deploy it as the live version immediately by setting 'deploy: true'. Requires your Respan API key.

```python
import requests

url = "https://api.respan.ai/api/prompts/<prompt_id>/versions/"
headers = {
    "Authorization": "Bearer YOUR_RESPAN_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "messages": [
        {"role": "system", "content": "You are a helpful {{role}}."},
        {"role": "user", "content": "Hello, how are you?"}
    ],
    "model": "gpt-4o-mini",
    "temperature": 0.7,
    "max_tokens": 256,
    "deploy": True  # Deploy as the live version immediately
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
```

--------------------------------

### Deploy Prompt via API

Source: https://www.respan.ai/docs/documentation/features/prompt-management/advanced

Create and deploy new prompt versions programmatically using the Prompt Versions API. Setting `deploy: true` makes the new version live immediately.

```APIDOC
## Deploy Prompt via API

Use the [Prompt Versions API](/docs/apis/prompts/api-prompts-prompt-id-versions) to create and deploy versions programmatically. Set `deploy: true` to make a version live immediately.

### Request Example (Python)

```python
import requests

url = "https://api.respan.ai/api/prompts/<prompt_id>/versions/"
headers = {
    "Authorization": "Bearer YOUR_RESPAN_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "messages": [
        {"role": "system", "content": "You are a helpful {{role}}."},
        {"role": "user", "content": "Hello, how are you?"}
    ],
    "model": "gpt-4o-mini",
    "temperature": 0.7,
    "max_tokens": 256,
    "deploy": True  # Deploy as the live version immediately
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
```

### Request Example (TypeScript)

```typescript
fetch('https://api.respan.ai/api/prompts/<prompt_id>/versions/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_RESPAN_API_KEY'
    },
    body: JSON.stringify({
        messages: [
            { role: "system", content: "You are a helpful {{role}}." },
            { role: "user", content: "Hello, how are you?" }
        ],
        model: "gpt-4o-mini",
        temperature: 0.7,
        max_tokens: 256,
        deploy: true  // Deploy as the live version immediately
    })
})
.then(response => response.json())
.then(data => console.log(data));
```
```

--------------------------------

### Create and Deploy Prompt Version via API (TypeScript)

Source: https://www.respan.ai/docs/documentation/features/prompt-management/advanced

Use the Prompt Versions API to create a new prompt version and deploy it as the live version immediately by setting 'deploy: true'. Requires your Respan API key.

```typescript
fetch('https://api.respan.ai/api/prompts/<prompt_id>/versions/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_RESPAN_API_KEY'
    },
    body: JSON.stringify({
        messages: [
            { role: "system", content: "You are a helpful {{role}}." },
            { role: "user", content: "Hello, how are you?" }
        ],
        model: "gpt-4o-mini",
        temperature: 0.7,
        max_tokens: 256,
        deploy: true  // Deploy as the live version immediately
    })
})
.then(response => response.json())
.then(data => console.log(data));
```

--------------------------------

### Compare Prompt Management Approaches

Source: https://www.respan.ai/docs/documentation/features/prompt-management/prompt-management-quickstart

Illustrates the difference between hardcoding prompts directly in your application versus using prompt management with a prompt ID and variables.

```python
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "system",
            "content": "You are a helpful customer support agent for TechCorp."
        },
        {
            "role": "user",
            "content": f"Customer {customer_name} is asking about {issue_type}"
        }
    ]
)
```

```python
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "placeholder"}],
    extra_body={
        "prompt": {
            "prompt_id": "042f5f",
            "variables": {
                "customer_name": "John",
                "issue_type": "billing"
            },
            "override": True
        }
    }
)
```

--------------------------------

### Get Aggregated Log Stats

Source: https://www.respan.ai/docs/documentation/get-started/cli

Get aggregated statistics for logs. Supports filtering by time range.

```bash
respan logs summary --start-time "2023-01-01T00:00:00Z" --end-time "2023-01-02T00:00:00Z"
```

--------------------------------

### Switch Claude Models via CLI

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/proxy-coding-agents

Demonstrates how to specify different Claude models directly from the command line interface.

```bash
claude --model claude-opus-4-6
```

```bash
claude --model claude-sonnet-4-5-20250929
```

```bash
claude --model claude-3-5-haiku-20241022
```

--------------------------------

### Set up OpenAI SDK with Respan Gateway

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/end-to-end-from-first-api-call-to-production-monitoring

Configure your OpenAI SDK to point to the Respan API by setting the base URL and providing your Respan API key.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.respan.ai/api/",
    api_key="YOUR_RESPAN_API_KEY",
)
```

--------------------------------

### Use a prompt with the gateway API

Source: https://www.respan.ai/docs/documentation/get-started/gateway

Call the gateway with a prompt ID and variables to inject custom instructions and fill in dynamic content. Replace YOUR_RESPAN_API_KEY and YOUR_PROMPT_ID with your actual credentials.

```bash
curl -X POST "https://api.respan.ai/api/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_RESPAN_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "prompt_id": "YOUR_PROMPT_ID",
    "variables": {
      "language": "Spanish",
      "user_message": "What is machine learning?"
    }
  }'
```

--------------------------------

### Get Specific Log

Source: https://www.respan.ai/docs/documentation/get-started/cli

Retrieve a specific log span by its ID.

```bash
respan logs get <id>
```

--------------------------------

### Integrate OpenCode Agent

Source: https://www.respan.ai/docs/documentation/get-started/cli

Set up tracing for the OpenCode agent. This command writes a hook to `~/.respan/hooks/` and registers it with the agent.

```bash
respan integrate opencode
```

--------------------------------

### Direct API Call (Chat Completions)

Source: https://www.respan.ai/docs/documentation/features/gateway/gateway-quickstart

Example of making a direct POST request to the chat completions endpoint using cURL.

```APIDOC
## Direct API Call (Chat Completions)

### Description
Make a direct API call to the chat completions endpoint using cURL, including authentication and request payload.

### Method
```bash
curl -X POST "https://api.respan.ai/api/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_RESPAN_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```
```

--------------------------------

### Chat Span Example

Source: https://www.respan.ai/docs/documentation/features/tracing/log-content-types

The default span type for chat completions. Input is an array of messages, and output is the assistant's response.

```json
{
  "model": "gpt-4o",
  "input": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is machine learning?"}
  ],
  "output": {
    "role": "assistant",
    "content": "Machine learning is a subset of artificial intelligence..."
  }
}
```

--------------------------------

### Anthropic Authentication Error Response

Source: https://www.respan.ai/docs/documentation/resources/reference/error-handling

Example of an error response when using Anthropic models, indicating an authentication issue such as an invalid API key.

```json
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}
```

--------------------------------

### Deploy Existing Prompt Version via API (Python)

Source: https://www.respan.ai/docs/documentation/features/prompt-management/advanced

Update an existing prompt version to deploy it as the live version by using a PATCH request with 'deploy: true'. Requires your Respan API key.

```python
url = "https://api.respan.ai/api/prompts/<prompt_id>/versions/<version_id>/"
data = {"deploy": True}

response = requests.patch(url, headers=headers, json=data)
```

--------------------------------

### OpenAI API Key Error Response

Source: https://www.respan.ai/docs/documentation/resources/reference/error-handling

Example of an error response when using OpenAI models, specifically indicating an invalid API key.

```json
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
```

--------------------------------

### Initialize Respan with Claude Agents (Python)

Source: https://www.respan.ai/docs/documentation/features/tracing/traces

Initialize Respan with the Claude Agents instrumentor and query the agent.

```python
import asyncio, os
import claude_agent_sdk
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage
from respan import Respan
from respan_instrumentation_claude_agent_sdk import ClaudeAgentSDKInstrumentor

Respan(instrumentations=[ClaudeAgentSDKInstrumentor(capture_content=True)])

async def main():
    async for message in claude_agent_sdk.query(
        prompt="Explain tracing in one sentence.",
        options=ClaudeAgentOptions(model="sonnet", max_turns=1,
            env={"ANTHROPIC_API_KEY": os.environ["ANTHROPIC_API_KEY"]}),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())
```

--------------------------------

### Call Claude Agents SDK via Respan

Source: https://www.respan.ai/docs/documentation/features/gateway/gateway-quickstart

Use the claude_agent_sdk to interact with Claude agents through Respan. This example shows an asynchronous query.

```python
import claude_agent_sdk

async for message in claude_agent_sdk.query(
    prompt="Hello!",
    options={"model": "sonnet", "max_turns": 1},
):
    if isinstance(message, claude_agent_sdk.ResultMessage):
        print(message.result)
```

--------------------------------

### Set Respan API Key

Source: https://www.respan.ai/docs/documentation/features/tracing/traces

Set your Respan API key as an environment variable. For a faster setup, consider using the CLI wizard.

```bash
export RESPAN_API_KEY="your-api-key"
```

--------------------------------

### Initialize Respan with OpenAI Agents (Python)

Source: https://www.respan.ai/docs/documentation/features/tracing/traces

Initialize Respan with the OpenAI Agents instrumentor and run an agent.

```python
from agents import Agent, Runner
from respan import Respan
from respan_instrumentation_openai_agents import OpenAIAgentsInstrumentor

Respan(instrumentations=[OpenAIAgentsInstrumentor()])

agent = Agent(name="Assistant", instructions="Reply in one sentence.")
result = Runner.run_sync(agent, "Explain tracing.")
print(result.final_output)
```

--------------------------------

### Get Absolute Value of Number with Jinja

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/filters-in-jinja-templates

Use the `abs` filter to return the absolute (non-negative) value of a number. This is useful for calculations where the sign is irrelevant.

```jinja
{{ -5 | abs }}  →  5
```

--------------------------------

### Add MCP Server with Whitelisted Tools (Codex CLI)

Source: https://www.respan.ai/docs/documentation/get-started/mcp

Configure the Codex CLI to connect to the Respan MCP server, specifying a whitelist of allowed tools. The configuration is stored in ~/.codex/config.toml. Replace YOUR_RESPAN_API_KEY with your actual key.

```toml
[mcp_servers.respan]
enabled = true
url = "https://mcp.respan.ai/mcp"

[mcp_servers.respan.http_headers]
Authorization = "Bearer YOUR_RESPAN_API_KEY"
Respan-Enabled-Tools = "list_logs,get_log_detail,list_traces,get_trace_tree"
```

--------------------------------

### Get First Item of a List with Jinja

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/filters-in-jinja-templates

The `first` filter retrieves the initial element from a list. It's useful when you only need the first value in a sequence.

```jinja
{{ ["apple", "banana", "cherry"] | first }}  →  apple
```

--------------------------------

### JavaScript RAG Pipeline Initialization

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/trace-a-rag-pipeline

Initialize Respan telemetry and OpenAI client in a JavaScript environment. This example sets up basic configurations for tracing and LLM interactions.

```typescript
import { RespanTelemetry } from '@respan/tracing';
import OpenAI from 'openai';

const respan = new RespanTelemetry({
    apiKey: process.env.RESPAN_API_KEY || "",
    appName: 'rag-app',
});
const openai = new OpenAI();

// Simple in-memory docs for this example
const docs = [
    "Respan supports 250+ LLM models through a unified API gateway.",
    "Traces organize logs into hierarchical workflows with parent-child spans.",
    "Evaluators can be LLM-based, code-based, or human reviewers.",

```

--------------------------------

### JavaScript/TypeScript SDK Configuration for OTLP Traces

Source: https://www.respan.ai/docs/documentation/features/tracing/spans

Configure the OpenTelemetry Node.js SDK to export traces to Respan. This snippet initializes the OTLP trace exporter and starts the SDK.

```typescript
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const exporter = new OTLPTraceExporter({
    url: 'https://api.respan.ai/api/v2/traces',
    headers: {
        'Authorization': 'Bearer YOUR_RESPAN_API_KEY',
    },
});

const sdk = new NodeSDK({
    traceExporter: exporter,
});

sdk.start();
```

--------------------------------

### Get Length of List or String with Jinja

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/filters-in-jinja-templates

The `length` filter returns the number of items in a list or the number of characters in a string. It's useful for conditional logic or displaying counts.

```jinja
{{ ["apple", "banana", "cherry"] | length }}  →  3
```

--------------------------------

### OpenAI SDK Integration

Source: https://www.respan.ai/docs/documentation/features/gateway/gateway-quickstart

Demonstrates how to configure the OpenAI SDK to use the Respan AI Gateway as its base URL and authenticate with an API key.

```APIDOC
## OpenAI SDK Integration

### Description
Configure the OpenAI SDK to point to the Respan API endpoint and use your Respan API key for authentication.

### Method
```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.respan.ai/api/",
    api_key="YOUR_RESPAN_API_KEY",
)

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)
```
```

--------------------------------

### Deploy Existing Version via API

Source: https://www.respan.ai/docs/documentation/features/prompt-management/advanced

Deploy an existing prompt version programmatically using the Update Version API. Set `deploy: true` to make a specific version live.

```APIDOC
## Deploy Existing Version via API

To deploy an existing version, use the [Update Version API](/docs/apis/prompts/api-prompts-prompt-id-versions-version) with `deploy: true`:

### Request Example (Python)

```python
url = "https://api.respan.ai/api/prompts/<prompt_id>/versions/<version_id>/"
data = {"deploy": True}

response = requests.patch(url, headers=headers, json=data)
```
```

--------------------------------

### OTLP Endpoint Configuration (Environment Variables)

Source: https://www.respan.ai/docs/documentation/features/tracing/spans

Configure your OpenTelemetry exporter to send traces to Respan by setting these environment variables. Ensure your Respan API key is correctly substituted.

```bash
OTEL_EXPORTER_OTLP_ENDPOINT="https://api.respan.ai/api"
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_RESPAN_API_KEY"
OTEL_EXPORTER_OTLP_PROTOCOL="http/json"
```

--------------------------------

### JavaScript AI Agent with Respan Tracing

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/monitor-an-ai-agent-in-production

Instrument a JavaScript AI agent using Respan's SDK for workflows and tasks. This example shows how to set up the telemetry client and wrap asynchronous operations.

```JavaScript
import { RespanTelemetry } from '@respan/tracing';
import OpenAI from 'openai';

const respanAi = new RespanTelemetry({
    apiKey: process.env.RESPAN_API_KEY || "",
    appName: 'support-agent'
});
const openai = new OpenAI();

async function supportAgent(userMessage: string, customerId: string) {
    return await respanAi.withWorkflow(
        { name: 'support_agent' },
        async () => {
            return await respanAi.withRespanSpanAttributes(
                async () => {
                    // Step 1: Plan
                    const planResult = await respanAi.withTask(
                        { name: 'plan' },
                        async () => {
                            const completion = await openai.chat.completions.create({
                                model: 'gpt-4o-mini',
                                messages: [
                                    { role: 'system', content: 'You are a helpful assistant.' },
                                    { role: 'user', content: userMessage },
                                ],
                            });
                            return completion.choices[0].message;
                        }
                    );

                    // Step 2: Synthesize
                    const answer = await respanAi.withTask(
                        { name: 'synthesize' },
                        async () => {
                            const completion = await openai.chat.completions.create({
                                model: 'gpt-4o-mini',
                                messages: [
                                    { role: 'system', content: 'Provide a helpful answer.' },
                                    { role: 'user', content: userMessage },
                                ],
                            });
                            return completion.choices[0].message.content;
                        }
                    );
                    return answer;
                },
                {
                    customer_identifier: customerId,
                    metadata: { agent: 'support', version: 'v1' },
                }
            );
        }
    );
}

// Example usage (assuming you have userMessage and customerId defined)
// supportAgent('How can I get started with Respan?', 'user_123').then(console.log);

```

--------------------------------

### Python AI Agent with Respan Tracing

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/monitor-an-ai-agent-in-production

Instrument a Python AI agent using Respan decorators for workflows, tasks, and tools. This example shows how to define and execute a support agent that uses tools.

```Python
from openai import OpenAI
from respan_tracing.decorators import workflow, task, agent, tool
from respan_tracing.main import RespanTelemetry
from respan_tracing.contexts.span import respan_span_attributes
import json

k_tl = RespanTelemetry()
client = OpenAI()

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "search_docs",
            "description": "Search the knowledge base",
            "parameters": {
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"],
            },
        },
    }
]


@tool(name="search_docs")
def search_docs(query: str) -> str:
    """Simulated knowledge base search."""
    return f"Found 3 results for '{query}': [doc1, doc2, doc3]"


@task(name="plan")
def plan(user_message: str):
    """Agent decides what to do."""
    completion = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": "You are a helpful assistant. Use tools when needed."},
            {"role": "user", "content": user_message},
        ],
        tools=TOOLS,
    )
    return completion.choices[0].message


@task(name="synthesize")
def synthesize(user_message: str, tool_results: list[str]):
    """Generate final answer from tool results."""
    context = "\n".join(tool_results)
    completion = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": f"Answer using this context:\n{context}"},
            {"role": "user", "content": user_message},
        ],
    )
    return completion.choices[0].message.content


@workflow(name="support_agent")
def support_agent(user_message: str, customer_id: str):
    with respan_span_attributes(
        respan_params={
            "customer_identifier": customer_id,
            "metadata": {"agent": "support", "version": "v1"},
        }
    ):
        # Step 1: Plan
        plan_result = plan(user_message)

        # Step 2: Execute tools
        tool_results = []
        if plan_result.tool_calls:
            for tool_call in plan_result.tool_calls:
                args = json.loads(tool_call.function.arguments)
                result = search_docs(**args)
                tool_results.append(result)

        # Step 3: Synthesize
        if tool_results:
            answer = synthesize(user_message, tool_results)
        else:
            answer = plan_result.content

    return answer


# Run it
result = support_agent("How do I set up tracing?", customer_id="user_789")
print(result)
```

--------------------------------

### Add MCP Server with API Key (Codex CLI)

Source: https://www.respan.ai/docs/documentation/get-started/mcp

Configure the Codex CLI to connect to the Respan MCP server using an API key. The configuration is stored in ~/.codex/config.toml. Replace YOUR_RESPAN_API_KEY with your actual key.

```toml
[mcp_servers.respan]
enabled = true
url = "https://mcp.respan.ai/mcp"

[mcp_servers.respan.http_headers]
Authorization = "Bearer YOUR_RESPAN_API_KEY"
```

--------------------------------

### TypeScript: Use Structured Output with Anthropic via OpenAI SDK

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/how-to-structure-llm-output-with-anthropic-models

Utilize the OpenAI TypeScript SDK to interact with Anthropic models for structured output. This example uses Zod for schema definition and validation.

```typescript
import { OpenAI } from "openai";
import { zodResponseFormat } from "openai/helpers/zod";
import { z } from "zod";

const CalendarEvent = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const client = new OpenAI({
  baseURL: "https://api.respan.ai/api",
  apiKey: "YOUR_RESPAN_API_KEY",
});

const response = await client.chat.completions
  .create({
    messages: [{ role: "user", content: "Say this is a test" }],
    model: "claude-3-5-sonnet-20240620", // any anthropic model
    response_format: zodResponseFormat(CalendarEvent, "event")
  })
  .asResponse();

console.log(await response.json());
```

--------------------------------

### Add MCP Server with Whitelisted Tools (Claude)

Source: https://www.respan.ai/docs/documentation/get-started/mcp

Configure the Claude CLI to connect to the Respan MCP server, specifying a whitelist of allowed tools using the Respan-Enabled-Tools header. Replace YOUR_RESPAN_API_KEY with your actual key.

```bash
claude mcp add \
  --transport http \
  --header "Authorization: Bearer YOUR_RESPAN_API_KEY" \
  --header "Respan-Enabled-Tools: list_logs,get_log_detail,list_traces,get_trace_tree" \
  respan \
  https://mcp.respan.ai/mcp
```

--------------------------------

### Call Prompt with Legacy Schema v1 (TypeScript)

Source: https://www.respan.ai/docs/documentation/features/prompt-management/prompt-management-quickstart

This TypeScript example uses the OpenAI SDK with legacy prompt schema v1. The `@ts-expect-error` comment is included as per the source, and `override: true` is used.

```TypeScript
const response = await client.chat.completions.create({
    messages: [{ role: "user", content: "placeholder" }],
    model: "gpt-4o-mini",
    // @ts-expect-error
    prompt: {
        prompt_id: "YOUR_PROMPT_ID",
        variables: {
            task_description: "Square a number",
            specific_library: "math"
        },
        override: true
    }
});
```

--------------------------------

### Fetch Prompt Versions with Respan SDK (Python)

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/a-b-test-prompts-in-production

Use this Python function to fetch specific prompt versions from Respan at runtime. Ensure you have the 'requests' library installed and replace 'YOUR_RESPAN_API_KEY' with your actual API key.

```Python
from openai import OpenAI
import requests

client = OpenAI(
    base_url="https://api.respan.ai/api/",
    api_key="YOUR_RESPAN_API_KEY",
)

def get_prompt(prompt_name, version=None):
    """Fetch a prompt from Respan."""
    headers = {"Authorization": "Bearer YOUR_RESPAN_API_KEY"}
    params = {"prompt_name": prompt_name}
    if version:
        params["version"] = version
    resp = requests.get(
        "https://api.respan.ai/api/prompts/",
        headers=headers,
        params=params,
    )
    return resp.json()
```

--------------------------------

### Python: Use Structured Output with Anthropic via OpenAI SDK

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/how-to-structure-llm-output-with-anthropic-models

Call Anthropic models through the OpenAI SDK to Respan.ai, specifying the JSON schema in the request format. Ensure you have the OpenAI Python SDK installed.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.respan.ai/api/",
    api_key="YOUR_RESPAN_API_KEY",
)

response = client.chat.completions.create(
    model="claude-3-5-sonnet-20240620", # any anthropic model
    messages=[
        {"role": "user", "content": "Tell me a long story"}
    ],
    response_format={json_schema: {YOUR_JSON_SCHEMA}}
)
```

--------------------------------

### Initialize Respan Tracing with LlamaIndex

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/trace-a-rag-pipeline

Initialize Respan Telemetry and enable LlamaIndex auto-instrumentation. Configure LlamaIndex settings, including the LLM model.

```python
from respan_tracing import RespanTelemetry, OpenInference
from respan_tracing.decorators import workflow
from llama_index.core import VectorStoreIndex, Document, Settings
from llama_index.llms.openai import OpenAI as LlamaOpenAI

# Initialize tracing with LlamaIndex auto-instrumentation
telemetry = RespanTelemetry()
OpenInference.llamaindex()

# Configure LlamaIndex
Settings.llm = LlamaOpenAI(model="gpt-4o-mini")

# Create documents and build index
documents = [
    Document(text="Respan supports 250+ LLM models through a unified API gateway."),
    Document(text="Traces organize logs into hierarchical workflows with parent-child spans."),
    Document(text="Evaluators can be LLM-based, code-based, or human reviewers."),
    Document(text="Automations run evaluators on production logs in real-time."),
]
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()


@workflow(name="rag_pipeline")
def rag_pipeline(query: str):
    """RAG pipeline - LlamaIndex auto-instruments all internal steps."""

```

--------------------------------

### Switch OpenCode Models

Source: https://www.respan.ai/docs/documentation/resources/cookbooks/proxy-coding-agents

Run OpenCode with different models by specifying the model name with the `-m` flag. This allows you to test or use various models available through the gateway.

```bash
opencode run -m "openai/gpt-5.5" "..."
opencode run -m "openai/claude-sonnet-4-5-20250929" "..."
opencode run -m "openai/gemini-2.5-flash" "..."
```

--------------------------------

### Use AI Gateway with Customer Parameters (Python)

Source: https://www.respan.ai/docs/documentation/features/customer-identifier

This Python snippet shows how to configure the OpenAI client to use the Respan API gateway and include customer parameters for analytics. Replace 'YOUR_RESPAN_API_KEY' with your actual API key.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.respan.ai/api/",
    api_key="YOUR_RESPAN_API_KEY",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Tell me a story"}],
    extra_body={
        "customer_params": {
            "customer_identifier": "customer_1",
            "name": "Hendrix Liu",
            "email": "hendrix@respan.ai"
        }
    }
)
```

--------------------------------

### Anthropic SDK Integration

Source: https://www.respan.ai/docs/documentation/features/gateway/gateway-quickstart

Shows how to initialize the Anthropic SDK with the Respan AI Gateway's base URL for Anthropic models.

```APIDOC
## Anthropic SDK Integration

### Description
Initialize the Anthropic SDK to use the Respan API endpoint for Anthropic models, providing your API key.

### Method
```python
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.respan.ai/api/anthropic/",
    api_key="YOUR_RESPAN_API_KEY",
)

message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)
```
```

--------------------------------

### Initialize Respan with Vercel AI (TypeScript)

Source: https://www.respan.ai/docs/documentation/features/tracing/traces

Initialize Respan with the Vercel AI instrumentor and generate text.

```typescript
import { Respan } from "@respan/respan";
import { VercelAIInstrumentor } from "@respan/instrumentation-vercel";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

const respan = new Respan({ instrumentations: [new VercelAIInstrumentor()] });
await respan.initialize();

const result = await generateText({
  model: openai("gpt-5.4"),
  prompt: "Tell me a joke about AI.",
  experimental_telemetry: { isEnabled: true },
});
console.log(result.text);
await respan.flush();
```
Tokens:
Raw