Quickstart: instrument your first agent in 5 minutes
Send your first agent trace to LumiqTrace by wrapping your LLM client or agent framework with the SDK. No manual instrumentation required — two lines of setup.
Use this file to discover all available pages before exploring further.
LumiqTrace instruments your agents and LLM calls by wrapping your existing clients. Once initialized, every agent run, tool call, and model interaction is automatically captured and sent to your project’s dashboard. This guide walks through the setup using Node.js and OpenAI, with a Python alternative included.
1
Create your account and project
Go to app.lumiqtrace.com and sign up for a free account. After verifying your email, you’ll be taken through the onboarding wizard:
Create an organization — your billing workspace.
Create a project — an isolated container for agent events. Name it after the application you’re instrumenting (e.g. my-support-agent-production).
Copy your API key — shown once after project creation. It starts with lqt_ followed by 64 hex characters.
Your API key is shown in full only once. If you lose it, rotate it from Settings → API Keys — the old key remains valid for 24 hours during rollover.
2
Install the SDK
TypeScript / Node.js
Python
npm install @lumiqtrace/sdk openai
pip install lumiqtrace openai
3
Initialize and wrap your client
Add the following at the entry point of your application — before any agent or LLM calls are made.
TypeScript / Node.js
Python
import { lumiqtrace } from "@lumiqtrace/sdk";import OpenAI from "openai";lumiqtrace.init({ apiKey: process.env.LUMIQTRACE_API_KEY!, environment: "production",});const openai = lumiqtrace.wrapOpenAI(new OpenAI());
lumiqtrace.init() initializes the global SDK client. wrapOpenAI() patches the OpenAI client so all calls — and every agent step that goes through it — are automatically traced. Your existing code is unchanged.
import lumiqtracelumiqtrace.init( api_key="lqt_your_key_here", environment="production",)lumiqtrace.patch_openai()import openai # import after patching
lumiqtrace.patch_openai() monkey-patches both sync and async openai.chat.completions.create. Exceptions are always re-raised so your existing error handling is unaffected.
Replace lqt_your_key_here with the API key from the dashboard. The SDK logs a warning if the key format is invalid.
4
Run your agent or make an LLM call
Use your client exactly as you would normally. The SDK captures everything — model name, input and output tokens, cost, latency, tool calls, streaming TTFT, and finish reason.
TypeScript / Node.js
Python
Just an LLM call
import { lumiqtrace, withAgent } from "@lumiqtrace/sdk";import OpenAI from "openai";lumiqtrace.init({ apiKey: process.env.LUMIQTRACE_API_KEY!, environment: "production" });const openai = lumiqtrace.wrapOpenAI(new OpenAI());// Wrap as an agent to see the full agent traceawait withAgent( { name: "SupportAgent", role: "specialist", tools: [{ name: "lookup_order", description: "Look up an order by ID" }], }, async (agent) => { agent.logPlan(["Understand request", "Look up order", "Draft response"]); const order = await agent.traceTool( "lookup_order", { id: "ORD-123" }, () => Promise.resolve({ status: "delivered", total: 49.99 }) ); const response = await openai.chat.completions.create({ model: "gpt-4o", messages: [ { role: "system", content: "You are a helpful support agent." }, { role: "user", content: `Order ${order}: help me with my refund.` }, ], }); console.log(response.choices[0].message.content); });
import lumiqtracefrom lumiqtrace import with_agentimport openailumiqtrace.init(api_key="lqt_your_key_here", environment="production")lumiqtrace.patch_openai()client = openai.OpenAI()with with_agent( name="SupportAgent", role="specialist", tools=[{"name": "lookup_order", "description": "Look up an order"}],) as agent: agent.log_plan(["Understand request", "Look up order", "Draft response"]) order = agent.trace_tool( "lookup_order", {"id": "ORD-123"}, lambda: {"status": "delivered", "total": 49.99}, ) response = client.chat.completions.create( model="gpt-4o", messages=[ {"role": "system", "content": "You are a helpful support agent."}, {"role": "user", "content": f"Order {order}: help with refund."}, ], ) print(response.choices[0].message.content)
If you’re not using agents yet, a bare LLM call is traced automatically:
You’ll still see the full span: model, tokens, cost, latency, and finish reason.
5
View your trace in the dashboard
Open app.lumiqtrace.com and navigate to your project. Within a few seconds you should see your trace in the Traces view. Click any row to open the flame graph — each bar is a span (agent scope, tool call, LLM call) with full cost and latency breakdown.
If no trace appears after 15 seconds, check that your API key is correct and that your process did not exit before the SDK flushed. Call await lumiqtrace.getClient().flush() (TypeScript) or lumiqtrace.flush() (Python) at the end of your script to force an immediate flush. See the Serverless guide if running in Lambda or Vercel.
