# How to Set Up Multi-Provider Analytics Tracking (PostHog, Mixpanel, Amplitude) in Agent-Native

> Easily set up multi-provider analytics tracking for PostHog, Mixpanel, and Amplitude in agent-native. Securely forward events with server-side batching for optimal performance.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-06-27

---

**Agent-Native provides a built-in, server-side analytics stack that automatically forwards events to PostHog, Mixpanel, and Amplitude via environment variables, keeping API keys secure while batching requests for performance.**

BuilderIO/agent-native ships with a plug-in analytics architecture that eliminates the need to load multiple client-side SDKs. By configuring a few environment variables, you can enable **multi-provider analytics tracking** that captures every event server-side and distributes it to your chosen analytics platforms without exposing secrets to the browser.

## Architecture Overview

The analytics system in `BuilderIO/agent-native` consists of five key components working together to provide secure, batched event forwarding.

**Client SDK** (`@agent-native/core/client`): The `track()` function in [`packages/core/src/client/track.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/client/track.ts) serializes events and POSTs them to the internal endpoint `/_agent-native/track`.

**Core-Routes Plugin**: Automatically registers built-in tracking providers at server startup by invoking `registerBuiltinProviders()` from [`packages/core/src/tracking/providers.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/tracking/providers.ts).

**Provider Registry**: Defined in [`packages/core/src/tracking/registry.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/tracking/registry.ts), this holds active `TrackingProvider` instances. Each provider knows how to POST events to its downstream service.

**Batched Sender**: Queues events and sends them in batches (maximum 50 events every 10 seconds) to reduce network overhead. The queue is shared via `globalThis[QUEUE_KEY]`, ensuring the same batch is used for every active provider.

**Environment-Driven Activation**: Presence of specific environment variables automatically instantiates providers. No code changes are required to enable PostHog, Mixpanel, or Amplitude support.

All providers use plain `fetch()` calls rather than bundled SDKs, guaranteeing that secret keys never appear in client-side bundles.

## Environment Configuration

Agent-Native activates providers automatically when their respective API keys are present in the environment. Add these variables to your workspace `.env` file or configure them via the Builder UI Integrations page.

```dotenv
POSTHOG_API_KEY=phc_XXXXXXXXXXXXXXXXXXXXX
POSTHOG_HOST=https://eu.i.posthog.com
MIXPANEL_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXX
AMPLITUDE_API_KEY=amplitude-xxxxxxxxxxxxxxxxxxxx

```

The `POSTHOG_HOST` variable is optional and defaults to `https://us.i.posthog.com`. The secrets are stored in Builder’s vault and never checked into source control.

When the server starts, the function `registerBuiltinProviders()` in [`packages/core/src/tracking/providers.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/tracking/providers.ts) checks for these variables and immediately registers active providers:

```typescript
// packages/core/src/tracking/providers.ts (excerpt)
export function registerBuiltinProviders() {
  if (process.env.POSTHOG_API_KEY) {
    registerTrackingProvider(
      createPostHogProvider(
        process.env.POSTHOG_API_KEY,
        process.env.POSTHOG_HOST
      )
    );
  }
  if (process.env.MIXPANEL_TOKEN) {
    registerTrackingProvider(createMixpanelProvider(process.env.MIXPANEL_TOKEN));
  }
  if (process.env.AMPLITUDE_API_KEY) {
    registerTrackingProvider(
      createAmplitudeProvider(process.env.AMPLITUDE_API_KEY)
    );
  }
}

```

## Sending Events from Application Code

Once configured, import the `track` function from the client SDK and use it anywhere in your front-end or server components.

```typescript
import { track } from "@agent-native/core/client";

track({
  name: "user_signup",
  properties: {
    plan: "pro",
    referral: "campaign-42"
  }
});

```

The `track()` function POSTs the payload to `/_agent-native/track`. The server route then forwards the event to **all active providers** simultaneously. Because the queue is shared across providers, the same batch is used for every destination, conserving bandwidth and reducing server load.

## Verifying the Setup

To confirm that events are flowing correctly, use the built-in analytics query action or check your provider dashboards directly.

**Query the first-party collector**:

```bash
pnpm action query-agent-native-analytics \
  --sql "SELECT * FROM analytics_events ORDER BY created_at DESC LIMIT 5"

```

This action runs against the `analytics_events` table, which stores raw events for queries that do not rely on external providers.

**Check external dashboards**:
- **PostHog**: Navigate to Settings > Project > Personal API Keys
- **Mixpanel**: View Data Management > Events
- **Amplitude**: Review Events > Overview

## Adding Custom Providers

If you need to forward events to a custom analytics endpoint, register a provider at runtime using the registry API:

```typescript
import { registerTrackingProvider } from "@agent-native/core/tracking/registry";

registerTrackingProvider({
  name: "my-custom-provider",
  send: (event) => fetch("https://my-analytics.example.com/ingest", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(event)
  })
});

```

The custom provider joins the shared batch queue automatically and will receive events alongside PostHog, Mixpanel, or Amplitude.

## Summary

- **No client-side SDKs required**: Agent-Native uses server-side `fetch()` calls to keep secrets secure
- **Automatic activation**: Set `POSTHOG_API_KEY`, `MIXPANEL_TOKEN`, or `AMPLITUDE_API_KEY` to enable providers instantly
- **Shared batching**: Events are queued (max 50 per batch, flushed every 10 seconds) and sent to all active providers simultaneously via [`packages/core/src/tracking/providers.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/tracking/providers.ts)
- **First-party storage**: Raw events are optionally stored in the `analytics_events` table for SQL querying
- **Extensible**: Use `registerTrackingProvider()` from [`packages/core/src/tracking/registry.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/tracking/registry.ts) to add custom endpoints

## Frequently Asked Questions

### Do I need to install separate SDKs for PostHog, Mixpanel, or Amplitude?

No. Agent-Native implements its own provider logic in [`packages/core/src/tracking/providers.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/tracking/providers.ts) using standard `fetch()` calls. This keeps your client bundle lightweight and prevents API keys from leaking to the browser.

### How does the batching mechanism work?

The system maintains a shared queue (`globalThis[QUEUE_KEY]`) that accumulates events. Every 10 seconds or when 50 events accumulate (whichever comes first), the queue drains and sends batches to each active provider. This reduces network overhead significantly compared to sending individual requests.

### Can I use a custom analytics endpoint alongside the built-in providers?

Yes. You can register additional providers at runtime using `registerTrackingProvider()` from `@agent-native/core/tracking/registry`. Custom providers participate in the same batching queue as the built-in PostHog, Mixpanel, and Amplitude providers.

### Where should I store my analytics API keys?

Store them as environment variables in your workspace `.env` file or configure them through the Builder UI Integrations page. According to the source code in [`templates/analytics/server/lib/credential-keys.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/analytics/server/lib/credential-keys.ts), these credentials are managed securely and never exposed in client-side code or source control.