# Data Residency

The `amplitude-ai` SDK supports routing all Agent observability events to Amplitude's US or EU data centers. Data residency is configured on the underlying **Amplitude Python SDK**, not on the `amplitude-ai` SDK itself, because the AI SDK delegates all network I/O to the customer's `Amplitude` instance.

## Quick Start

### EU Data Residency

```python
from amplitude import Amplitude
from amplitude_ai import AmplitudeAI

amplitude = Amplitude("your-api-key")
amplitude.configuration.server_zone = "EU"

ai = AmplitudeAI(amplitude=amplitude)
```

With this configuration, all `[Agent]` events are sent to `https://api.eu.amplitude.com/2/httpapi`.

### US Data Residency (default)

```python
from amplitude import Amplitude
from amplitude_ai import AmplitudeAI

amplitude = Amplitude("your-api-key")
# server_zone defaults to "US" — no change needed

ai = AmplitudeAI(amplitude=amplitude)
```

Events are sent to `https://api2.amplitude.com/2/httpapi`.

## How It Works

The Amplitude Python SDK provides a `server_zone` configuration that controls which regional endpoint receives events:

| `server_zone` | HTTP V2 Endpoint | Batch Endpoint |
|---|---|---|
| `"US"` (default) | `https://api2.amplitude.com/2/httpapi` | `https://api2.amplitude.com/batch` |
| `"EU"` | `https://api.eu.amplitude.com/2/httpapi` | `https://api.eu.amplitude.com/batch` |

The `amplitude-ai` SDK does not implement its own HTTP layer. It calls `amplitude.track(event)` on the customer's `Amplitude` instance, which handles serialization, batching, retry, and transport. This means:

1. **All Agent events use the same endpoint** as the rest of the customer's Amplitude events.
2. **No additional configuration** is needed on the `amplitude-ai` SDK.
3. **Batch mode** is also supported — set `amplitude.configuration.use_batch = True` to use the batch endpoint.

## Custom Endpoints

For customers who self-host an Amplitude-compatible event ingestion endpoint (e.g., a proxy or on-premises deployment), set `server_url` directly:

```python
from amplitude import Amplitude
from amplitude_ai import AmplitudeAI

amplitude = Amplitude("your-api-key")
amplitude.configuration.server_url = "https://analytics.internal.example.com/2/httpapi"

ai = AmplitudeAI(amplitude=amplitude)
```

When `server_url` is set explicitly, it takes precedence over `server_zone`. The URL is used as-is for all event delivery.

## Standalone Initialization

If you use the standalone `api_key` initialization (i.e., `AmplitudeAI(api_key="...")` without passing an existing `Amplitude` instance), the SDK creates an internal `Amplitude` client with the default US zone. To use EU data residency, configure the server zone after initialization:

```python
from amplitude_ai import AmplitudeAI

ai = AmplitudeAI(api_key="your-api-key")
ai.amplitude.configuration.server_zone = "EU"
```

**Recommended:** Use the explicit `Amplitude` instance pattern shown in the Quick Start above, as it gives you full control over all configuration before any events are tracked.

## Combining Data Residency with Privacy Tiers

Data residency and privacy controls are independent — they compose without conflict:

```python
from amplitude import Amplitude
from amplitude_ai import AmplitudeAI, AIConfig, ContentMode

amplitude = Amplitude("your-api-key")
amplitude.configuration.server_zone = "EU"

ai = AmplitudeAI(
    amplitude=amplitude,
    config=AIConfig(
        content_mode=ContentMode.METADATA_ONLY,  # No content leaves the process
        redact_pii=True,                          # PII scrubbing as defense-in-depth
    ),
)
```

This configuration ensures:
- Events are routed to the EU data center
- No message content or reasoning text is transmitted
- PII patterns are scrubbed as an additional safety layer (for any content that might appear in metadata fields)

## Verification

To verify events are being sent to the correct endpoint, use the per-event delivery callback:

```python
def verify_endpoint(event, status_code, message):
    print(f"Sent to {amplitude.configuration.server_url}: {event.event_type} -> {status_code}")

ai = AmplitudeAI(
    amplitude=amplitude,
    config=AIConfig(on_event_callback=verify_endpoint),
)
```

## Summary

| Scenario | Configuration |
|---|---|
| US (default) | No change needed |
| EU | `amplitude.configuration.server_zone = "EU"` |
| Custom / on-premises | `amplitude.configuration.server_url = "https://..."` |
| Batch mode | `amplitude.configuration.use_batch = True` |
