LLM API 与智能体框架

从一次模型调用开始，只有在任务确实需要工具、状态、恢复或多角色协作时才增加 Agent 框架。框架不能替代清晰的输入输出合同、权限边界、评估集和失败处理。

OpenAI、Anthropic、Gemini 与 OpenRouter

模型 API 的共同结构是：认证、输入消息或内容、模型选择、输出解析、工具调用、流式响应和错误处理。OpenAI 新建 Agent 应用优先从 Responses API 与官方 Agents SDK 文档理解当前接口；Anthropic、Gemini 使用各自官方 SDK。OpenRouter 提供统一入口，但模型能力、参数和数据政策仍由具体路由决定。

不要把 API Key 写进前端、Notebook 输出或 Git。设置超时、有限重试和请求 ID；只对网络错误、限流等可恢复失败重试，避免对有外部副作用的工具重复执行。模型 ID、输入模板、温度等参数和 Provider 响应元数据进入实验记录，但“最新推荐模型”始终查询官方页面，不在项目中靠猜测更新。

LangChain

LangChain 提供模型、Prompt、Retriever、Tool 和结构化输出等组件。它适合大量集成的应用，但应保持核心链路可读：每一步输入输出有类型，外部调用可替换，业务逻辑不藏在长串隐式组合中。

LangGraph

LangGraph 用图、状态和 Checkpoint 组织长运行工作流。节点完成一个明确转换，边表达路由；循环必须有终止条件，恢复要区分已经完成的外部副作用。它适合需要暂停、人工介入和持久状态的 Agent，不是单次工具调用的必需品。

OpenAI Agents SDK

OpenAI Agents SDK 面向带工具、上下文、Agent 交接、流式输出和完整 Trace 的应用。先用单 Agent 和少量工具验证行为，再增加 handoff。工具 Schema 要窄，返回值可解释，敏感或不可逆动作在应用层增加授权与确认。

AutoGen

AutoGen 用事件和消息构建 Agent 与多 Agent 应用。多 Agent 只有在角色拥有不同上下文、工具或并行任务时才有价值；仅让多个模型轮流讨论会增加成本和不确定性。设置最大轮数、终止条件和可观察日志。

CrewAI

CrewAI 以 Agent、Task、Crew/Flow 表达角色化流程。任务的期望输出和依赖要具体，工具权限按角色最小化。对于固定确定性流程，普通函数或工作流引擎往往更简单。

LlamaIndex

LlamaIndex 强调数据连接、索引、检索、Workflow 和 Agent。RAG 首先验证切分、元数据、召回和引用，再优化生成；不要把回答流畅度误当成检索正确性。

PydanticAI

PydanticAI 使用 Python 类型、依赖注入和结构化结果组织 Agent。它适合重视类型合同和可测试依赖的 Python 项目。外部模型输出仍可能验证失败，应用需要明确重试、降级或返回错误。

smolagents

smolagents 是 Hugging Face 的轻量 Agent 库，适合教学、原型和与 Hub 模型生态组合。Code Agent 会产生可执行代码，必须放在合适沙箱中，并限制网络、文件和凭据访问。

从模型调用到 Agent

结构化模型调用
→ 一项只读工具
→ 多工具路由
→ 显式状态与恢复
→ 人工确认的外部动作
→ 确有必要时再做多 Agent

每增加一层，都要补充对应评估：输出 Schema、工具选择、参数正确性、恢复幂等性、终止条件、成本和延迟。Prompt injection 内容视为不可信数据，不能让网页或文档自行扩大工具权限。

参考：OpenAI API 文档、OpenAI Agents SDK、Anthropic API、Gemini API、LangChain/LangGraph、AutoGen、CrewAI、LlamaIndex、PydanticAI、smolagents。