Installation

Install the Agent Diff TypeScript SDK

Requirements

• Node.js 18 or higher
• Agent Diff backend running (locally or remote)

Installation

npm

npm install agent-diff

Configuration

Self-Hosted (Local)

import { AgentDiff } from 'agent-diff';

// Connects to http://localhost:8000 by default
const client = new AgentDiff();

Agent Diff Cloud (Hosted)

For the hosted version at api.agentdiff.dev:

const client = new AgentDiff({
  baseUrl: 'https://api.agentdiff.dev',
  apiKey: 'ad_live_sk_...'  // Get from dashboard
});

Sign up at agentdiff.dev to get your API key for the hosted version.

Custom Self-Hosted URL

const client = new AgentDiff({
  baseUrl: 'https://your-agentdiff-server.com'
});

With API Key (Self-Hosted)

const client = new AgentDiff({
  baseUrl: 'https://your-agentdiff-server.com',
  apiKey: 'ad_live_sk_...'
});

Environment Variables

You can also configure via environment variables:

# For hosted version
export AGENT_DIFF_BASE_URL="https://api.agentdiff.dev"
export AGENT_DIFF_API_KEY="ad_live_sk_..."

# For local development
export AGENT_DIFF_BASE_URL="http://localhost:8000"

// SDK will automatically use environment variables
const client = new AgentDiff();

Configuration Priority

The SDK resolves configuration in this order:

1. Explicit parameters passed to new AgentDiff()
2. Environment variables (AGENT_DIFF_BASE_URL, AGENT_DIFF_API_KEY)
3. Defaults (http://localhost:8000, no API key)

Verify Installation

import { AgentDiff } from 'agent-diff';

const client = new AgentDiff();

async function verify() {
  // List available templates
  const templates = await client.listTemplates();
  console.log(`Found ${templates.templates.length} templates`);

  // Create a test environment
  const env = await client.initEnv({
    templateService: 'slack',
    templateName: 'slack_default',
    impersonateUserId: 'U01AGENBOT9'
  });
  console.log(`Created environment: ${env.environmentId}`);

  // Clean up
  await client.deleteEnv(env.environmentId);
  console.log('✓ SDK working correctly!');
}

verify();

TypeScript Types

The SDK exports all types:

import type {
  InitEnvRequest,
  InitEnvResponse,
  StartRunRequest,
  StartRunResponse,
  DiffRunResponse,
  Template,
  TestSuite,
  Test
} from 'agent-diff';

Next Steps

Basic Usage

Learn the core SDK operations

Vercel AI SDK

Integrate with Vercel AI SDK