Quickstart: instrument your first agent in 5 minutes

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

Create your account and project

Go to app.zespan.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 zsp_ 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.

Install the SDK

TypeScript / Node.js
Python

npm install @zespan/sdk openai

pip install zespan openai

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 { zespan } from "@zespan/sdk";
import OpenAI from "openai";

zespan.init({
  apiKey: process.env.ZESPAN_API_KEY!,
  environment: "production",
});

const openai = zespan.wrapOpenAI(new OpenAI());

zespan.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 os

import zespan

zespan.init(
    api_key=os.environ["ZESPAN_API_KEY"],
    environment="production",
)
zespan.patch_openai()

import openai  # import after patching

zespan.patch_openai() monkey-patches both sync and async openai.chat.completions.create. Exceptions are always re-raised so your existing error handling is unaffected.

Set the ZESPAN_API_KEY environment variable to the API key from the dashboard. The SDK logs a warning if the key format is invalid.

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 { zespan, withAgent } from "@zespan/sdk";
import OpenAI from "openai";

zespan.init({ apiKey: process.env.ZESPAN_API_KEY!, environment: "production" });
const openai = zespan.wrapOpenAI(new OpenAI());

// Wrap as an agent to see the full agent trace
await 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 os

import zespan
from zespan import with_agent
import openai

zespan.init(api_key=os.environ["ZESPAN_API_KEY"], environment="production")
zespan.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:

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Explain agent observability." }],
});

You’ll still see the full span: model, tokens, cost, latency, and finish reason.

View your trace in the dashboard

Open app.zespan.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 zespan.getClient().flush() (TypeScript) or zespan.flush() (Python) at the end of your script to force an immediate flush. See the Serverless guide if running in Lambda or Vercel.

SDK initialization options

TypeScript
Python

Option	Type	Default	Description
`apiKey`	`string`	Required	Your project API key. Must start with `zsp_`.
`environment`	`string`	`"production"`	Tags every event with an environment label.
`storePrompts`	`boolean`	`true`	Store prompt and completion text. PII redaction applied before transmission. Set to `false` to disable.
`sampleRate`	`number`	`1.0`	Fraction of calls to trace (0.0–1.0).
`redactKeys`	`string[]`	Common PII keys	Tag/metadata keys whose values are redacted before sending.
`debug`	`boolean`	`false`	Log SDK activity to the console.
`batchSize`	`number`	`50`	Events to collect before flushing.
`flushInterval`	`number`	`2000`	Milliseconds between automatic flushes.
`baseURL`	`string`	`https://api.zespan.com`	Override for self-hosted deployments.

Option	Type	Default	Description
`api_key`	`str`	Required	Your project API key.
`environment`	`str`	`"production"`	Environment label.
`store_prompts`	`bool`	`True`	Store prompt and completion text. PII redaction applied before transmission. Set to `False` to disable.
`sample_rate`	`float`	`1.0`	Fraction of calls to trace.
`redact_keys`	`list[str]`	Common PII keys	Keys to redact from tags/metadata.
`debug`	`bool`	`False`	Log flush activity to stdout.
`batch_size`	`int`	`50`	Events per flush.
`flush_interval`	`float`	`2.0`	Seconds between automatic flushes.
`base_url`	`str`	`https://api.zespan.com`	Override for self-hosted deployments.

Tracing other frameworks

Anthropic

zespan.wrapAnthropic(new Anthropic())

Google Gemini

zespan.wrapGoogle(new GoogleGenerativeAI(key))

AWS Bedrock

zespan.wrapBedrock(new BedrockRuntimeClient())

Mistral

zespan.wrapMistral(new Mistral())

Groq

zespan.wrapGroq(new Groq())

OpenRouter

zespan.wrapOpenAI(new OpenAI({ baseURL: "..." }))

LiteLLM

Drop-in proxy — point your SDK at the LiteLLM base URL.

LangChain

Full chain, agent executor, and retriever tracing via callback handler.

Google ADK

Multi-agent tracing with instrumentADK, wrapADKRunner, or wrapADKAgent.

CrewAI

Crew and task tracing via the Zespan CrewAI integration.

AutoGen

Multi-agent conversation and tool tracing for AutoGen / AG2.

LlamaIndex

Query engine, retriever, and agent tracing via callback handler.

Vercel AI SDK

generateText, streamText, and generateObject traced automatically.

Haystack

Pipeline component and retriever tracing for Haystack 2.x.

Semantic Kernel

Kernel function and planner tracing for Microsoft Semantic Kernel.

​SDK initialization options

​Tracing other frameworks

Anthropic

Google Gemini

AWS Bedrock

Mistral

Groq

OpenRouter

LiteLLM

LangChain

Google ADK

CrewAI

AutoGen

LlamaIndex

Vercel AI SDK

Haystack

Semantic Kernel

SDK initialization options

Tracing other frameworks