Quickstart: instrument your first agent in 5 minutes

npm install @zespan/sdk openai

pip install zespan openai

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());

import os

import zespan

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

import openai  # import after patching

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)

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

​

Explore the demo

• Signed in: choose Explore the demo in the account menu (bottom of the sidebar), or on the Explore the demo button next to the sample-trace button on an empty Overview and in the setup wizard. Pages that have nothing to show yet can also offer See it on demo data, which opens that same page inside the demo.
• Signed out: go to app.zespan.com/demo for a short read-only guest session.

​

What you see in the demo

• It is read only. You join as a viewer, so you can look at everything and change nothing. Buttons that would create or run something (for example Author a policy, Generate evidence pack, New dataset, Create alert, Apply fix) are not shown as main buttons there: a guest sees a Sign up to … link in their place, and a signed-in person who joined the demo sees a short Read-only demo note. Reading and navigation are never hidden. Everyone who opens the demo sees the same sample data, and nothing you do there reaches your own projects.
• You see yourself and a fictional team. The demo’s Team page, audit log and member lists show your own name and email, plus three made-up teammates. Other real people who have opened the demo never appear to you, and you never appear to them.
• It stays out of your way. The demo appears in the organization switcher as Demo (read only), below your own organizations. It does not count toward your limit of 3 organizations, and it never becomes your default organization after you sign in. A banner at the top of every demo page says so and has Back to my project, which returns you to the last project you had open.
• The Issues page shows a mix of kinds, each proven from its own spans. When the functional checks are switched on for the demo, next to the demo story’s issue it has thirteen more, all made from recorded runs of four fictional agents (CustomerSupportAgent, RefundAgent, ReportsAgent and CampaignAgent) and found by the same checks every project uses, not written by hand. Each has a Type: Technical (a 429 rate-limit retry storm, a provider 503, a context that was too long, a model call that timed out), Functional (a tool called that the agent was never given, a total that is not the sum of its lines) and a domain pack (Support: an order number that is not the one the lookup returned, a refund promised in 24 hours when the policy tool says 5 days; AI product: a card number in a reply; BI: a revenue total that is not the sum of the returned rows, “no data” said when rows came back; Martech: the same campaign created twice, a click-through rate that is not the one the analytics tool returned). Open any of them for its cause, fix and prevention, each from the check’s own wording. An issue appears only if the check proved it at its strongest level; a weaker finding is left out, and checks that need an AI judge are not run in the demo. With the functional checks switched off, only the four Technical ones are shown. Healthy runs of the same agents sit beside them, and none of them is flagged. See Issues → Kinds of issue.
• ZespanPilot answers sample questions only. Pilot is in the demo’s sidebar and opens from Ask Pilot, with a list of starter questions (why agent success dropped, what caused the delegation loop, how to prevent it, what to set up first, issues versus incidents, why a page is empty, what a span is). Each answer is written in advance from the demo’s own data, so it is the same for everyone and costs no AI usage. Anything else you type gets “Sign up or open your project to ask your own.” Demo conversations are not saved, so nobody can see anyone else’s questions.
• Policies, compliance and prevention are filled in. The demo’s Policies page lists one applied policy, “Refund agent: keep payment data out of replies”, with the guardrail it created, the test it was checked against (the demo’s recorded traffic from the last 7 days) and its apply record. When prevention drafts are switched on for the demo, it also lists a policy Zespan drafted for the demo story, “Stop repeated identical tool calls” (a repeat guard for RefundAgent, tested on RefundAgent’s own healthy runs and the loop itself). It is a draft: nothing runs until a person applies it, and once applied it starts at dryrun, which only records what it would stop. You find it under Proposed by Zespan and in the Prevent part of the story’s issue page. Compliance has one SOC 2 evidence pack for the last 30 days, and the Audit log shows the matching entries. Every name in them is the fictional team, and all of it is recreated each day with current dates. See Policies, Evidence packs and Audit log.

​

The demo story

​

SDK initialization options

​

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.