> ## Documentation Index
> Fetch the complete documentation index at: https://docs.margovia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Anthropic

> Wrap Anthropic messages and capture usage automatically.

## Recommended: tracked Anthropic client

Use this when one Anthropic message should become one Margovia run.

```ts theme={null}
import Anthropic from "@anthropic-ai/sdk";
import { Margovia } from "@margovia/sdk";

const margovia = new Margovia();
const anthropic = margovia.anthropic(new Anthropic());

await anthropic.messages.create({
  name: "summarize_contract",
  customerId: "workspace_456",
  customerName: "Acme Inc.",
  customerPlan: { name: "enterprise", monthlyUsd: 499 },
  outcome: "summary_created",
  request: {
    model: "claude-sonnet-4-20250514",
    max_tokens: 800,
    messages
  }
});
```

The tracked client starts a run, calls `client.messages.create(request)`, reads `response.usage`, records the cost event, and completes or fails the run.

Use a stable, namespaced `customerId`. Margovia stores this value exactly as sent and uses it as the customer grouping key.

The tracked client records:

* `provider: "anthropic"`
* model
* input tokens
* output tokens
* cache creation tokens
* 5 minute and 1 hour cache creation tokens
* cache read tokens
* latency

## Alternative: patch an existing client

Use this when you want to keep normal Anthropic call sites and pass Margovia fields through provider `metadata`.

```ts theme={null}
const anthropic = margovia.wrapAnthropic(new Anthropic(), {
  autoTrack: true,
  defaultName: "anthropic.messages.create"
});

await anthropic.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 800,
  messages,
  metadata: {
    margoviaName: "summarize_contract",
    margoviaOutcome: "summary_created",
    userId: "user_123",
    customerId: "workspace_456",
    customerName: "Acme Inc.",
    customerPlan: "enterprise",
    customerPlanMonthlyUsd: "499"
  }
});
```

This is useful for wide migrations, but the tracked Anthropic client is clearer for new code.

## Custom run input

```ts theme={null}
const anthropic = margovia.wrapAnthropic(new Anthropic(), {
  getRunInput: (_request, [body]) => ({
    name: "contract_summary",
    customerId: `workspace_${body.workspace.id}`,
    customerName: body.workspace.name,
    customerPlan: { name: "enterprise", monthlyUsd: 499 },
    outcome: "summary_created"
  })
});
```

Use `getRunInput` when customer or plan data comes from your authenticated request context instead of provider metadata.

## Explicit helper

Use `trackAnthropic(...)` when you already have your own helper function around Anthropic calls.

```ts theme={null}
const response = await margovia.trackAnthropic({
  name: "summarize_contract",
  customerId: "workspace_456",
  customerName: "Acme Inc.",
  outcome: "summary_created",
  request: params,
  fn: () => anthropic.messages.create(params)
});
```

This starts the run, calls Anthropic, reads `response.usage`, records cost, and completes or fails the run.

Use a raw Anthropic client inside `trackAnthropic(...)`. Do not pass an already-wrapped client into this helper or you may double-report the same call.

## Common mistake

Do not wrap a raw Anthropic call with `.track(...)` and expect cost to appear:

```ts theme={null}
await margovia.track({
  name: "summarize_contract",
  fn: () => rawAnthropic.messages.create(params)
});
```

That creates a run, but the raw client does not report token usage to Margovia. Use `margovia.anthropic(client)`, `wrapAnthropic(...)`, `trackAnthropic(...)`, or `run.trackCost(...)`.