Quickstart

Install the SDK, wrap your agent, and see every step in the dashboard.

Prerequisites

A Veval account (dashboard.veval.dev)
A Veval API key. In the dashboard, go to Settings → API Keys.

Send your first trace

Install the SDK

dotnet add package Veval.Sdk

pip install veval-sdk

npm install @veval/sdk

Wrap a run

The simplest integration needs no LLM. Wrap any async operation with RunAsync and record a step with TrackStepAsync.

using Veval.Sdk;

var veval = new VevalSdk(new VevalOptions { ApiKey = "YOUR_API_KEY" });

var result = await veval.RunAsync("my-agent", async ctx =>
{
    var output = await ctx.TrackStepAsync("summarize", input: "hello world", async () =>
    {
        // replace with your real LLM call
        return "Hello, world!";
    });

    return output;
});

veval.Dispose();

import asyncio
from veval import VevalSdk, VevalOptions

veval = VevalSdk(VevalOptions(api_key="YOUR_API_KEY"))

async def main():
    async def my_agent(ctx):
        async def summarize():
            # replace with your real LLM call
            return "Hello, world!"

        return await ctx.track_step_async("summarize", "hello world", summarize)

    result = await veval.run_async("my-agent", my_agent)

asyncio.run(main())

import { VevalSdk } from "@veval/sdk";

const veval = new VevalSdk({ apiKey: "YOUR_API_KEY" });

const result = await veval.runAsync("my-agent", async (ctx) => {
  const output = await ctx.trackStepAsync("summarize", "hello world", async () => {
    // replace with your real LLM call
    return "Hello, world!";
  });
  return output;
});

Open the dashboard

Open dashboard.veval.dev. You’ll see a trace for my-agent with one step.

No trace in the dashboard? Look for a Veval: Sending trace failed warning in your console, such as status 401 for a wrong API key or 429 when your quota is used up. See Delivery failures.

Use the service pattern

For real agents, pass the execution context into your service class so every LLM call is tracked. This is the recommended pattern for production.

// Your agent service accepts VevalExecutionContext
public class MyAgentService(IVevalSdk veval, AnthropicClient claude)
{
    public async Task<string> ExecuteAsync(VevalExecutionContext ctx)
    {
        var answer = await ctx.TrackStepAsync("answer", ctx.Input, async handle =>
        {
            var response = await claude.Messages.CreateAsync(...);

            // attach LLM metadata to the step
            handle.SetMeta("type",       "llm");
            handle.SetMeta("model",      response.Model);
            handle.SetMeta("tokens_in",  response.Usage.InputTokens);
            handle.SetMeta("tokens_out", response.Usage.OutputTokens);
            handle.SetMeta("cost_usd",   ComputeCost(response.Usage));

            return response.Content[0].Text;
        });

        return answer;
    }
}

// Wire it up
var veval   = new VevalSdk(new VevalOptions { ApiKey = "YOUR_API_KEY" });
var service = new MyAgentService(veval, claude);

var result = await veval.RunAsync("my-agent", service.ExecuteAsync, input: userMessage);

# Your agent service accepts VevalExecutionContext
class MyAgentService:
    def __init__(self, anthropic):
        self._anthropic = anthropic

    async def execute_async(self, ctx):
        async def step(handle):
            response = await self._anthropic.messages.create(...)

            # attach LLM metadata to the step
            handle.set_meta("type",       "llm")
            handle.set_meta("model",      response.model)
            handle.set_meta("tokens_in",  response.usage.input_tokens)
            handle.set_meta("tokens_out", response.usage.output_tokens)
            handle.set_meta("cost_usd",   compute_cost(response.usage))

            return response.content[0].text

        return await ctx.track_step_async("answer", ctx.input, step)

# Wire it up
veval   = VevalSdk(VevalOptions(api_key="YOUR_API_KEY"))
service = MyAgentService(anthropic)

result = await veval.run_async("my-agent", service.execute_async, input=user_message)

// Your agent service accepts VevalExecutionContext
class MyAgentService {
  constructor(anthropic) {
    this.anthropic = anthropic;
  }

  async execute(ctx) {
    return await ctx.trackStepAsync("answer", ctx.input, async (handle) => {
      const response = await this.anthropic.messages.create({ ... });

      // attach LLM metadata to the step
      handle.setMeta("type",       "llm");
      handle.setMeta("model",      response.model);
      handle.setMeta("tokens_in",  response.usage.input_tokens);
      handle.setMeta("tokens_out", response.usage.output_tokens);
      handle.setMeta("cost_usd",   computeCost(response.usage));

      return response.content[0].text;
    });
  }
}

// Wire it up
const veval   = new VevalSdk({ apiKey: "YOUR_API_KEY" });
const service = new MyAgentService(anthropic);

const result = await veval.runAsync("my-agent", (ctx) => service.execute(ctx), userMessage);

Injecting IVevalSdk (the interface) lets you swap in VevalTestSdk in tests — no live LLM calls, no API cost. See Replay.

What’s next

Instrument your agent

Record metadata and tool calls.

Test with replay

Run your agent against recorded traces with no live LLM calls.

Run a scenario

Run your agent against multiple inputs and assert on every result.

Get started

Concepts

Guides

Development

Prerequisites

Send your first trace

Use the service pattern

What’s next

Instrument your agent

Test with replay

Run a scenario

​Prerequisites

​Send your first trace

​Use the service pattern

​What’s next

Instrument your agent

Test with replay

Run a scenario

Prerequisites

Send your first trace

Use the service pattern

What’s next