@use-crux/anthropic

Anthropic SDK adapter for Crux. Runs Crux prompts and agents directly against Claude models through the official @anthropic-ai/sdk client.

Orchestration — prompt composition, context engineering, memory, tools, agents — lives in @use-crux/core. This package is the binding: createAnthropic() wraps an Anthropic client through the single-turn anthropicProviderRuntime and owns no orchestration logic of its own. It is generation-only; pair it with embedding() from @use-crux/ai or another provider for retrieval/indexing.

Install

pnpm add @use-crux/anthropic @use-crux/core @anthropic-ai/sdk

@anthropic-ai/sdk is a peer dependency (>=0.74.0).

Usage

import { prompt } from "@use-crux/core";
import { createAnthropic } from "@use-crux/anthropic";
import Anthropic from "@anthropic-ai/sdk";

const anthropic = createAnthropic(
  new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
);

const fixTypos = prompt({
  id: "fix-typos",
  template: ({ instruction }: { instruction: string }) => instruction,
});

const result = await anthropic.generate(fixTypos, {
  model: "claude-sonnet-4-5-20250929",
  input: { instruction: "Fix typos" },
});

result.text; // extracted text
result.raw; // raw Anthropic.Message

generate() returns the canonical Crux envelope: text, object when present, optional accumulated usage, optional cost, steps, finalStep, provider-neutral messages, typed raw, and retained _meta for observability. usage is present only when every provider-call step reported usage. stream() returns { textStream, raw, completion }, where completion resolves to the same envelope fields without raw/_meta.

createAnthropic() returns a CruxAdapter with generate(), stream(), and agent composition methods (parallel, pipeline, consensus, swarm). Use createGenerateObjectFn(client, model) / createGenerateTextFn(client, model) to satisfy @use-crux/core APIs that expect a generate function (e.g. llmJudge, summarizeMessages). createGenerateObjectFn() is provider-native: it uses Anthropic structured parsing and preserves provider errors, but it does not run Crux prompt resolution, validation retry, safety, cassettes, tools, memory, or instrumentation. Use createGenerateObjectFnFromGenerate(generate) from @use-crux/core/compaction when a helper call needs full adapter runtime behavior.

For headless use, toParams(resolved, { model }) converts a resolved prompt into Anthropic request params and fromResponse(response) normalizes an Anthropic response into Crux response facts. adapter.prepare(prompt, opts) returns a sans-I/O handle with params, step(response), and finish(response). The handle uses the same Crux executor as generate(), so tools, approvals, typed tool context, validation retry, safety, memory capture, and observability stay managed by Crux while your code owns client.messages.create(call.params).

Use generate(prompt, { ...opts, transport }) when Crux should keep owning the loop and your callback should make each Anthropic call from public params. Streaming with transport is not supported and rejects with CruxTransportStreamUnsupportedError.

The package exports anthropicProviderRuntime for advanced adapter composition. Internally, Anthropic uses defineSingleTurnProviderBundle() from @use-crux/core/adapter; adapter authors building similar single-turn providers should start there.

Crux maps portable GenerationSettings.toolChoice values to Anthropic tool_choice: 'auto' → { type: 'auto' }, 'none' → { type: 'none' }, 'required' → { type: 'any' }, and { tool } → { type: 'tool', name }. Portable reasoning maps to Claude thinking budgets (low 2k, medium 8k, high 24k tokens). toolApproval declares portable human-in-the-loop approval policy by tool name at context, prompt, or call site. Tools that declare contextSchema require toolsContext.<toolName> at the call site, and runtimeContext is threaded through tool execution, middleware, and function-form approval policies. timeout accepts structured budgets (totalMs, stepMs, chunkMs, toolMs, and tools[name]) and expired budgets reject with TimeoutError. Anthropic-native options that Crux does not model portably belong in the typed extra option.

For provider prompt caching, Crux resolves cached contexts into a stable prefix and marks the final cached SystemBlock with cacheBoundary. This adapter places Anthropic cache_control: { type: 'ephemeral' } on that boundary block only.

Message and Tool-Round Serialization

Anthropic provider-history conversion is owned inside this package. The public toMessages() and fromMessages() helpers are wrappers over the same codec used by createAnthropic() for request messages, assistant tool-call extraction, and second-call tool-loop transcripts.

Anthropic has no native tool role, so canonical Crux tool messages become user messages with tool_result content blocks. Assistant tool calls become ordered tool_use blocks alongside optional text. Rich tool outputs keep native Anthropic image and PDF blocks where supported, and unsupported media falls back to deterministic text references.

See the @use-crux/core reference and the Crux docs for the full API.

Media boundary

Anthropic messages support native image and PDF/document content, including supported tool output. Audio and video reject before provider I/O. The package structurally omits generateImage(), transcribe(), and generateSpeech(); there are no throwing stubs or runtime capability query.