> ## Documentation Index > Fetch the complete documentation index at: https://docs.zespan.com/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart: instrument your first agent in 5 minutes > Send your first agent trace to Zespan by wrapping your LLM client or agent framework with the SDK. No manual instrumentation required — two lines of setup. 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. Go to [app.zespan.com](https://app.zespan.com) and sign up for a free account. After verifying your email, you'll be taken through the onboarding wizard: 1. **Create an organization** — your billing workspace. 2. **Create a project** — an isolated container for agent events. Name it after the application you're instrumenting (e.g. `my-support-agent-production`). 3. **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. ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} npm install @zespan/sdk openai ``` ```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} pip install zespan openai ``` Add the following at the entry point of your application — before any agent or LLM calls are made. ```typescript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} 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. ```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} 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. 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 theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} 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); } ); ``` ```python theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} 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: ```typescript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}} 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. Open [app.zespan.com](https://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](/guides/serverless) if running in Lambda or Vercel. ## SDK initialization options | 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 `zespan.wrapAnthropic(new Anthropic())` `zespan.wrapGoogle(new GoogleGenerativeAI(key))` `zespan.wrapBedrock(new BedrockRuntimeClient())` `zespan.wrapMistral(new Mistral())` `zespan.wrapGroq(new Groq())` `zespan.wrapOpenAI(new OpenAI({ baseURL: "..." }))` Drop-in proxy — point your SDK at the LiteLLM base URL. Full chain, agent executor, and retriever tracing via callback handler. Multi-agent tracing with `instrumentADK`, `wrapADKRunner`, or `wrapADKAgent`. Crew and task tracing via the Zespan CrewAI integration. Multi-agent conversation and tool tracing for AutoGen / AG2. Query engine, retriever, and agent tracing via callback handler. `generateText`, `streamText`, and `generateObject` traced automatically. Pipeline component and retriever tracing for Haystack 2.x. Kernel function and planner tracing for Microsoft Semantic Kernel.