Orq.ai Documentation - AI Gateway & LLM Collaboration Platform

Already have an agent? Add a few lines of OpenTelemetry setup to start seeing full trace visibility and cost tracking in orq.ai.

Create your orq.ai account

Get your API key

Open Organization > API Keys in the AI Studio. Click Create API Key, give it a name, and copy it.Then open a terminal and run the command below, replacing your-api-key-here with the copied key. The code samples in the next steps read it from this environment variable.

export ORQ_API_KEY="your-api-key-here"

Connect your framework

Install the dependencies:

pip install orq-ai-sdk langchain langchain-openai langgraph

Call setup() once before defining the graph. Every node, tool call, and LLM step is then captured and shipped to orq.ai.

from orq_ai_sdk.langchain import setup

setup()

from typing import Annotated, Literal, TypedDict
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from langchain.tools import tool
from langgraph.graph import StateGraph, START
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode

class State(TypedDict):
    messages: Annotated[list, add_messages]

@tool
def get_weather(location: str) -> str:
    """Get weather for a location."""
    data = {"tokyo": "Sunny, 22°C", "paris": "Cloudy, 15°C", "new york": "Rainy, 18°C"}
    return data.get(location.lower(), f"No data for {location}")

tools = [get_weather]
llm   = ChatOpenAI(model="gpt-4o-mini", temperature=0).bind_tools(tools)

def weather_agent(state: State):
    return {"messages": [llm.invoke(state["messages"])]}

def route(state: State) -> Literal["tools", "__end__"]:
    last = state["messages"][-1]
    return "tools" if hasattr(last, "tool_calls") and last.tool_calls else "__end__"

graph = StateGraph(State)
graph.add_node("weather_agent", weather_agent)
graph.add_node("tools", ToolNode(tools))
graph.add_edge(START, "weather_agent")
graph.add_conditional_edges("weather_agent", route)
graph.add_edge("tools", "weather_agent")

app = graph.compile()
result = app.invoke({"messages": [HumanMessage(content="Weather in Tokyo?")]})
print(result["messages"][-1].content)

See the LangGraph Observability guide for streaming, tool tracing, and Control Tower asset capture.

Install the dependencies:

pnpm add ai@latest @vercel/otel @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/instrumentation @opentelemetry/resources @opentelemetry/semantic-conventions @ai-sdk/openai

Set the environment variables:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://my.orq.ai/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ORQ_API_KEY}"
export OTEL_RESOURCE_ATTRIBUTES="service.name=vercel-ai-app,service.version=1.0.0"
export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"

Create an instrumentation.js file at the root of your project:

TypeScript

// instrumentation.js
import { registerOTel, OTLPHttpJsonTraceExporter } from '@vercel/otel';

export function register() {
  registerOTel({
    serviceName: 'your-project-name',
    traceExporter: new OTLPHttpJsonTraceExporter({
      url: 'https://my.orq.ai/v2/otel/v1/traces',
      headers: {
        'Authorization': `Bearer ${process.env.ORQ_API_KEY}`,
      },
    }),
  });
}

Then enable telemetry on each generation call:

TypeScript

// index.js
import { register } from './instrumentation.js';
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

register();

const result = await generateText({
  model: openai("gpt-4.1"),
  prompt: "Write a short story about a robot",
  experimental_telemetry: {
    isEnabled: true,
  },
});

See the Vercel AI Observability guide for streaming, structured output, and agent detection examples.

Install the dependencies:

pip install pydantic-ai openai opentelemetry-sdk opentelemetry-exporter-otlp 'logfire>=4'

Set the environment variables:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://my.orq.ai/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ORQ_API_KEY}"
export OTEL_RESOURCE_ATTRIBUTES="service.name=pydantic-ai-app,service.version=1.0.0"
export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"

Configure logfire and instrument Pydantic AI before running the agent:

Python

import logfire
from pydantic_ai import Agent

logfire.configure(
    service_name='orq-traces',
    send_to_logfire=False,
    metrics=False,
)

logfire.instrument_pydantic_ai()

agent = Agent('openai:gpt-4o-mini')
result = agent.run_sync('What is the capital of France?')
print(result.output)

See the Pydantic AI Observability guide for streaming, structured output, and tool tracing.

Install the dependencies:

pip install opentelemetry-sdk opentelemetry-instrumentation opentelemetry-exporter-otlp openai-agents orq-ai-sdk

Set the environment variables:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://my.orq.ai/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ORQ_API_KEY}"
export OTEL_RESOURCE_ATTRIBUTES="service.name=openai-agents-app,service.version=1.0.0"
export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"

Instrument before running any agents:

Python

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from orq_ai_sdk.openai_agents_instrumentation import OpenAIAgentsInstrumentor
from agents import Agent, Runner

# Set up OpenTelemetry
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))

# Instrument OpenAI agents with Orq.ai
OpenAIAgentsInstrumentor().instrument(tracer_provider=tracer_provider)

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)

All subsequent Runner.run_sync() / Runner.run() calls are automatically traced.

See the OpenAI Agents Observability guide for multi-agent handoff tracing and Control Tower asset capture.

Install the dependencies:

pip install agno openai opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp-proto-http openinference-instrumentation-agno

Set the environment variables:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://my.orq.ai/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${ORQ_API_KEY}"
export OTEL_RESOURCE_ATTRIBUTES="service.name=agno-app,service.version=1.0.0"
export OPENAI_API_KEY="<YOUR_OPENAI_API_KEY>"

Instrument before creating your agent:

Python

from opentelemetry import trace as trace_api
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from openinference.instrumentation.agno import AgnoInstrumentor
from agno.agent import Agent
from agno.models.openai import OpenAIChat

tracer_provider = TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace_api.set_tracer_provider(tracer_provider)

AgnoInstrumentor().instrument(tracer_provider=tracer_provider)

agent = Agent(model=OpenAIChat(id="gpt-4o-mini"))
print(agent.run("What is the capital of France?").content)

See the Agno Observability guide for tool tracing and multi-agent examples.

View your traces

Run the agent and open Traces in the AI Studio. Every request will appear with model, latency, token counts, and cost. For agentic frameworks, individual tool calls and steps appear as child spans.

Analyze traces with MCP

Install the Orq MCP server in the editor or AI assistant, then ask the coding assistant:

Show me the 10 slowest traces from the last 24 hours and explain what might be causing the latency

The assistant queries the Orq MCP and returns an analysis like this:

Troubleshooting

Authentication error: 401 Unauthorized

Confirm the variable is set: echo $ORQ_API_KEY
Verify the key is active under Organization > API Keys
Confirm the key is passed in the Authorization: Bearer header on your OTLP exporter, not as a query parameter

Traces not appearing in the Studio

Confirm your OTLP endpoint is set to https://my.orq.ai/v2/otel (or /v2/otel/v1/traces for exporters that require the full path)
Check that the workspace in your API key matches the AI Studio workspace you are viewing
Traces can take a few seconds to appear, wait 10 seconds and refresh

Annotate your traces

Label and review spans to build high-quality evaluation datasets from real production traffic.

Set up analytics

Track cost, latency, error rates, and token usage across models and deployments over time.

Run your first experiment

Use your traced data as a baseline to compare prompts, models, and configurations side by side.

Build your first agent

Build and deploy a native orq.ai agent with tools, memory, and full AI Studio management.

​Create your orq.ai account

​Get your API key

​Connect your framework

​View your traces

​Analyze traces with MCP

​Troubleshooting

Annotate your traces

Set up analytics

Run your first experiment

Build your first agent

Create your orq.ai account

Get your API key

Connect your framework

View your traces

Analyze traces with MCP

Troubleshooting