VoltAgent Observability SDK

Modern, type-safe, and developer-friendly SDK for tracking LLM agent workflows and observability.

🚀 Quick Start

npm install @voltagent/sdk

import { VoltAgentObservabilitySDK } from "@voltagent/sdk";

const sdk = new VoltAgentObservabilitySDK({
  baseUrl: "https://api.voltagent.dev",
  publicKey: "your-public-key",
  secretKey: "your-secret-key",
  autoFlush: true,
  flushInterval: 3000,
});

// Start a trace (conversation/session)
const trace = await sdk.trace({
  name: "Customer Support Query",
  agentId: "support-agent-v1",
  input: { query: "How to reset password?" },
  userId: "user-123",
  conversationId: "conv-456",
  tags: ["support", "password-reset"],
});

// Add an agent
const agent = await trace.addAgent({
  name: "Support Agent",
  input: { task: "Handle password reset request" },
  instructions: "You are a helpful customer support agent.",
  metadata: {
    modelParameters: { model: "gpt-4" },
  },
});

// Use a tool
const searchTool = await agent.addTool({
  name: "knowledge-base-search",
  input: { query: "password reset procedure" },
});

await searchTool.success({
  output: {
    results: ["Reset via email", "Reset via SMS"],
    relevanceScore: 0.89,
  },
});

// Complete the workflow
await agent.success({
  output: { response: "Password reset link sent!" },
  usage: { promptTokens: 150, completionTokens: 85, totalTokens: 235 },
});

await trace.end({
  output: { result: "Query resolved successfully" },
});

📋 Features

✅ Trace-based Architecture - Industry standard observability patterns
✅ Hierarchical Events - Agent → Tool/Memory/Retriever relationships
✅ Type Safety - Full TypeScript support with discriminated unions
✅ Fluent API - Intuitive method chaining
✅ Multi-Agent Support - Sub-agents and complex workflows
✅ Error Handling - Built-in error tracking and reporting
✅ Auto-flushing - Automatic event batching and sending
✅ Backward Compatible - Existing code continues to work

🏗️ Architecture

Core Concepts

Trace: A complete conversation/session (the main execution context)
Agent: An AI agent operating within a trace
Tool: External service calls (APIs, databases, etc.)
Memory: Data storage and retrieval operations
Retriever: Information search and retrieval

Event Hierarchy

Trace
├── Agent 1
│   ├── Tool 1 → success/error
│   ├── Memory 1 → success/error
│   ├── Sub-Agent 1.1
│   │   └── Tool 1.1.1 → success/error
│   └── Agent 1 → success/error
└── Agent 2
    └── Retriever 1 → success/error

📚 Step-by-Step Guide

1. Initialize the SDK

import { VoltAgentObservabilitySDK } from "@voltagent/sdk";

const sdk = new VoltAgentObservabilitySDK({
  baseUrl: "https://api.voltagent.dev",
  publicKey: "your-public-key",
  secretKey: "your-secret-key",
  autoFlush: true,
  flushInterval: 3000,
});

Prerequisites: Create an account at https://console.voltagent.dev/ and set up an organization and project to get your API keys.

2. Create a Trace

A trace represents one complete agent execution session. Every agent operation must happen within a trace.

const trace = await sdk.trace({
  name: "Customer Support Query",
  agentId: "support-agent-v1",
  input: { query: "How to reset password?" },
  userId: "user-123",
  conversationId: "conv-456",
  tags: ["support", "password-reset"],
  metadata: {
    priority: "high",
    source: "web-chat",
  },
});

3. Add an Agent to the Trace

const agent = await trace.addAgent({
  name: "Support Agent",
  input: { query: "User needs password reset help" },
  instructions:
    "You are a customer support agent specialized in helping users with account issues.",
  metadata: {
    modelParameters: {
      model: "gpt-4",
      temperature: 0.7,
      maxTokens: 1000,
    },
    role: "customer-support",
    specialization: "account-issues",
  },
});

4. Add Tools, Memory, and Retrievers

Tools (External API calls)

const searchTool = await agent.addTool({
  name: "knowledge-base-search",
  input: {
    query: "password reset procedure",
    maxResults: 5,
  },
  metadata: {
    searchType: "semantic",
    database: "support-kb",
  },
});

// Tool success
await searchTool.success({
  output: {
    results: ["Reset via email", "Reset via SMS", "Contact support"],
    count: 3,
    relevanceScore: 0.89,
  },
  metadata: {
    searchTime: "0.2s",
    indexUsed: "support-kb-v2",
  },
});

// Tool error (if needed)
await searchTool.error({
  statusMessage: new Error("Database connection timeout"),
  metadata: {
    database: "support-kb",
    timeoutMs: 5000,
  },
});

Memory Operations

const memoryOp = await agent.addMemory({
  name: "user-context-storage",
  input: {
    key: "user_123_context",
    value: {
      lastLogin: "2024-01-15",
      accountType: "premium",
    },
    ttl: 3600,
  },
  metadata: {
    type: "redis",
    region: "us-east-1",
  },
});

await memoryOp.success({
  output: {
    stored: true,
    key: "user_123_context",
    expiresAt: "2024-01-15T15:00:00Z",
  },
  metadata: {
    cacheHit: false,
    storageLatency: "2ms",
  },
});

Retrieval Operations

const retriever = await agent.addRetriever({
  name: "policy-document-retriever",
  input: {
    query: "password reset policy for premium users",
    maxDocuments: 3,
    threshold: 0.8,
  },
  metadata: {
    vectorStore: "pinecone",
    embeddingModel: "text-embedding-ada-002",
  },
});

await retriever.success({
  output: {
    documents: [
      "Premium users can reset passwords instantly via email",
      "Password reset requires 2FA verification for premium accounts",
    ],
    relevanceScores: [0.95, 0.88],
  },
  metadata: {
    searchTime: "0.3s",
    documentsScanned: 1500,
  },
});

5. Working with Sub-Agents

Create hierarchical agent structures for complex workflows:

// Create a sub-agent under the main agent
const policyChecker = await agent.addAgent({
  name: "Policy Checker",
  input: {
    userId: "user-123",
    requestType: "password-reset",
  },
  instructions: "You verify customer requests against company policies.",
  metadata: {
    role: "policy-verification",
    parentAgent: agent.id,
    modelParameters: {
      model: "gpt-4",
    },
  },
});

// Add a tool to the sub-agent
const verificationTool = await policyChecker.addTool({
  name: "policy-verification",
  input: { userId: "user-123", action: "password-reset" },
});

await verificationTool.success({
  output: { policyCompliant: true, requiredVerification: "2fa-sms" },
});

// Complete the sub-agent
await policyChecker.success({
  output: {
    policyCompliant: true,
    approvalGranted: true,
  },
  usage: {
    promptTokens: 85,
    completionTokens: 45,
    totalTokens: 130,
  },
  metadata: {
    policiesChecked: ["password-policy", "premium-user-policy"],
    complianceScore: 0.95,
  },
});

6. Complete the Agent and Trace

// Complete the main agent
await agent.success({
  output: {
    response: "Password reset link sent to user's email",
    actionTaken: "email-reset-link",
    userSatisfied: true,
  },
  usage: {
    promptTokens: 150,
    completionTokens: 85,
    totalTokens: 235,
  },
  metadata: {
    responseTime: "2.1s",
    confidenceScore: 0.95,
  },
});

// Complete the trace
await trace.end({
  output: {
    result: "Customer support query resolved successfully",
    resolution: "password-reset-completed",
  },
  status: "completed",
  usage: {
    promptTokens: 150,
    completionTokens: 85,
    totalTokens: 235,
  },
  metadata: {
    totalAgents: 2,
    totalOperations: 4,
    successRate: 1.0,
  },
});

📚 API Reference

SDK Initialization

const sdk = new VoltAgentObservabilitySDK({
  baseUrl: string;
  publicKey: string;
  secretKey: string;
  autoFlush?: boolean; // default: true
  flushInterval?: number; // default: 5000ms
});

Creating Traces

const trace = await sdk.trace({
  name: string;
  agentId: string; // The main agent identifier
  input?: any;
  userId?: string;
  conversationId?: string;
  metadata?: Record<string, unknown>;
  tags?: string[];
});

Trace Operations

// Update trace metadata
await trace.update({
  status?: string;
  metadata?: Record<string, unknown>;
  // ... other trace fields
});

// End trace - Success
await trace.end({
  output?: any;
  status?: string;
  usage?: { promptTokens: number; completionTokens: number; totalTokens: number };
  metadata?: Record<string, unknown>;
});

// End trace - Error
await trace.end({
  output?: any;
  status: "error";
  metadata?: Record<string, unknown>;
});

// Add agents to trace
const agent = await trace.addAgent({
  name: string;
  input?: any;
  instructions?: string;
  metadata?: Record<string, unknown>;
});

Agent Operations

// Add sub-agents
const subAgent = await agent.addAgent(options);

// Add tools
const tool = await agent.addTool({
  name: string;
  input?: any;
  metadata?: Record<string, unknown>;
});

// Add memory operations
const memory = await agent.addMemory({
  name: string;
  input?: any;
  metadata?: Record<string, unknown>;
});

// Add retrieval operations
const retriever = await agent.addRetriever({
  name: string;
  input?: any;
  metadata?: Record<string, unknown>;
});

// Complete agent - Success
await agent.success({
  output?: any;
  usage?: { promptTokens: number; completionTokens: number; totalTokens: number };
  metadata?: Record<string, unknown>;
});

// Complete agent - Error
await agent.error({
  statusMessage: Error | string | object;
  stage?: string;
  metadata?: Record<string, unknown>;
});

Tool/Memory/Retriever Operations

// Success completion
await tool.success({
  output?: any;
  metadata?: Record<string, unknown>;
});

await memory.success({
  output?: any;
  metadata?: Record<string, unknown>;
});

await retriever.success({
  output?: any;
  metadata?: Record<string, unknown>;
});

// Error handling
await tool.error({
  statusMessage: Error | string | object;
  metadata?: Record<string, unknown>;
});

await memory.error({
  statusMessage: Error | string | object;
  metadata?: Record<string, unknown>;
});

await retriever.error({
  statusMessage: Error | string | object;
  metadata?: Record<string, unknown>;
});

🔧 Usage Examples

Simple Weather Agent

const trace = await sdk.trace({
  name: "weather_query",
  agentId: "weather-agent-v1",
  input: { query: "Weather in Istanbul?" },
});

const agent = await trace.addAgent({
  name: "Weather Agent",
  instructions: "You provide accurate weather information.",
  metadata: { modelParameters: { model: "gpt-4" } },
});

// Call weather API
const weatherTool = await agent.addTool({
  name: "weather_api",
  input: { city: "Istanbul" },
});

await weatherTool.success({
  output: {
    temperature: 22,
    condition: "sunny",
    humidity: 65,
  },
});

// Save to memory
const memory = await agent.addMemory({
  name: "cache_weather",
  input: { key: "istanbul_weather", value: { temp: 22, condition: "sunny" } },
});

await memory.success({
  output: { cached: true, expiresIn: 3600 },
});

await agent.success({
  output: { response: "It's 22°C and sunny in Istanbul!" },
  usage: { promptTokens: 50, completionTokens: 25, totalTokens: 75 },
});

await trace.end({
  output: { result: "Weather query completed" },
  status: "completed",
});

Multi-Agent Research Workflow

const trace = await sdk.trace({
  name: "research_workflow",
  agentId: "orchestrator",
  input: { topic: "AI trends 2024" },
});

// Research agent
const researcher = await trace.addAgent({
  name: "Research Agent",
  instructions: "You research and gather information on given topics.",
  metadata: { modelParameters: { model: "gpt-4" } },
});

const search = await researcher.addRetriever({
  name: "web_search",
  input: { query: "AI trends 2024", maxResults: 10 },
});

await search.success({
  output: {
    documents: ["AI trend doc 1", "AI trend doc 2"],
    relevanceScores: [0.9, 0.8],
    totalResults: 10,
  },
});

await researcher.success({
  output: { researchComplete: true, documentsFound: 10 },
  usage: { promptTokens: 200, completionTokens: 150, totalTokens: 350 },
});

// Summary agent
const summarizer = await trace.addAgent({
  name: "Summary Agent",
  instructions: "You create comprehensive summaries from research data.",
  metadata: { modelParameters: { model: "gpt-4" } },
});

// Translation sub-agent
const translator = await summarizer.addAgent({
  name: "Translation Agent",
  instructions: "You translate content to different languages.",
  metadata: { modelParameters: { model: "gpt-3.5-turbo" } },
});

const translateTool = await translator.addTool({
  name: "translate_api",
  input: { text: "AI trends summary", targetLanguage: "tr" },
});

await translateTool.success({
  output: { translatedText: "AI eğilimleri özeti..." },
});

await translator.success({
  output: { translation: "Turkish translation completed" },
  usage: { promptTokens: 100, completionTokens: 80, totalTokens: 180 },
});

await summarizer.success({
  output: { summary: "Comprehensive AI trends summary with translation" },
  usage: { promptTokens: 300, completionTokens: 200, totalTokens: 500 },
});

await trace.end({
  output: { result: "Research workflow completed successfully" },
  status: "completed",
});

Error Handling

const trace = await sdk.trace({
  name: "error_handling_example",
  agentId: "test-agent",
});

const agent = await trace.addAgent({
  name: "Risky Agent",
  instructions: "You handle operations that might fail.",
});

const riskyTool = await agent.addTool({
  name: "external_api",
  input: { endpoint: "https://unreliable-api.com" },
});

try {
  // Simulate API call that might fail
  const result = await callExternalAPI();
  await riskyTool.success({
    output: result,
    metadata: { responseTime: "1.2s" },
  });

  await agent.success({
    output: { result: "Operation completed successfully" },
  });
} catch (error) {
  // Handle tool error
  await riskyTool.error({
    statusMessage: error,
    metadata: {
      errorCode: "API_TIMEOUT",
      retryAttempts: 3,
    },
  });

  // Handle agent error
  await agent.error({
    statusMessage: new Error("Agent failed due to tool error"),
    stage: "tool_execution",
    metadata: {
      failedTool: "external_api",
      errorType: "TIMEOUT",
    },
  });

  // End trace with error
  await trace.end({
    output: { error: "Workflow failed" },
    status: "error",
    metadata: { errorStage: "tool_execution" },
  });
}

🏷️ Event Types

Agent Events

agent:start - Agent begins processing
agent:success - Agent completes successfully
agent:error - Agent encounters an error

Tool Events

tool:start - Tool call begins
tool:success - Tool call succeeds
tool:error - Tool call fails

Memory Events

memory:read_start / memory:read_success / memory:read_error
memory:write_start / memory:write_success / memory:write_error

Retriever Events

retriever:start - Retrieval begins
retriever:success - Retrieval succeeds
retriever:error - Retrieval fails

💡 Best Practices

Always call sdk.flush() before your application exits to ensure all events are sent
Use meaningful names for traces, agents, tools, and operations to improve debugging
Include relevant metadata for debugging and analytics, but avoid sensitive data
Track token usage in the usage field, not metadata, for proper cost tracking
Handle errors properly with descriptive error messages and relevant context
Use hierarchical agents for complex workflows to maintain clear operation flow
Set appropriate tags on traces for easy filtering and search in the dashboard
Use structured error objects instead of plain strings for better error analysis
Include timing metadata for performance monitoring and optimization
Group related operations under the same agent for logical organization

🧪 Testing

npm test

Run examples:

npm run examples

🔗 Links

📄 License

MIT License - see LICENSE file for details.

@voltagent/sdk