npm package: @sisu-ai/adapter-anthropic
Description: Connect Sisu to Anthropic models with first-class tool calling, streaming, and vision input support.
Latest version: 10.0.0

# @sisu-ai/adapter-anthropic

Connect Sisu to Anthropic models with first-class tool calling, streaming, and vision input support.

[![Tests](https://github.com/finger-gun/sisu/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/finger-gun/sisu/actions/workflows/tests.yml)
[![CodeQL](https://github.com/finger-gun/sisu/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/finger-gun/sisu/actions/workflows/github-code-scanning/codeql)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/finger-gun/sisu/blob/main/LICENSE)
[![Downloads](https://img.shields.io/npm/dm/%40sisu-ai%2Fadapter-anthropic)](https://www.npmjs.com/package/@sisu-ai/adapter-anthropic)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/finger-gun/sisu/blob/main/CONTRIBUTING.md)

## Setup
```bash
npm i @sisu-ai/adapter-anthropic
```

- Env: `API_KEY`
- Optional base URL: `BASE_URL`
- Optional debug: `DEBUG_LLM=1` to log redacted request/response summaries on errors

## Transport and compatibility

- The adapter now uses the official `@anthropic-ai/sdk` Messages API transport.
- Public Sisu behavior is intentionally preserved: message normalization, tool-call mapping, streaming `token`/`assistant_message` events, and usage mapping.
- Existing app code should continue to work unchanged. If you relied on low-level fetch stubs in tests, prefer `Response`-compatible mocks or SDK-boundary mocks.

## Usage
```ts
import { anthropicAdapter, anthropicEmbeddings } from '@sisu-ai/adapter-anthropic';

const model = anthropicAdapter({ model: 'claude-3-5-sonnet-20240620' });
// with a self-hosted proxy
const model = anthropicAdapter({ model: 'claude-3-opus-20240229', baseUrl: 'https://api.anthropic.com' });

const embeddings = anthropicEmbeddings({
  baseUrl: process.env.EMBEDDINGS_BASE_URL!,
  model: process.env.EMBEDDINGS_MODEL!,
  apiKey: process.env.EMBEDDINGS_API_KEY,
});
```

## Embeddings
- Anthropic does not provide a native embeddings API.
- `anthropicEmbeddings(...)` is a convenience helper for Anthropic-centered apps that use a compatible third-party embeddings endpoint.
- You must pass `baseUrl` and `model` explicitly; there are no Anthropic-specific defaults.

## Tools
- Sends `tools` in Anthropic format (`name`, `description`, `input_schema`).
- Sends `tool_choice` only when `tools` exist (Anthropic rejects `tool_choice` without tools).
- Maps assistant tool calls to `{ id, name, arguments }` for the middleware loop.
- Maps tool results into Anthropic `tool_result` blocks and back.

## Vision
- Supports mixed text + image user messages.
- Accepts content parts (`content` / `contentParts`) with `{ type: 'text', text }` and `{ type: 'image_url', image_url }`.
- Accepts convenience fields: `image`, `image_url`, `images`, `image_urls`.
- Image inputs may be:
  - `data:image/...;base64,...` URLs
  - raw base64 payloads
  - remote `http(s)` URLs (fetched and converted to base64 before API call)

## Streaming
- Supports server‑sent events from the Messages API.
- Emits `{ type: 'token', token }` events for content deltas and a final `{ type: 'assistant_message', message }`.

## Options
```ts
anthropicAdapter({
  model: 'claude-3-5-sonnet-20240620',
  apiKey?: string,            // default: API_KEY
  baseUrl?: string,           // default: https://api.anthropic.com (or BASE_URL)
  anthropicVersion?: string,  // default: 2023-06-01
  timeout?: number,           // default: 60000 ms
  maxRetries?: number,        // default: 3 (with backoff; 4xx except 429 are not retried)
});
```

## Message mapping
- System messages → `system` string (joined if multiple system messages appear)
- User messages → text blocks and (optionally) image blocks with Anthropic base64 image sources
- Assistant messages with tool calls → `tool_use` blocks with `{ id, name, input }`
- Tool messages → user `tool_result` blocks with `{ tool_use_id | name, content }`

## Usage reporting
The adapter maps `usage.input_tokens` and `usage.output_tokens` to `{ promptTokens, completionTokens, totalTokens }`.

## Debugging
- `DEBUG_LLM=1` prints sanitized payloads and error bodies.
- Combine with your app logger’s `LOG_LEVEL=debug` to see middleware events.

# Community & Support

Discover what you can do through examples or documentation. Check it out at https://github.com/finger-gun/sisu. Example projects live under [`examples/`](https://github.com/finger-gun/sisu/tree/main/examples) in the repo.


- [Code of Conduct](https://github.com/finger-gun/sisu/blob/main/CODE_OF_CONDUCT.md)
- [Contributing Guide](https://github.com/finger-gun/sisu/blob/main/CONTRIBUTING.md)
- [License](https://github.com/finger-gun/sisu/blob/main/LICENSE)
- [Report a Bug](https://github.com/finger-gun/sisu/issues/new?template=bug_report.md)
- [Request a Feature](https://github.com/finger-gun/sisu/issues/new?template=feature_request.md)

---

## Documentation

**Core** — [Package docs](packages/core/README.md) · [Error types](packages/core/ERROR_TYPES.md)

**Adapters** — [OpenAI](packages/adapters/openai/README.md) · [Anthropic](packages/adapters/anthropic/README.md) · [Ollama](packages/adapters/ollama/README.md)

<details>
<summary>All middleware packages</summary>

- [@sisu-ai/mw-agent-run-api](packages/middleware/agent-run-api/README.md)
- [@sisu-ai/mw-context-compressor](packages/middleware/context-compressor/README.md)
- [@sisu-ai/mw-control-flow](packages/middleware/control-flow/README.md)
- [@sisu-ai/mw-conversation-buffer](packages/middleware/conversation-buffer/README.md)
- [@sisu-ai/mw-cors](packages/middleware/cors/README.md)
- [@sisu-ai/mw-error-boundary](packages/middleware/error-boundary/README.md)
- [@sisu-ai/mw-guardrails](packages/middleware/guardrails/README.md)
- [@sisu-ai/mw-invariants](packages/middleware/invariants/README.md)
- [@sisu-ai/mw-orchestration](packages/middleware/orchestration/README.md)
- [@sisu-ai/mw-rag](packages/middleware/rag/README.md)
- [@sisu-ai/mw-react-parser](packages/middleware/react-parser/README.md)
- [@sisu-ai/mw-register-tools](packages/middleware/register-tools/README.md)
- [@sisu-ai/mw-tool-calling](packages/middleware/tool-calling/README.md)
- [@sisu-ai/mw-trace-viewer](packages/middleware/trace-viewer/README.md)
- [@sisu-ai/mw-usage-tracker](packages/middleware/usage-tracker/README.md)
</details>

<details>
<summary>All tool packages</summary>

- [@sisu-ai/tool-aws-s3](packages/tools/aws-s3/README.md)
- [@sisu-ai/tool-azure-blob](packages/tools/azure-blob/README.md)
- [@sisu-ai/tool-extract-urls](packages/tools/extract-urls/README.md)
- [@sisu-ai/tool-github-projects](packages/tools/github-projects/README.md)
- [@sisu-ai/tool-rag](packages/tools/rag/README.md)
- [@sisu-ai/tool-summarize-text](packages/tools/summarize-text/README.md)
- [@sisu-ai/tool-terminal](packages/tools/terminal/README.md)
- [@sisu-ai/tool-web-fetch](packages/tools/web-fetch/README.md)
- [@sisu-ai/tool-web-search-duckduckgo](packages/tools/web-search-duckduckgo/README.md)
- [@sisu-ai/tool-web-search-google](packages/tools/web-search-google/README.md)
- [@sisu-ai/tool-web-search-openai](packages/tools/web-search-openai/README.md)
- [@sisu-ai/tool-wikipedia](packages/tools/wikipedia/README.md)
</details>

<details>
<summary>All RAG packages</summary>

- [@sisu-ai/rag-core](packages/rag/core/README.md)
</details>

<details>
<summary>All vector packages</summary>

- [@sisu-ai/vector-core](packages/vector/core/README.md)
- [@sisu-ai/vector-chroma](packages/vector/chroma/README.md)
</details>

<details>
<summary>All examples</summary>

**Anthropic** — [hello](examples/anthropic-hello/README.md) · [control-flow](examples/anthropic-control-flow/README.md) · [stream](examples/anthropic-stream/README.md) · [vision](examples/anthropic-vision/README.md) · [weather](examples/anthropic-weather/README.md)

**Ollama** — [hello](examples/ollama-hello/README.md) · [stream](examples/ollama-stream/README.md) · [vision](examples/ollama-vision/README.md) · [weather](examples/ollama-weather/README.md) · [web-search](examples/ollama-web-search/README.md)

**OpenAI** — [hello](examples/openai-hello/README.md) · [weather](examples/openai-weather/README.md) · [stream](examples/openai-stream/README.md) · [vision](examples/openai-vision/README.md) · [reasoning](examples/openai-reasoning/README.md) · [react](examples/openai-react/README.md) · [control-flow](examples/openai-control-flow/README.md) · [branch](examples/openai-branch/README.md) · [parallel](examples/openai-parallel/README.md) · [graph](examples/openai-graph/README.md) · [orchestration](examples/openai-orchestration/README.md) · [orchestration-adaptive](examples/openai-orchestration-adaptive/README.md) · [guardrails](examples/openai-guardrails/README.md) · [error-handling](examples/openai-error-handling/README.md) · [rag-chroma](examples/openai-rag-chroma/README.md) · [web-search](examples/openai-web-search/README.md) · [web-fetch](examples/openai-web-fetch/README.md) · [wikipedia](examples/openai-wikipedia/README.md) · [terminal](examples/openai-terminal/README.md) · [github-projects](examples/openai-github-projects/README.md) · [server](examples/openai-server/README.md) · [aws-s3](examples/openai-aws-s3/README.md) · [azure-blob](examples/openai-azure-blob/README.md)
</details>

---

## Contributing

We build Sisu in the open. Contributions welcome.

[Contributing Guide](CONTRIBUTING.md) · [Report a Bug](https://github.com/finger-gun/sisu/issues/new?template=bug_report.md) · [Request a Feature](https://github.com/finger-gun/sisu/issues/new?template=feature_request.md) · [Code of Conduct](CODE_OF_CONDUCT.md)

---

<div align="center">

**[Star on GitHub](https://github.com/finger-gun/sisu)** if Sisu helps you build better agents.

*Quiet, determined, relentlessly useful.*

[Apache 2.0 License](LICENSE)

</div>