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

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

Provider Registry: Defined in 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.

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 checks for these variables and immediately registers active providers:

// 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.

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:

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:

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
• 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 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 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, these credentials are managed securely and never exposed in client-side code or source control.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}