> ## Documentation Index
> Fetch the complete documentation index at: https://agentdiff.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Agent Diff TypeScript SDK

## Requirements

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

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install agent-diff
  ```

  ```bash pnpm theme={null}
  pnpm add agent-diff
  ```

  ```bash yarn theme={null}
  yarn add agent-diff
  ```
</CodeGroup>

## Configuration

### Self-Hosted (Local)

```typescript theme={null}
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`:

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

<Note>
  Sign up at [agentdiff.dev](https://agentdiff.dev) to get your API key for the hosted version.
</Note>

### Custom Self-Hosted URL

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

### With API Key (Self-Hosted)

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

### Environment Variables

You can also configure via environment variables:

```bash theme={null}
# 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"
```

```typescript theme={null}
// 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

```typescript theme={null}
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:

```typescript theme={null}
import type {
  InitEnvRequest,
  InitEnvResponse,
  StartRunRequest,
  StartRunResponse,
  DiffRunResponse,
  Template,
  TestSuite,
  Test
} from 'agent-diff';
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Basic Usage" icon="play" href="/sdks/typescript/basic-usage">
    Learn the core SDK operations
  </Card>

  <Card title="Vercel AI SDK" icon="triangle" href="/integrating-with-agents/vercel-ai">
    Integrate with Vercel AI SDK
  </Card>
</CardGroup>