@flink-app/anthropic-adapter

Anthropic Claude adapter for the Flink AI framework. Provides seamless integration with Anthropic's Claude models.

Installation

npm install @flink-app/anthropic-adapter
# or
pnpm add @flink-app/anthropic-adapter

The @anthropic-ai/sdk package is included as a dependency, so you don't need to install it separately.

Usage

Basic Setup

import { AnthropicAdapter } from "@flink-app/anthropic-adapter";
import { FlinkApp } from "@flink-app/flink";

const app = new FlinkApp({
  ai: {
    llms: {
      default: new AnthropicAdapter({
        apiKey: process.env.ANTHROPIC_API_KEY!,
        model: "claude-sonnet-4-5-20250929"
      }),
    },
  },
});

await app.start();

Legacy API (still supported):

// Backward-compatible constructor
new AnthropicAdapter(process.env.ANTHROPIC_API_KEY!, "claude-sonnet-4-5-20250929")

Agent Instructions

Define your agent's behavior using the instructions property:

// src/agents/support_agent.ts
export const Agent: FlinkAgentProps = {
  name: "support_agent",
  instructions: "You are a helpful customer support agent.",
  tools: ["get_order_status"],
  model: { adapterId: "default" },
};

How it works:

• Instructions are prepended as a system message to every conversation
• Follows Vercel AI SDK pattern for consistency
• Provides stable agent behavior across all interactions

Dynamic Context with System Messages

For per-request context, add system messages to the conversation:

const result = await ctx.agents.myAgent.execute({
  message: [
    { role: "system", content: "Current user tier: Premium" },
    { role: "user", content: "What can I do?" }
  ]
});

Order of messages sent to Anthropic:

1. Agent instructions (as system message)
2. User-provided system messages (if any)
3. Conversation messages

This gives you both static agent behavior and dynamic per-request context.

Multiple Adapters

You can register multiple Anthropic adapters with different configurations:

import { AnthropicAdapter } from "@flink-app/anthropic-adapter";
import { FlinkApp } from "@flink-app/flink";

const app = new FlinkApp({
  ai: {
    llms: {
      // Default Sonnet 4.5 model - best balance of intelligence, speed, and cost
      default: new AnthropicAdapter({
        apiKey: process.env.ANTHROPIC_API_KEY!,
        model: "claude-sonnet-4-5-20250929"
      }),

      // Fast Haiku 4.5 model for simple tasks - near-frontier performance at lower cost
      fast: new AnthropicAdapter({
        apiKey: process.env.ANTHROPIC_API_KEY!,
        model: "claude-haiku-4-5-20251001"
      }),

      // Opus 4.5 model for complex tasks - maximum intelligence
      smart: new AnthropicAdapter({
        apiKey: process.env.ANTHROPIC_API_KEY!,
        model: "claude-opus-4-5-20251101"
      }),
    },
  },
});

Using in Agents

Reference the adapter by its registered ID in your agent configuration:

// src/agents/support_agent.ts
import { FlinkAgentProps } from "@flink-app/flink";

export const Agent: FlinkAgentProps = {
  name: "support_agent",
  description: "Customer support assistant",
  instructions: "You are a helpful customer support agent.",
  tools: ["get_order_status"],
  model: {
    adapterId: "default", // Uses the "default" adapter
    maxTokens: 1000,
    temperature: 0.7,
  },
};

Supported Models

This adapter works with all Claude models. The latest Claude 4.5 models offer significant improvements over previous generations:

Claude 4.5 Models (Recommended)

• Claude Sonnet 4.5: claude-sonnet-4-5-20250929 (recommended for most use cases)

  • Best balance of intelligence, speed, and cost
  • Exceptional performance in coding and agentic tasks
  • 200K context window (1M in beta with header)
  • Pricing: $3/MTok input, $15/MTok output

• Claude Haiku 4.5: claude-haiku-4-5-20251001 (fastest)

  • Near-frontier performance at a fraction of the cost
  • Optimized for speed and cost-efficiency
  • 200K context window
  • Pricing: $1/MTok input, $5/MTok output

• Claude Opus 4.5: claude-opus-4-5-20251101 (most capable)

  • Maximum intelligence for complex tasks
  • Industry leader in coding, agents, and enterprise workflows
  • 200K context window
  • Pricing: $5/MTok input, $25/MTok output

Legacy Models

For backwards compatibility, legacy Claude 3 and 4 models are still supported:

• Claude Opus 4.1: claude-opus-4-1-20250805
• Claude Sonnet 4: claude-sonnet-4-20250514
• Claude 3.7 Sonnet: claude-3-7-sonnet-20250219
• Claude Opus 4: claude-opus-4-20250514
• Claude 3 Haiku: claude-3-haiku-20240307

We recommend migrating to Claude 4.5 models for improved performance and capabilities.

Model Aliases vs Specific Versions

Anthropic provides both specific version IDs and aliases:

• Specific versions (e.g., claude-sonnet-4-5-20250929): Fixed model snapshots that never change

  • Recommended for production to ensure consistent behavior
  • Snapshot date indicates the exact model version

• Aliases (e.g., claude-sonnet-4-5): Automatically point to the latest snapshot

  • Useful for development and experimentation
  • Updated within a week of new releases
  • May change behavior when new snapshots are released

Example:

// Production: Use specific version for stability
new AnthropicAdapter(apiKey, "claude-sonnet-4-5-20250929")

// Development: Use alias to always get latest improvements
new AnthropicAdapter(apiKey, "claude-sonnet-4-5")

Features

• ✅ Full tool calling support with automatic schema sanitization
• ✅ Streaming with event-based updates
• ✅ Proper message conversion and system instruction handling
• ✅ Comprehensive error handling with helpful messages
• ✅ Token usage tracking
• ✅ Debug logging for tool calls
• ✅ Support for all Claude 4.5 models
• ✅ 200K token context window (1M in beta)
• ✅ Extended thinking capabilities

Claude 4.5 Capabilities

All Claude 4.5 models support:

• Extended Thinking: Enhanced reasoning for complex problems
• Vision: Process and analyze images alongside text
• Multilingual: Strong performance across multiple languages
• Long Context: 200K tokens standard, 1M tokens in beta
• Tool Use: Sophisticated function calling and tool integration

API

AnthropicAdapter

interface AnthropicAdapterOptions {
  apiKey: string;
  model: string;
}

class AnthropicAdapter implements LLMAdapter {
  constructor(options: AnthropicAdapterOptions);
  constructor(apiKey: string, model: string); // Legacy
}

Parameters

• apiKey: Your Anthropic API key
• model: The Claude model to use (e.g., "claude-sonnet-4-5-20250929")

Error Handling

The adapter provides comprehensive error handling with helpful messages:

• 400 Bad Request: Invalid model name, malformed messages, or invalid tool schemas
• 401 Unauthorized: Invalid API key - check your ANTHROPIC_API_KEY
• 403 Forbidden: Insufficient permissions or account limitations
• 429 Too Many Requests: Rate limit exceeded - consider retry logic
• 500/529 Server Error: Temporary issue with Anthropic's servers - retry recommended

All errors include the model name and specific guidance for resolution.

Model Selection Tips

• Use Sonnet 4.5 (claude-sonnet-4-5-20250929) as your default - it provides the best balance for most applications
• Use Haiku 4.5 (claude-haiku-4-5-20251001) for high-volume, cost-sensitive workloads where speed matters
• Use Opus 4.5 (claude-opus-4-5-20251101) for complex reasoning, advanced coding, or when maximum intelligence is required

You can also use model aliases like claude-sonnet-4-5 which automatically point to the latest snapshot, though specific version IDs are recommended for production to ensure consistent behavior.

Migrating from Claude 3 to Claude 4.5

If you're currently using Claude 3 models, simply update the model ID in your adapter configuration:

// Before (Claude 3.5 Sonnet)
new AnthropicAdapter(apiKey, "claude-3-5-sonnet-20241022")

// After (Claude Sonnet 4.5)
new AnthropicAdapter(apiKey, "claude-sonnet-4-5-20250929")

Benefits of upgrading to Claude 4.5:

• Better performance: Improved reasoning and coding capabilities
• Extended thinking: Built-in support for complex problem-solving
• Lower latency: Faster response times (especially Haiku 4.5)
• Better cost efficiency: Haiku 4.5 offers near-frontier performance at lower cost

The adapter handles all API differences automatically - no code changes required beyond the model ID.

Requirements

• Node.js >= 18
• @flink-app/flink >= 1.0.0
• @anthropic-ai/sdk >= 0.30.0

License

MIT