Installation

Install the Agent Diff Python SDK

Requirements

• Python 3.10 or higher
• Agent Diff backend running (locally or remote)

Installation

pip

pip install agent-diff

uv add agent-diff

poetry add agent-diff

Configuration

Both the client and code executors use the same environment variables. Set them once and everything works automatically.

Environment Variables (Recommended)

Set these once in your shell or .env file:

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

# For local development (no API key needed)
export AGENT_DIFF_BASE_URL="http://localhost:8000"

Then both client and executors auto-configure:

from agent_diff import AgentDiff, PythonExecutorProxy

# Both automatically use env vars
client = AgentDiff()
executor = PythonExecutorProxy(env.environmentId)  

Explicit Configuration

You can also pass values directly:

from agent_diff import AgentDiff, PythonExecutorProxy

# Client with explicit config
client = AgentDiff(
    base_url="https://api.agentdiff.dev",
    api_key="ad_live_sk_..."
)

# Executor with explicit config
executor = PythonExecutorProxy(
    environment_id=env.environmentId,
    base_url=client.base_url,
    api_key=client.api_key
)

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

Configuration Priority

The SDK resolves configuration in this order:

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

Verify Installation

from agent_diff import AgentDiff

client = AgentDiff()

# List available templates
templates = client.list_templates()
print(f"Found {len(templates.templates)} templates")

# Create a test environment
env = client.init_env(
    templateService="slack",
    templateName="slack_default",
    impersonateUserId="U01AGENBOT9"
)
print(f"Created environment: {env.environmentId}")

# Clean up
client.delete_env(envId=env.environmentId)
print("✓ SDK working correctly!")

Next Steps

Basic Usage

Learn the core SDK operations

OpenAI Agents

Integrate with OpenAI Agents SDK