# AGENTS.md

Package: `@amplitude/ai` v0.24.1

## Install

```bash
pnpm add @amplitude/ai
```

## MCP Server Setup

The SDK ships an MCP server for AI coding agents. It provides project scanning,
file validation, instrumentation, test generation, and the complete API reference.

Install `@amplitude/ai` in the project first, and configure the server per
project (not in a global config) so it runs the version installed in that project.
Always name the scoped package in `npx` (`npx -y -p @amplitude/ai amplitude-ai ...`):
`amplitude-ai` is only a bin name, and `npx` without `-p` looks it up as a separate package.

### Cursor

Add to `.cursor/mcp.json` in your project root:
```json
{ "mcpServers": { "amplitude-ai": { "command": "npx", "args": ["-y", "-p", "@amplitude/ai", "amplitude-ai", "mcp"] } } }
```
Then point the agent at the instrumentation guide: `node_modules/@amplitude/ai/amplitude-ai.md`

### Claude Code

```bash
claude mcp add --scope project amplitude-ai -- npx -y -p @amplitude/ai amplitude-ai mcp
```
This writes `.mcp.json` in the project root. Then point the agent at the instrumentation guide: `node_modules/@amplitude/ai/amplitude-ai.md`

### OpenAI Codex CLI

Add to `.codex/config.toml` in your project root (Codex reads project config for trusted projects):
```toml
[mcp_servers.amplitude-ai]
command = "npx"
args = ["-y", "-p", "@amplitude/ai", "amplitude-ai", "mcp"]
```
Codex auto-reads this `AGENTS.md` file for context.

### Generic (any MCP-compatible agent)

```json
{ "amplitude-ai": { "command": "npx", "args": ["-y", "-p", "@amplitude/ai", "amplitude-ai", "mcp"] } }
```

## Decision Tree

- **Default: use `ai.agent(...).session(...)` with provider wrappers** — gives you every event type, per-user analytics, session enrichment, quality scoring.
- Already have a provider client: use `wrap()` to instrument it.
- Multiple agents collaborating: use `session.runAs(childAgent, fn)` for automatic identity propagation.
- Need tool telemetry: use `tool()`.
- Need span/observability: use `observe()`.
- Cannot modify call sites at all: use `patch()` for aggregate-only monitoring (no per-user analytics).
- Already emit OTEL GenAI spans: use `AmplitudeAgentExporter({ amplitudeAI: ai })` (or `enableOtel()`) to map them to [Agent] events.
- LangChain / LangGraph: use `AmplitudeCallbackHandler` (duck-typed; implements `handleChatModelStart` for User Message).
- Need agent-assistant guidance: run MCP prompt `instrument_app`.
- Want local verification: use `MockAmplitudeAI().summary()` for fill-rate report.
- HTML artifact snapshots are producer-owned content: existing capture modes and ordinary best-effort string redaction apply. Choose approved source content and preflight size before tracking; the SDK does not parse or sanitize rendered HTML.
- Agent runs on a hosted platform (Sierra, Decagon, Fin, Agentforce): no SDK; forward conversations over HTTP by following `docs/integrations/<platform>.md`.
- Conversations already traced in Langfuse, LangSmith, Braintrust: forward them, including history, over HTTP by following `docs/integrations/<tool>.md`.
- Conversations or traces already in a warehouse (Snowflake, BigQuery, Databricks): follow `docs/integrations/warehouses/README.md`; check output with `docs/integrations/check-agent-events.mjs`.
- Requests go through an inference router or AI gateway (Fireworks, OpenRouter, LiteLLM, Requesty): follow `docs/integrations/routers.md` for the base URL, the `context: { ingestion_path: 'gateway', gateway: '...' }` tag, the routed model ID rule, and pricing; the per-request identity contract is `docs/integrations/analytics-metadata.schema.json`.
- Agent runs on AWS Strands (Python): export native OTLP by following `docs/integrations/strands.md`. Scrub content before export with `docs/integrations/privacy.md`. When the app already runs this SDK, `AmplitudeAgentExporter` / `enableOtel()` can map spans in process.

## MCP Surface

Tools:
- `get_event_schema`
- `get_integration_pattern`
- `validate_setup`
- `suggest_instrumentation`
- `validate_file`
- `search_docs`
- `scan_project`
- `generate_verify_test`
- `instrument_file`

Resources:
- `amplitude-ai://event-schema`
- `amplitude-ai://integration-patterns`
- `amplitude-ai://instrument-guide`

Prompt:
- `instrument_app` — Short prompt; fetch `amplitude-ai://instrument-guide` (full amplitude-ai.md) before editing

## Canonical Patterns

- zero-code patching — `patch({ amplitudeAI: ai })`
- wrap-openai — `wrap(existingClient, ai)`
- bound-agent-session — `ai.agent('id').session({ userId }).run(fn)`
- multi-agent-runas — `s.runAs(childAgent, fn)`
- tool-decorator — `tool(fn, { name: 'tool_name' })`
- observe-spans — `observe(fn, { name: 'span-name' })`
- express-middleware — `createAmplitudeAIMiddleware({ amplitudeAI: ai, userIdResolver })`

## Gotchas

- `tool()` in Node requires explicit JSON schema for robust agent input shaping.
- Keep `AMPLITUDE_AI_API_KEY` available in runtime env for telemetry delivery.
- Use `MockAmplitudeAI` for deterministic tests.
- Call `ai.flush()` before returning from serverless handlers (Next.js, Lambda, Vercel).
- `session.run()` relies on `AsyncLocalStorage`; not available in Edge Runtime. **Cloudflare Workers:** do NOT import `AmplitudeAI`, `AIConfig`, or any runtime export from `@amplitude/ai` in Worker bundles — they pull in `node:async_hooks` / `node:module` which break Workers Builds. Use the SDK-free `FetchAmplitudeClient` pattern with direct `[Agent]` event construction (see "Edge Runtime / Cloudflare Workers" in amplitude-ai.md). Only `import type { ... } from '@amplitude/ai/types'` is safe.
- **User message text:** `trackUserMessage(content, opts?)` — put human-readable intent in `content`; large JSON / RAG / pipeline state in `opts.context` (preferred — maps to the registered `[Agent] Context` property, always queryable in charts), not as the only `content`, or session labels and segmentation show raw JSON. Avoid `opts.eventProperties` for custom dimensions on `[Agent]` events — unregistered properties may be silently dropped by schema enforcement.
- **Turns vs spans:** `[Agent] User Message` + `[Agent] AI Response` drive turn-level analytics; `observe()` / `trackSpan()` complement them — do not use spans alone for conversation metrics.
- **Gateways / custom `baseURL`:** use `trackAiMessage` with `usage` fields, the **real** routed model id, and `totalCostUsd` when genai-prices cannot resolve the model string (install `@pydantic/genai-prices` for automatic cost when supported). Tag gateway traffic with `context: { ingestion_path: 'gateway', gateway: 'openrouter'|'litellm'|'requesty' }`.
- **LangChain callbacks:** `AmplitudeCallbackHandler` is duck-typed (no hard `@langchain/core` dep). Prefer `handleChatModelStart` coverage for chat models.

## CLI

- `amplitude-ai` — Print instrumentation prompt for AI coding agents
- `amplitude-ai --print-guide` — Print the full amplitude-ai.md guide to stdout
- `amplitude-ai mcp` — Start the MCP server for AI coding agents
- `amplitude-ai doctor [--json]` — Validate environment, deps, and event pipeline
- `amplitude-ai status [--json]` — Show SDK version, installed providers, and env config

## Testing

- Run package tests: `pnpm --filter @amplitude/ai test`
- Run typecheck: `pnpm --filter @amplitude/ai test:typescript`
- Run docs freshness: `node scripts/generate-agent-docs.mjs --check`

## Examples

- `examples/zero-code.ts`
- `examples/wrap-openai.ts`
- `examples/multi-agent.ts`
- `examples/framework-integration.ts`
- `examples/real-openai.ts` (requires OPENAI_API_KEY)

## Instrumentation Guide

Fetch the public guide for the job. These URLs track `main`.

- Node app: fetch `https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/amplitude-ai.md` and follow it, then install `@amplitude/ai` as that guide says.
- Python app: `python3 -m pip install amplitude-ai`, then run `amplitude-ai --print-guide`.
- Hosted platform, tracing tool, warehouse, gateway, or AWS Strands: start at `https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/README.md` and follow the linked page, including privacy.
- `amplitude-ai.md` — **Start here** once the package is installed. Complete 4-phase instrumentation workflow + API reference. The installed copy is `node_modules/@amplitude/ai/amplitude-ai.md`.
- `llms-full.txt` — Extended API reference with MCP tools and patterns
- `docs/integrations/sierra.md` — Sierra conversation ingestion over the HTTP API (no SDK)
- `docs/integrations/decagon.md` — Decagon conversation ingestion over the HTTP API (no SDK)
- `docs/integrations/fin.md` — Fin conversation ingestion over the HTTP API (no SDK)
- `docs/integrations/agentforce.md` — Agentforce conversation ingestion over the HTTP API (no SDK)
- `docs/integrations/langfuse.md` — Langfuse trace forwarding over the HTTP API (no SDK)
- `docs/integrations/langsmith.md` — LangSmith trace forwarding over the HTTP API (no SDK)
- `docs/integrations/braintrust.md` — Braintrust trace forwarding over the HTTP API (no SDK)
- `docs/integrations/warehouses/README.md` — Snowflake, BigQuery, Databricks ingestion through a SQL view and warehouse import (no SDK)
- `docs/integrations/routers.md` — Inference routers and AI gateways: SDK wrap, router-exported OTLP spans, or HTTP API
- `docs/integrations/strands.md` — AWS Strands (Python) native OTLP export
- `docs/integrations/privacy.md` — Client-side scrubbing for HTTP, OTLP, Batch, S3, and warehouse paths that do not run the SDK

## Event Schema (names)

- `[Agent] AI Response`
- `[Agent] Embedding`
- `[Agent] Evaluator Result`
- `[Agent] Score`
- `[Agent] Session End`
- `[Agent] Session Enrichment`
- `[Agent] Session Record`
- `[Agent] Span`
- `[Agent] Tool Call`
- `[Agent] User Message`