elizaos--eliza/plugins/plugin-anthropic

@elizaos/plugin-anthropic

Anthropic Claude model provider for elizaOS. Adds Claude text generation, streaming, image description, and structured JSON output to any Eliza agent.

What it does

This plugin registers Claude model handlers into the elizaOS model dispatch layer. Once loaded, calls to runtime.useModel() for any text, reasoning, or image-description model type are routed to the Anthropic API (or Claude Code CLI, or OAuth subscription, depending on your auth mode).

Capabilities added:

• Text generation — all ModelType tiers: TEXT_NANO, TEXT_SMALL, TEXT_MEDIUM, TEXT_LARGE, TEXT_MEGA, RESPONSE_HANDLER, ACTION_PLANNER
• Reasoning — TEXT_REASONING_SMALL and TEXT_REASONING_LARGE with configurable chain-of-thought token budget
• Image description — IMAGE_DESCRIPTION returns { title, description } from an image URL
• Streaming — all text handlers support stream: true, returning an async TextStreamResult
• Structured output — pass responseSchema (JSON Schema) to any text handler to receive parsed JSON
• Tool calling — pass tools, toolChoice to any text handler for native Anthropic tool use
• Prompt caching — cache_control: ephemeral applied automatically to system prompts and stable prompt segments

Auto-enable

The plugin is automatically enabled when ANTHROPIC_API_KEY or CLAUDE_API_KEY is present in the environment. No manual plugin registration is needed in that case.

To register manually:

import { anthropicPlugin } from "@elizaos/plugin-anthropic";
import { AgentRuntime } from "@elizaos/core";

const runtime = new AgentRuntime({
  plugins: [anthropicPlugin],
  // ...
});

Usage

import { ModelType } from "@elizaos/core";

// Text generation
const text = await runtime.useModel(ModelType.TEXT_LARGE, {
  prompt: "Explain quantum computing in simple terms",
});

// Streaming
const result = await runtime.useModel(ModelType.TEXT_LARGE, {
  prompt: "Count from 1 to 5.",
  stream: true,
  onStreamChunk: (chunk) => process.stdout.write(chunk),
});

// Structured output
const obj = await runtime.useModel(ModelType.TEXT_SMALL, {
  prompt: "Return a JSON object with a greeting field.",
  responseSchema: {
    type: "object",
    properties: { greeting: { type: "string" } },
    required: ["greeting"],
  },
});

// Image description
const { title, description } = await runtime.useModel(ModelType.IMAGE_DESCRIPTION, {
  imageUrl: "https://example.com/photo.jpg",
});

Configuration

Env var	Required	Default	Description
ANTHROPIC_API_KEY	Yes*	—	Anthropic API key (sk-ant-...)
CLAUDE_API_KEY	Alt	—	Alias accepted alongside ANTHROPIC_API_KEY
ANTHROPIC_AUTH_MODE	No	apikey	Auth mode: apikey, oauth, or claude-cli
ANTHROPIC_SMALL_MODEL	No	claude-haiku-4-5-20251001	Model for small-tier calls
ANTHROPIC_LARGE_MODEL	No	claude-opus-4-7	Model for large-tier calls
ANTHROPIC_NANO_MODEL	No	(small fallback)	Model for TEXT_NANO
ANTHROPIC_MEDIUM_MODEL	No	(small fallback)	Model for TEXT_MEDIUM
ANTHROPIC_MEGA_MODEL	No	(large fallback)	Model for TEXT_MEGA
ANTHROPIC_REASONING_SMALL_MODEL	No	(small fallback)	Model for TEXT_REASONING_SMALL
ANTHROPIC_REASONING_LARGE_MODEL	No	(large fallback)	Model for TEXT_REASONING_LARGE
ANTHROPIC_BASE_URL	No	https://api.anthropic.com/v1	API base URL override
ANTHROPIC_BROWSER_BASE_URL	No	—	Proxy URL for browser builds
ANTHROPIC_COT_BUDGET	No	0	Chain-of-thought token budget (0 = disabled)
ANTHROPIC_COT_BUDGET_SMALL	No	—	CoT budget for small-size models
ANTHROPIC_COT_BUDGET_LARGE	No	—	CoT budget for large-size models
ANTHROPIC_PROMPT_CACHE_TTL	No	5m	Prompt cache TTL: "5m" or "1h"
ANTHROPIC_EXPERIMENTAL_TELEMETRY	No	false	Enable Vercel AI SDK telemetry

* Required unless ANTHROPIC_AUTH_MODE=oauth or ANTHROPIC_AUTH_MODE=claude-cli.

OAuth mode

Set ANTHROPIC_AUTH_MODE=oauth. Token is read from (in order):

1. CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_OAUTH_TOKEN env var
2. macOS keychain (Claude Code-credentials)
3. ~/.claude/.credentials.json (or $CLAUDE_CONFIG_DIR/.credentials.json)

Run claude auth login (Claude Code CLI) to populate the credential store.

CLI mode

Set ANTHROPIC_AUTH_MODE=claude-cli. Requires the claude binary on PATH (install from code.claude.com). Invokes claude -p for each model call. Does not support messages, tools, toolChoice, or responseSchema.

Caveats

• Opus 4.x models only accept temperature=1. The plugin enforces this automatically.
• temperature and topP are mutually exclusive in the Anthropic API. Supplying both logs a warning and drops topP.
• maxTokens is capped at 32k (Opus 4) or 64k (all others) to avoid API 400 errors.
• Browser builds (exports.browser) never access process.env. Set ANTHROPIC_BROWSER_BASE_URL to a server-side proxy; do not expose your API key in client-side code.

Development

bun run --cwd plugins/plugin-anthropic build
bun run --cwd plugins/plugin-anthropic test
bun run --cwd plugins/plugin-anthropic typecheck

For agent-facing documentation (file layout, how to add handlers, extension steps), see CLAUDE.md.