Environments & Templates

Understanding isolated test environments and their starting states

How It Works

Agent Diff uses templates and environments to create isolated test spaces:

Template

A snapshot of a service’s state (users, channels, messages, etc.) that serves as a starting point and is used to populate an environment.

Environment

An isolated copy of a template where your agent operates. Each test gets its own environment.

1. Clone Template

   When you create an environment, Agent Diff clones the template’s data into a fresh database schema.

2. Agent Operates

   Your agent makes API calls against the isolated environment. Changes only affect this environment.

Templates

Templates are pre-configured database schemas that serve as starting points.

Built-in Templates

Template	Service	Description	impersonateUserId
slack_default	slack	3 users, 2 channels, 3 messages	U01AGENBOT9
slack_bench_default	slack	Extended seed for benchmarks	U01AGENBOT9
linear_default	linear	Basic teams, users, issues	2790a7ee-fde0-4537-9588-e233aa5a68d1
linear_expanded	linear	Full seed with projects, cycles, workflows	2790a7ee-fde0-4537-9588-e233aa5a68d1

View seed files on GitHub for details of already populated envs: Slack seeds | Linear seeds

Environments

Environments are isolated, ephemeral copies of templates where your agents operate.

Creating an Environment

from agent_diff import AgentDiff

client = AgentDiff()

# Create environment from template
env = client.init_env(
    templateService="slack",
    templateName="slack_default",
    impersonateUserId="U01AGENBOT9",  # Which user the agent acts as
    ttlSeconds=3600  # Auto-cleanup after 1 hour
)

print(f"Environment ID: {env.environmentId}")
print(f"API URL: {env.environmentUrl}")

Key Properties

Property	Description
environmentId	Unique identifier (UUID)
environmentUrl	Base URL for API calls
expiresAt	Auto-cleanup time (based on TTL)
status	ready, expired, deleted

Isolation

Each environment has:

• Separate database schema: No cross-contamination between tests
• Independent state: Changes don’t affect other environments or templates
• Own API endpoint: Unique URL for routing agent requests

Querying Environment Data

import requests

# List all channels in the environment
response = requests.get(f"{env.environmentUrl}/conversations.list")
channels = response.json()["channels"]
for ch in channels:
    print(f"#{ch['name']} ({ch['id']})")

# List all users
response = requests.get(f"{env.environmentUrl}/users.list")
users = response.json()["members"]
for u in users:
    print(f"@{u['name']} ({u['id']})")

Cleanup

# Manual cleanup
client.delete_env(envId=env.environmentId)

# Or let TTL expire automatically

---

Creating Custom Templates

You can create a template from any environment:

# 1. Start with a base template
env = client.init_env(templateService="slack", templateName="slack_default")

# 2. Customize it via API
import requests
requests.post(f"{env.environmentUrl}/conversations.create", json={
    "name": "engineering"
})
requests.post(f"{env.environmentUrl}/chat.postMessage", json={
    "channel": "C01GENERAL99",
    "text": "Custom seed message!"
})

# 3. Save as a new template
custom = client.create_template_from_environment(
    environmentId=env.environmentId,
    service="slack",
    name="my_custom_template",
    description="My customized Slack workspace",
    visibility="private"
)

Next Steps

Runs & Diffs

Learn how state changes are captured

Assertions

Define expected outcomes