# @standardagents/anthropic

Anthropic provider package for Standard Agents - direct access to Claude models with typed configuration

> **Info:**
>
> For direct access, set `ANTHROPIC_API_KEY` in your environment. Standard Agents Builder can use hosted routing through `STANDARD_AGENTS_API_KEY` when the provider key is absent. Hosted access depends on platform configuration.

## Overview

The `@standardagents/anthropic` package provides the Anthropic provider factory for Standard Agents. It wraps the official `@anthropic-ai/sdk` and enables direct access to Claude models with typed `providerOptions`, extended thinking support, prompt caching, and Anthropic's server-side web search tool.

- Key Features

  - Direct Anthropic Messages API access with automatic client management
  - Typed `providerOptions` with TypeScript autocompletion
  - Extended thinking support across model generations (adaptive on Claude 4.6+, token budgets on Claude 4.0-4.5)
  - Thinking blocks round-trip correctly in multi-turn tool conversations
  - Built-in `web_search` provider tool (executed on Anthropic's servers)
  - Live model listing and capability detection via the Anthropic Models API
  - Prompt caching opt-in for the system prompt

## Installation

```bash npm
npm install @standardagents/anthropic
```

```bash pnpm
pnpm add @standardagents/anthropic
```

```bash yarn
yarn add @standardagents/anthropic
```

## Quick Start

```typescript agents/models/claude_opus.ts
import { defineModel } from '@standardagents/spec';
import { anthropic } from '@standardagents/anthropic';

export default defineModel({
  name: 'claude-opus',
  provider: anthropic,
  model: 'claude-opus-5-5',
  // Prices change. Check https://platform.claude.com/docs/en/about-claude/pricing
  inputPrice: 4,
  outputPrice: 20,
});
```

## Provider Factory

The `anthropic` export is a provider factory function that creates Anthropic provider instances:

```typescript
import { anthropic } from '@standardagents/anthropic';

// The factory is used by defineModel internally
defineModel({
  name: 'my-model',
  provider: anthropic,  // Pass the factory, not a string
  model: 'claude-sonnet-5-5',
});
```

## Provider Options

The `anthropic` factory includes a typed schema for provider-specific options:

```typescript
import { defineModel } from '@standardagents/spec';
import { anthropic } from '@standardagents/anthropic';

export default defineModel({
  name: 'claude-opus',
  provider: anthropic,
  model: 'claude-opus-5-5',
  // Prices change. Check https://platform.claude.com/docs/en/about-claude/pricing
  inputPrice: 4,
  outputPrice: 20,
  providerOptions: {
    service_tier: 'auto',
    metadata: { user_id: 'user-123' },
    cacheSystemPrompt: true,
  },
});
```

### Available Options

| Option              | Type                        | Description                                                                                                                               |
| ------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `service_tier`      | `'auto' \| 'standard_only'` | Request priority tier                                                                                                                     |
| `metadata`          | `{ user_id?: string }`      | Opaque user identifier for abuse monitoring                                                                                               |
| `cacheSystemPrompt` | `boolean`                   | Add a prompt-caching breakpoint to the system prompt so repeated requests bill cached-input rates                                         |
| `thinking`          | `object`                    | Explicit thinking configuration override (Anthropic API shape, e.g. `{ type: 'adaptive' }` or `{ type: 'enabled', budget_tokens: 8192 }`) |

Unknown keys are passed through to the Messages API for forward compatibility.

## Extended Thinking

The provider maps the Standard Agents 0-100 reasoning level to the right thinking configuration per model generation:

| Model family                                                             | Thinking mode | Mapping                                                                               |
| ------------------------------------------------------------------------ | ------------- | ------------------------------------------------------------------------------------- |
| Claude Fable 5.x, Mythos, Opus 5.x, Opus 4.6-4.8, Sonnet 5.x, Sonnet 4.6 | Adaptive      | `thinking: { type: 'adaptive' }` + `output_config.effort` (`low` / `medium` / `high`) |
| Opus 4.0-4.5, Sonnet 4.0-4.5, Haiku 4.5, Sonnet 3.7                      | Token budget  | `thinking: { type: 'enabled', budget_tokens }` scaled to the output limit             |
| Claude 3.x                                                               | None          | Thinking is not requested                                                             |

A prompt's explicit `reasoning.level` takes precedence over native thinking options. Level `0` disables thinking where supported. Fable, Mythos, Opus 5.5, and Sonnet 5.5 use `low` effort at level `0`.

Thinking text, signatures, and redacted thinking blocks are preserved on responses and replayed exactly on subsequent turns, which Anthropic requires for multi-turn tool use with thinking enabled. When thinking is active, sampling parameters (`temperature`, `top_p`, `top_k`) are automatically omitted since the API rejects them alongside thinking.

## Provider Tools

Anthropic's server-side `web_search` tool is exposed as a provider-embedded tool. Add it to a prompt or model's tool list and Claude will search the web on Anthropic's servers; results are recorded in execution logs as provider tool calls with their queries and sources.

## Usage & Cost Tracking

Token usage is normalized to the Standard Agents convention: `promptTokens` covers the full prompt (including cache reads and cache writes), `cachedTokens` reports tokens served from the prompt cache, and `reasoningTokens` reports thinking tokens. Raw Anthropic usage buckets (`cacheCreationInputTokens`, `cacheReadInputTokens`, `serviceTier`, server tool usage) are preserved in response metadata for inspection.

The Anthropic API reports token counts but no dollar cost, so the provider derives the exact request cost for documented Claude models from the raw billing buckets — uncached input at the base rate, cache writes at 1.25x (5-minute TTL) or 2x (1-hour TTL), cache reads at the model-specific cached-input rate, and output (including thinking tokens) at the output rate. This provider-reported cost takes precedence over a flat `inputPrice`/`outputPrice` calculation, so you do not need to set prices on models in the known-pricing table. For custom or future model IDs without table entries, set `inputPrice` and `outputPrice` on the model definition.

## Supported Models

All Claude models are supported (model IDs starting with `claude-`). The model picker lists live data from the Anthropic Models API, including context window, output limits, and per-model capabilities.

**API Key:** Set `ANTHROPIC_API_KEY` environment variable

**Package:** `@standardagents/anthropic`