<!-- GENERATED FILE: do not edit manually -->
# AGENTS.md

Package: `amplitude-ai` v1.4.0

## Install
- `pip install amplitude-ai`
- Optional MCP support: `pip install '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 provider client objects: use `wrap()` to instrument them.
- Multiple agents collaborating: use `session.run_as(child_agent)` for automatic identity propagation.
- Need explicit tool telemetry: use `@tool`.
- Cannot modify call sites at all: use `patch()` for aggregate-only monitoring (no per-user analytics).
- Need guided agent integration: use MCP prompt `instrument_app`.

## Canonical Patterns
- zero-code patching
- wrap-openai
- bound-agent-session
- multi-agent-run-as
- tool-decorator
- fastapi-middleware

## 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`

## Gotchas
- Keep `AMPLITUDE_AI_API_KEY` set in runtime env.
- Use `MockAmplitudeAI` for deterministic tests.
- Use `unpatch()` in tests to prevent cross-test leakage.
- Before putting large JSON in `track_user_message` content only, read **Content shaping** in `llms-full.txt` or `amplitude-ai.md` (short user line + `context=` for structured payloads).

## Testing
- `uv run pytest langley/amplitude_ai/tests`
- `uv run python scripts/generate_agent_docs.py --check`

## CLI
- `amplitude-ai` — print instrumentation prompt for AI coding agents; subcommands: mcp, doctor, status, --print-guide
- `amplitude-ai-instrument` — zero-code auto-patching wrapper (run your app with automatic instrumentation)
- `amplitude-ai-doctor` — validate environment, deps, and event pipeline
- `amplitude-ai-status` — show SDK version, installed providers, and env config
- `amplitude-ai-mcp` — start the MCP server for AI coding agents
- `amplitude-ai-register-catalog` — register event schema in your Amplitude Data Catalog

## Examples
- `examples/zero_code_example.py`
- `examples/wrap_openai_example.py`
- `examples/multi_agent_example.py`
- `examples/framework_integration_example.py`
- `examples/real_openai_example.py` (requires OPENAI_API_KEY)

## Extended Reference
- `llms-full.txt` — Full API signatures and canonical patterns for LLM agents

## Instrumentation Guide
- `amplitude-ai.md` — self-contained 4-phase instrumentation guide for any AI coding agent

## Event Schema (names)
- `[Agent] AI Response`
- `[Agent] Embedding`
- `[Agent] Score`
- `[Agent] Session End`
- `[Agent] Session Enrichment`
- `[Agent] Session Evaluation`
- `[Agent] Span`
- `[Agent] Tool Call`
- `[Agent] Topic Classification`
- `[Agent] User Message`
