Skip to main content
You want to confirm Apie is receiving events from your agent before you instrument real workloads. When you finish this page, your agent will be registered, a test event will be in the dashboard, and you’ll have a session replay URL to inspect.

​
Install

npm install @apie-sh/sdk
npm install -D @apie/cli

​
Set your API key

Get a project key from the Apie dashboard. Add it to your environment: 
APIE_API_KEY=apie_sk_test_...
APIE_BASE_URL=https://api.apie.sh
For local development against a self-hosted Apie instance, set APIE_BASE_URL to your API host (default is http://localhost:3000).

​
Initialize your project

The CLI scaffolds a config file and .env template: 
npx apie init
This creates:
  • apie.config.ts (TypeScript) or apie.config.py (Python) — agent identity and SDK settings
  • .env.example — copy to .env and fill in your API key

​
Wire the SDK

Export a configured client from your config file. One client per process — like Sentry. 
import { Apie } from "@apie-sh/sdk";

const apie = new Apie({
  apiKey: process.env.APIE_API_KEY,
  agent: {
    key: "my-agent",
    name: "My Agent",
  },
  runtime: {
    environment: process.env.NODE_ENV ?? "development",
    framework: "custom",
    language: "typescript",
  },
  mode: "monitor",
});

export default apie;
In your agent entrypoint, wait for registration to complete: 
import apie from "./apie.config";

await apie.ready();
// Agent is registered — start instrumenting

​
What you’ll see

After ready() resolves, Apie has called POST /v1/agents/identify. Your agent appears in the dashboard with an agentId and agentVersionId.

​
Send a test event

Verify the full pipeline with a smoke test: 
npx apie send-test-event
npx apie send-test-event --mode proof
# pipeline smoke test (default)
npx apie send-test-event --mode single
The pipeline mode simulates a realistic session: orchestrator run, LLM call, workflow step, tool call, guard evaluation, handoff, child run, and worker tool. The proof mode adds activation-proof evidence for a safe production-like action. The single mode sends one minimal tool call.

​
What you’ll see

The CLI prints a session replay URL. Open it in your browser to walk through the simulated session timeline.

​
Run diagnostics

If something doesn’t look right: 
npx apie doctor
npx apie doctor --send-test
doctor checks your config, registration status, queue health, and event validation.

​
Next steps

Choose how to instrument

Pick MCP proxy, framework plugin, or explicit instrumentation.

Trace runs and sessions

Wrap your agent work so every request creates a run.