Skip to content

Quickstart

This guide takes you from zero to a visible trace in the Orq dashboard. Estimated time: 10 minutes.

Prerequisites

  • Python 3.9+ or Node.js 18+
  • An Orq account (free at getorqai.com/app/register)
  • An OpenAI or Anthropic API key (or any LLM you are already calling)

Step 1: Install the SDK

Python 
pip install orq-sdk
TypeScript / Node 
npm install @orq/sdk

Step 2: Initialise with your API key

Find your project API key in the Orq dashboard under Settings. Initialise the SDK once, before any LLM calls run.

Python 
import orq

orq.init(api_key="orq_live_xxxxxxxxxxxxxxxx")
Keep your API key out of source control. Use an environment variable: api_key=os.environ["ORQ_API_KEY"].

Step 3: Instrument your agent

Wrap your agent entry point with the @orq.trace decorator. Orq will automatically capture every LLM call, tool invocation, and sub-agent handoff as a span inside the trace.

Python 
import orq
from openai import OpenAI

orq.init(api_key=os.environ["ORQ_API_KEY"])
client = OpenAI()

@orq.trace(name="answer-question")
def answer(user_question: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": user_question},
        ],
    )
    return response.choices[0].message.content

result = answer("What is the capital of the Netherlands?")
print(result)
The SDK wraps the OpenAI and Anthropic clients automatically when you call orq.init(). You do not need to change any OpenAI client calls.

Step 4: Run your agent and view the trace

Run your script. After the first call completes, open the Orq dashboard and navigate to Traces. You should see a trace named answer-question with one LLM span showing the model, latency, token counts, and the full prompt and completion.

Step 5: Add eval metrics

Traces are useful. Scores over time are what let you gate releases. In the Orq dashboard, open your project and go to Eval Metrics. Add a metric, for example Coherence with a threshold of 80. Orq will start scoring every new trace against that metric automatically.

Next steps