# Warpmetrics

Observability for AI agents. Agents query their own runs, see what failed, and improve automatically.

## What it does

Warpmetrics tracks every LLM call your agent makes — cost, latency, tokens, success/failure — and organizes them into runs with outcomes. Unlike tracing tools built for humans, Warpmetrics exposes this data back to agents via MCP tools so they can debug and improve themselves.

## Quick start

```bash
npm install @warpmetrics/warp
```

```javascript
import { warp, run, add, outcome } from '@warpmetrics/warp';
import OpenAI from 'openai';

const openai = warp(new OpenAI());

async function myAgent(task) {
  const r = run('my-agent');

  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: task }],
  });

  add(r, response);
  outcome(r, 'completed');
}
```

That's it. Every LLM call is tracked automatically. No proxies, no config, no latency added.

## SDK functions

- `warp(client)` — wrap an OpenAI or Anthropic client. All calls are tracked automatically.
- `run(label, options?)` — start a run (one agent execution). Options: `{ name, link }`.
- `group(label, options?)` — create a logical step inside a run. Options: `{ name }`.
- `add(target, ...items)` — link calls, groups, or runs together. `add(run, response1, response2)`.
- `outcome(target, name, options?)` — record an outcome. Options: `{ reason, source, tags, metadata }`.
- `ref(target)` — get the string ID of any run, group, or call.
- `cost(target)` — get estimated USD cost of any run, group, or call.
- `flush()` — manually flush pending events.

## Supported providers

- OpenAI (`chat.completions.create`, `responses.create`)
- Anthropic (`messages.create`)

## Environment variables

- `WARPMETRICS_API_KEY` — your API key (starts with `wm_live`)
- `WARPMETRICS_API_URL` — custom API endpoint (default: `https://api.warpmetrics.com`)

## Links

- Website: https://warpmetrics.com
- API reference: https://api.warpmetrics.com
- SDK: https://www.npmjs.com/package/@warpmetrics/warp