@flink-app/人类适应器

Flink AI框架的Anthropic Claude适配器. 提供与Anthropic的克洛德模型的无缝融合.

安装

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

这个 @anthropic-ai/sdk 软件包包含为依赖,所以不需要单独安装.

使用量

基本设置

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();

遗产 API( 仍然支持 ):

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

代理指令

使用 instructions 属性 :

// 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" },
};

如何运作:

• 指令是作为系统信息准备给每个对话
• 遵循 Vercel AI SDK 一致性模式
• 在所有相互作用中提供稳定的代理行为

带有系统信件的动态上下文

对于每个请求上下文,在对话中添加系统消息:

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

发送到 Anthropic 的信件顺序 :

1. 探员 instructions (作为系统消息)
2. 用户提供的系统信息(如果有的话)
3. 对话消息

这给您带来了静态代理行为和动态的每个请求上下文.

多个适配器

可以注册多个具有不同配置的Anthropic适配器:

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"
      }),
    },
  },
});

用于代理

在代理配置中引用适配器注册的ID:

// 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,
  },
};

支持的模式

这个适配器与所有的克洛德模型一起工作. 最新的Claude 4.5模式比前几代有重大改进:

Claude 4.5 型号(建议)

• 克劳德·索内 4.5数字 : claude-sonnet-4-5-20250929 (建议大多数使用情况)

  • 智能、速度和成本的最佳平衡
  • 编码和代理任务的特殊表现
  • 200K 上下文窗口 (1M 在β 有标题)
  • 定价:3美元/MTok投入,15美元/MTok产出

• 克劳德·海库 4.5数字 : claude-haiku-4-5-20251001 (快讯)

  • 近岸业绩,成本的一小部分
  • 优化速度和成本效益
  • 200K 上下文窗口
  • 定价:1美元/MTok投入,5美元/MTok产出

• 克劳德·奥普斯 4.5数字 : claude-opus-4-5-20251101 (最有能力)

  • 复杂任务的最大智能
  • 编码、代理和企业工作流程行业领先
  • 200K 上下文窗口
  • 定价:5美元/MTok投入,25美元/MTok产出

遗产模式

对于后向相容性,遗留克洛德3和4型仍然支持:

• 克洛德·奥普斯 4.1数字 : claude-opus-4-1-20250805
• 克洛德·索内特 4数字 : claude-sonnet-4-20250514
• 克洛德·3.7 索内数字 : claude-3-7-sonnet-20250219
• 克洛德·奥普斯4数字 : claude-opus-4-20250514
• 克劳德 三海库数字 : claude-3-haiku-20240307

我们建议改用克洛德4.5模式,以提高业绩和能力.

模型异名对特定版本

Anthropic 提供了特定的版本ID和别名:

• 特定版本 (例如, claude-sonnet-4-5-20250929:永远不变的固定模型快照

  • 建议制作以确保行为一致
  • 快照日期表示准确的模型版本

• 别名 (例如, claude-sonnet-4-5: 自动指向最新的快照

  • 有利于发展和实验
  • 在新发布一周内更新
  • 发布新快照时可能改变行为

示例

// 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")

缓存计量和成本优化

Anthropic 适配器自动捕捉到详细的缓存度量衡来帮助您优化成本并理解性能:

const result = await ctx.agents.myAgent.execute({
  message: "Analyze this large document..."
});

console.log(result.usage);
// {
//   inputTokens: 3000,
//   outputTokens: 500,
//   cachedInputTokens: 2000,         // Tokens read from cache (10% cost)
//   cacheCreationInputTokens: 500    // Tokens written to cache (125% cost)
// }

// Calculate actual billed tokens with Anthropic's pricing
const regularTokens = result.usage.inputTokens -
  (result.usage.cachedInputTokens || 0) -
  (result.usage.cacheCreationInputTokens || 0);

const cacheReadCost = (result.usage.cachedInputTokens || 0) * 0.1;
const cacheWriteCost = (result.usage.cacheCreationInputTokens || 0) * 1.25;
const regularCost = regularTokens * 1.0;

console.log(`Cost breakdown:`);
console.log(`- Regular tokens: ${regularTokens} × 100% = ${regularCost}`);
console.log(`- Cache reads: ${result.usage.cachedInputTokens} × 10% = ${cacheReadCost}`);
console.log(`- Cache writes: ${result.usage.cacheCreationInputTokens} × 125% = ${cacheWriteCost}`);
console.log(`Total cost factor: ${regularCost + cacheReadCost + cacheWriteCost}`);
// "Total cost factor: 1325" (vs 3000 without caching) - 56% savings after initial cache write!

缓存量表 :

• inputTokens: 总输入符 (包括缓存和缓存写入)
• outputTokens: 总产出符号
• cachedInputTokens: 从缓存读取输入符( 10% 成本)
• cacheCreationInputTokens: 写入缓存的输入符 (125% 成本, 一次性)

急速缓存 :

• 快取读取:普通代币成本的10%(节省了90%!)
• 快取写入:125%的正常代币成本(一次性投资)
• 最低门槛值: 2048 个令牌(只激活于 ~2048 个令牌)
• 缓存寿命5分钟的不活动时间

缓存策略 : 对于反复出现的情况(系统提示、知识基础、少见的例子):

1. 第一项请求: 向缓存支付125%cacheCreationInputTokens(中文(简体) )
2. 随后提出的请求 (在5分钟内):支付10%从缓存读取(cachedInputTokens(中文(简体) )
3. 双向断面: 在2个缓存读取后,你开始储蓄
4. 长期: 大量节省经常使用的上下文

当缓存帮助最多时 :

• 对请求使用长的系统提示
• 二. 大的知识基础
• 提示中少见的例子
• 具有持续背景的多回合对话
• 多次分析文件

示例:系统提示缓存

// First request: Create cache
// inputTokens: 3000, cacheCreationInputTokens: 2500
// Cost: 500×1.0 + 2500×1.25 = 3625 tokens worth

// Second request: Read from cache
// inputTokens: 3000, cachedInputTokens: 2500
// Cost: 500×1.0 + 2500×0.1 = 750 tokens worth (79% savings!)

// Third+ requests: Continue reading from cache
// Same 79% savings as long as cache is active

扩展思维

Claude的思维是每个适配器的配置,然后逐字通过作为 thinking 请求参数,使用 effort 以 output_config.effort。两者都使用 SDK 的自有类型,因此API 支持的每一种模式都是可用的,无需修改适配器:

const adapter = new AnthropicAdapter({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-opus-5-5",
  thinking: { type: "adaptive", display: "summarized" }, // optional
  effort: "high",                                        // optional: low | medium | high | xhigh | max
});

在省略时,两个参数都不发送,模型的默认适用(克洛德5代默认运行适应性思维).

思考如何通过Flink:

• thinking 块为 reasoning 块并被物剂浮出水面 reasoning_delta 活动 fullStream。它们从未出现在 textStream 或者说 result.message与 display: "omitted" (当前模型上的默认)块以空文本到达,但仍带有签名.
• 每个 thinking 财务报告和审定财务报表 redacted_thinking 块是逐字保存的 (providerData.anthropic.thinkingBlocks)在助理留言和 在文本之前重播, 工具调用后关,Anthropic要求签名在整个工具使用中保持有效.
• 另一供应商制造的思维痕迹没有安特罗克的签名,被跳过.

结构化输出和工具选择

两者均由代理人每拨电话要求(model.structuredOutput 编号 : model.toolChoice,或 execute({ model: { ... } }); 普通案件适配器上没有配置任何内容.

结构化产出 以两种方式之一实现,由 structuredOutputMode数字 :

new AnthropicAdapter({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-3-5-sonnet-20241022",
  structuredOutputMode: "tool", // optional, auto-detected from the model by default
});

原生路径将图案减少为结构化的输出子集:数字和长度限制(minimum, (中文(简体) ), maxLength, (中文(简体) ), pattern,...) 被剥去,每个物体都得到 additionalProperties: false。Flink 仍然根据整个计划验证答案,所以在界限之外的一个值失败 StructuredOutputError 而不是通过.

当代理也拥有真正的工具时,后退会发出 tool_choice: { type: "any" } 所以模型仍然可以先调用这些,然后用输出工具完成. 打电话的人自己的 toolChoice 尊重: "none" 只留下输出工具, 强制真实工具会被强制用于该步骤。 虽然扩展思维是活性的(已配置,或克勞德5默认),但API拒绝强制,因此倒置后方请求在系统中输出工具会被及时提示并依赖于Flink的验证.

工具选择 地图进入 tool_choice数字 : "auto" → auto, (中文(简体) ), "none" → none, (中文(简体) ), "required" → any, (中文(简体) ), { type: "tool", name } → tool。只有当请求载有工具时才发送。 注意API拒绝强制选择(any 编号 : tool),而扩展思维是活性的,这是克洛德5代的默认;偏好 structuredOutput 当目标为JSON回复时.

特征

• QQ 使用自动疗程调用支持的完整工具
• * 扩展思维通过(thinking, (中文(简体) ), effort思想流出为 reasoning_delta 并逐个重复播放
• QQ 以事件为基础的更新流
• * 适当的消息转换和系统指令处理
• ++ 处理有帮助的信件的全面错误
• QQ 调用跟踪
• 用于工具呼叫的调试日志
• 支持所有Claude 4.5型号
• 200K令牌上下文窗口(1M in beta)
• * 扩展思维能力

Claude 4.5 能力

所有Claude 4.5模型都支持:

• 扩展思维:加强复杂问题的推理
• 愿景: 处理和分析图像与文本
• 多语言: 多种语文的有力表现
• 长背景: 200K 令牌标准, 1M 令牌以β为单位
• 工具的使用: 复杂函数调用和工具集成

API 密码

AnthropicAdapter

interface AnthropicAdapterOptions {
  apiKey: string;
  model: string;
  thinking?: Anthropic.ThinkingConfigParam;       // e.g. { type: "adaptive", display: "summarized" }
  effort?: "low" | "medium" | "high" | "xhigh" | "max";
  debug?: boolean;
}

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

参数

• apiKey: 您的 Anthropic API 密钥
• model: Claude模型要使用(例如"Claude-sonnet-4-5-20250929")
• thinking: 可选扩展思维配置,逐字发送为 thinking
• effort: 可选工作级别,作为 output_config.effort
• debug: 可选调试日志( 默认) false(中文(简体) )

处理错误

适配器以有帮助的信息提供全面的错误处理:

• 400 坏请求: 无效的模型名称、 错误的邮件或无效的工具计划
• 401 未经批准: 无效的 API 密钥 - 请检查您的 ATHROPIC API KEY
• 403 禁止使用: 权限不足或账户限制
• 429项过多的请求: 超过率限制 - 考虑重试逻辑
• 500/529 服务器出错: Anthropic服务器的临时问题 - 建议重试

所有错误包括模型名称和解析的具体指导.

模式选择提示

• 使用 索内 4.5 (单位:千美元)claude-sonnet-4-5-20250929)作为您的默认 - 它为大多数应用程序提供了最佳平衡
• 使用 哈伊库 4.5 (单位:千美元)claude-haiku-4-5-20251001在速度重要的情况下,用于高数量、成本敏感的工作量
• 使用 目标4.5 (单位:千美元)claude-opus-4-5-20251101)用于复杂推理,高级编码,或当需要最大智能时

您也可以使用模型化名, 如 claude-sonnet-4-5 它自动指向最新的快照,尽管建议制作特定的版本ID,以确保行为一致.

从克洛德3号搬到克洛德4.5号

如果您目前使用克洛德3型号,只需更新适配器配置中的模型ID:

// 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")

升级至克洛德4.5的好处:

• 业绩更好改进推理和编码能力
• 扩展思维: 支持复杂问题的解决
• 低潜伏度: 更快的反应时间(特别是海库4.5)
• 提高成本效益: Haiku 4.5 以更低的成本提供近端性能

适配器自动处理所有API差异——除型号ID外不需要代码更改.

所需资源

• 节点.js 18
• @flink-app/flink >= 1.0.0
• @humanic-ai/sdk 0.30.0 (英语)

许可证

麻省理工学院