All documentation

Start here / guide 01

Start with your first trace

Install Tracify, send one real agent run, and verify it in the trace viewer.

Copy or share.

Start with your first trace

Tracify connects the model calls, tool calls, prompts, costs, failures, and evaluation signals inside an agent run. This guide takes you from an empty project to one useful trace in the dashboard. Plan on about five minutes.

You need a Tracify project and its API key. The key belongs to one region, EU or US, so create the project in the region where you want your data stored. See Choose a Tracify Cloud region if you are unsure.

1. Install the SDK

bash
npm install tracify-sdk

Using Python? Install tracify-sdk with pip instead and follow the Python SDK guide for the matching calls.

bash
pip install tracify-sdk

2. Set your API key

Keep the key in a server-side environment variable. The SDK reads TRACIFY_API_KEY automatically, so you do not need to pass it in code.

bash
export TRACIFY_API_KEY=tracify_sk_live_...

Never put a project API key in browser code. If the variable is missing, the TypeScript SDK prints a TRACIFY_API_KEY is not set warning and records nothing, and the Python SDK raises a ValueError when the client is created.

3. Wrap one run

traceAgent turns every call of your function into one trace. Each call gets a new run, and everything you record inside it hangs from that run.

ts
import { traceAgent, span } from "tracify-sdk";

export const answer = traceAgent(
  async (question: string) => {
    const docs = await span("search-docs", () => searchDocs(question), {
      type: "tool",
      input: question,
    });

    return span(
      "chat",
      async (step) => {
        const reply = await callModel(question, docs);
        step.set({
          model: "your-model-id",
          inputTokens: reply.usage.input,
          outputTokens: reply.usage.output,
        });
        return reply.text;
      },
      { type: "llm", input: question },
    );
  },
  { name: "support-agent", environment: "development", release: "quickstart" },
);

await answer("Where is my order?");

Replace searchDocs and callModel with your own functions. If you already use the OpenAI or Anthropic SDK, you can skip the manual span calls and wrap the client once instead. See OpenAI, Anthropic and LangGraph.

4. Verify the result

Open the project dashboard and select the newest run. A healthy first trace has:

  • a root run named after your agent,
  • one child span per span you recorded, in the order they ran,
  • timing on every span, plus the model and token counts you set,
  • the input and output of each step, with obvious secrets already removed.

If the run does not appear within a minute, open Troubleshoot your first trace.

What to do next

NextTroubleshoot your first trace