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

# Anthropic API Engine

> @obversa/engine-anthropic-api: text-only requests straight to the Anthropic Messages API, no process.

`@obversa/engine-anthropic-api` calls the Anthropic Messages API directly:
it streams tokens as they arrive and starts no command-line process. Use it
for a seat that only needs text, a judge or a scorer, where a coding agent's
tools and workspace would be wasted.

It loads none of your own setup, so it always runs clean and has no `clean` option. Its
row in the [engines table](/docs/packages/engines#the-engines) says the same.

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install @obversa/engine-anthropic-api
  ```

  ```bash pnpm theme={null}
  pnpm add @obversa/engine-anthropic-api
  ```
</CodeGroup>

Included in `@obversa/obversa`.

## Requirements

* An Anthropic API key, in the `ANTHROPIC_API_KEY` environment variable or
  the `apiKey` option.

## Identity

The plugin reports `provider: 'anthropic'`, with the model family read from
the model name. It runs the model the request names; without one it uses
`defaultModel`, and without that `claude-haiku-4-5-20251001`.

## Quickstart

Construct the engine and ask it what it will run as, with no network call:

```ts examples/engine-anthropic-api-binding.ts {4-7,9} theme={null}
import { AnthropicApiEngine } from '@obversa/engine-anthropic-api';

// The key is a placeholder. `admit` reads it and sends nothing.
const engine = new AnthropicApiEngine({
  defaultModel: 'claude-haiku-4-5-20251001',
  apiKey: 'example-key',
});

const identity = await engine.admit({ workspaceMode: 'none' }, new AbortController().signal);
console.log(JSON.stringify(identity, null, 2));
```

`admit` returns the identity the engine reports before any request: the
adapter, provider, model family, model and capabilities. Run it with
`npx tsx engine-anthropic-api-binding.ts`:

```json Output theme={null}
{
  "adapter": "anthropic-api",
  "adapterVersion": null,
  "provider": "anthropic",
  "modelFamily": null,
  "model": "claude-haiku-4-5-20251001",
  "executable": null,
  "capabilities": []
}
```

In a run, leave `apiKey` out and set `ANTHROPIC_API_KEY`, then pass the
engine to `run()` in `engines` or bind it to a graph node.

## Options

| Field | Type | Default | Description |
| - | - | - | - |
| `defaultModel` | `string` | `'claude-haiku-4-5-20251001'` | The wire model when the request names none. |
| `apiKey` | `string` | `process.env.ANTHROPIC_API_KEY` | The API key. |
| `effort` | `string` | none | Sent as `output_config.effort`. A request's `effort` wins. See [Reasoning effort](/docs/packages/engines#reasoning-effort). |

## Errors

* **A missing key** fails with a message that names both places to put it,
  and points at the agent-sdk and claude-cli engines, which use the host's
  Claude sign-in instead.
* **A request that asks for tools or workspace access** fails as
  `invalid-config`: the engine takes text-only requests. It ignores
  `AgentRequest.env`, because there's no process to pass it to.
* **Server errors (HTTP 5xx) and connection errors**, timeouts included, are
  retried. **A rate limit (HTTP 429)** fails as `rate-limit`, carrying the
  API's `retry-after` wait when it sends one.

## API

* **`AnthropicApiEngine`**: the engine class. **`AnthropicApiEngineOptions`**:
  its options. [Quickstart](#quickstart).

## Next steps

* [Evals in an agent workflow](/docs/reviewing/evals): the judge and scorer seats
  this engine suits.
* [Claude Agent SDK Engine](/docs/packages/engine-claude-agent-sdk): Claude with
  tools and memory, through the host's sign-in.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.