> ## 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 Python SDK

## Requirements

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

## Installation

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

  ```bash uv (recommended) theme={null}
  uv add agent-diff
  ```

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

## Configuration

<Tip>
  **Both the client and code executors** use the same environment variables. Set them once and everything works automatically.
</Tip>

### Environment Variables (Recommended)

Set these once in your shell or `.env` file:

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

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

```python theme={null}
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
)
```

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

### 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

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

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

  <Card title="OpenAI Agents" icon="robot" href="/integrating-with-agents/openai-agents">
    Integrate with OpenAI Agents SDK
  </Card>
</CardGroup>