主流模型 API

OpenAI、Anthropic、Google Gemini 均支持 对话 + 工具调用 +（部分）结构化输出，但 字段名、流式 tool call、上下文长度、定价 不同。Agent 网关要做 适配层，业务逻辑不要绑死一家 SDK。

学习目标

• 对照三家 Agent 相关 API 能力差异
• 会选择模型 tier（快/便宜 vs 强/贵）分工
• 理解 vendor lock-in 与抽象边界

能力对照（概念层）

维度	OpenAI	Anthropic	Gemini
工具调用	tools / tool_calls	tools / tool_use	function declarations
结构化	JSON mode / response_format	tool + schema	response_schema
上下文	模型各异（128k+ 等）	200k 级（Claude）	1M 级（部分型号）
流式	tool call delta 需拼接	类似	类似
嵌入	独立 embeddings API	Voyage 等第三方常见	Google embedding

以官方文档为准——本课表格随版本变化，集成时查当前 doc。

Agent 选型建议

场景	倾向
多步 tool 编排、复杂 JSON	旗舰推理模型
高 QPS 简单检索问答	小模型 + 强 RAG
长文档一次塞入	超长上下文型号（仍要 RAG 降噪）
成本敏感批处理	embed 用小模型；生成用缓存 prompt

CodeRoadMap 站内助手：检索质量 > 模型智商；好 chunk + hybrid 搜索 + 中等模型，往往优于裸 GPT 猜链接。

适配层模式

AgentService
  ├── chat(messages, tools) → 统一 ToolCall / ToolResult 类型
  ├── embed(texts) → float[]
  └── provider: openai | anthropic | gemini

• 统一 重试、限流、日志（不含 prompt 全文进生产日志）
• secrets 走环境变量，与 ai-security 一致
• 评估切换 provider 时跑 同一套 RAG golden set

与工程 track 衔接

团队如何选模型、谁为 API 账单负责，见 ai-engineering-essentials。个人用 Cursor 时 provider 由产品封装；自建 Agent 需自己管 key 与 quota。

练习

• 画适配层接口： 输入输出各 3 个字段