1. 这个问题比选框架更重要为什么“先问一个问题”是智能体开发的分水岭我去年下半年开始密集落地智能体项目从内部知识助手、销售话术生成器到客户投诉自动归因系统前后跑了7个真实业务线。过程中把 Claude Agent SDK、LangGraph、LangChain、LlamaIndex 甚至自研状态机都轮着搭过三遍以上。不是为了炫技而是因为每个项目上线后两周内必遇到同一个卡点流程跑着跑着就“断”了——不是报错不是崩溃而是逻辑莫名其妙绕弯、决策反复横跳、用户追问一句就彻底失联。直到第三次重构一个保险理赔辅助Agent时我把所有代码删掉只留一张白纸逼自己写下第一行字“这个智能体必须在3秒内给出可执行动作还是必须在5轮对话后输出结构化结论”就是这个问题直接决定了后续所有技术选型。Claude Agent SDK 的强项是“单步强推理高置信度动作触发”它默认假设你面对的是一个需要快速响应、低容错、高确定性的任务场景比如客服工单自动分派、实时风控拦截、API调用链路兜底而 LangGraph 的设计哲学是“状态可追溯边执行边修正”它天然适配那种需要多轮协商、外部工具调用不可控、中间状态必须人工介入的长周期任务比如跨部门协同审批、复杂合同条款比对、带人工复核的财务报销流程。很多人一上来就对比“LangChain 和 LangGraph 哪个更火”“Claude Agent SDK 能不能替代 LangChain”这就像问“锤子和电钻哪个更好用”却不说明你要装的是 Ikea 椅子还是承重墙龙骨。真正决定成败的从来不是框架语法有多优雅而是你手里的业务问题到底属于“确定性动作执行”还是“不确定性状态演进”。前者要的是确定性出口后者要的是可观测入口。我见过太多团队花两个月用 LangGraph 搭了一个销售线索打标Agent结果发现销售每天只看一眼标签就扔进CRM根本不需要状态回溯——那套复杂的 checkpoint 机制、state snapshot、interrupt 逻辑全成了性能负担。反过来也有团队用 Claude Agent SDK 做供应链异常预警结果因为无法记录“第3次触发预警后采购员手动否决了建议”导致系统永远学不会规避误报最后硬生生加了一层数据库存 state反而把 SDK 的轻量优势全废了。所以标题里说的“选型先问一个问题”不是玄学是血泪经验凝练的操作口诀。它不涉及任何代码却能帮你省下至少60%的返工时间。这个问题的答案会像一把尺子立刻把你拉回业务本质你的智能体到底是“执行器”还是“协作者”执行器要快、准、稳协作者要清、可逆、可干预。接下来所有技术细节都只是围绕这个核心判断做工程实现。2. 执行器 vs 协作者两类智能体的本质差异与选型逻辑2.1 执行器型智能体以 Claude Agent SDK 为典型代表的“确定性出口”范式执行器型智能体的核心诉求是在明确约束下完成一次精准的动作交付。它的成功标准非常朴素输入X输出YY必须是可被下游系统直接消费的确定值如API参数、SQL语句、JSON Schema校验通过的数据且整个过程耗时可控通常2秒、失败率极低0.5%。这类场景常见于企业内部自动化流程比如客服系统收到“我的订单号123456物流停滞”Agent需在1.8秒内调用物流查询API解析返回JSON提取“last_update_time”和“status_code”生成结构化告警事件发往工单系统ERP系统检测到“采购申请单金额超50万”Agent需立即调用风控模型API传入供应商历史履约率、当前账期余额等字段返回“approved/rejected/escalate_to_finance”三选一结果并附带置信度分数监控平台报警“服务器CPU持续95%达5分钟”Agent需自动执行“查进程→杀异常PID→重启服务→发钉钉通知”四步原子操作每步失败即终止并上报错误码。Claude Agent SDK 正是为这类场景深度优化的。它底层强制要求你定义Tool Schema严格遵循OpenAPI 3.0规范每个工具必须声明输入参数类型、必填项、枚举值范围、输出格式约束。SDK 在运行时会做三重校验① LLM生成的tool_call参数是否符合schema类型、长度、枚举② 实际调用返回是否匹配output_schema避免LLM幻觉伪造JSON③ 整个action chain是否在timeout阈值内完成默认1.5秒可设为200ms级。这种“契约式执行”带来的好处是你根本不用写retry逻辑、不用管state持久化、不用设计中断恢复——因为系统默认不允许“半途而废”。提示Claude Agent SDK 的tool_call不是简单函数调用而是带语义校验的协议交互。比如你定义一个search_knowledge_base(query: str, category: Literal[policy, product, compliance])工具LLM若生成category: policies拼写错误或category: 123类型错误SDK会在调用前直接抛出ValidationException而不是把错误参数传给后端——这省去了90%的边界case处理代码。2.2 协作者型智能体以 LangGraph 为典型代表的“可观测入口”范式协作者型智能体的核心诉求是在开放约束下维持一段可理解、可干预、可回溯的协作过程。它的成功标准不是单次输出正确而是整个协作流的透明度和可控性管理者能否看清“为什么Agent选择了方案A而非B”业务人员能否在第4步插入人工审核当第三方API超时系统能否自动降级到备选路径并记录决策日志这类场景常见于需要人机混合决策的业务比如法务部审核一份NDA协议Agent需先提取甲方乙方主体信息再比对历史模板库找出差异点接着调用合规检查工具扫描风险条款最后生成修订建议——但法务专员可能在“比对模板”后要求“先看甲方历史违约记录”或在“生成建议”前手动修改某条条款医疗问诊预筛患者描述症状后Agent需逐步追问“疼痛持续时间”“是否伴随发热”“既往病史”每轮追问都依赖上一轮回答且医生可在任意节点介入覆盖LLM生成的问题或直接跳转到特定检查项跨境电商选品Agent需并行调研目标市场政策、竞品定价、物流时效、本地化成本每个维度数据源不稳定海关API常超时、爬虫被封需动态调整采集顺序并允许运营人员在“政策分析完成”后手动输入最新法规解读。LangGraph 的设计完全围绕“状态可观测”展开。它强制你定义State SchemaPydantic BaseModel所有节点Node的输入输出都必须是该Schema的子集。每个节点执行后state会被序列化存入checkpoint支持SQLite/PostgreSQL/Redis你可以随时调用graph.get_state(config)查看当前完整状态树包括所有中间变量、工具调用历史、LLM原始prompt。更关键的是LangGraph原生支持Human-in-the-loop只需在任意节点后加.interrupt()系统就会暂停并暴露当前state前端调用graph.invoke({user_input: 按B方案执行}, config)即可继续——整个过程无需重启、不丢失上下文、不破坏state一致性。注意LangGraph 的“图”不是流程图而是状态迁移图。每个节点本质是state - state的纯函数没有隐式状态传递。这意味着你无法在节点A里“偷偷改”节点B要用的变量——所有变更必须显式写入state。这种设计看似繁琐实则杜绝了90%的幽灵bug比如某个节点意外覆盖了全局session_id导致后续所有日志串号。2.3 关键分界点三个实操判据帮你一秒定位类型光看理论容易迷糊我在实际项目中总结出三个硬性判据只要满足任一条件就属于协作者型必须选LangGraph类框架全部不满足则优先考虑Claude Agent SDK是否存在“非原子性决策点”如果你的业务流程中存在某个环节必须由人判断“是否继续”且该判断依赖LLM未生成的中间结果例如“请法务确认条款3是否需保留”这就是非原子性决策点。Claude Agent SDK 无法优雅处理——它要么执行完所有步骤要么失败退出而LangGraph可通过.interrupt()在任意节点后暂停等待人工输入后再resume。工具调用失败是否允许降级或跳过如果某个工具如“查海关编码”超时业务上允许跳过此步直接进入下一步如“按默认税率计算”则属于协作者型。Claude Agent SDK 默认fail-fast需额外写fallback逻辑LangGraph则天然支持在node内捕获异常写if tool_failed: state.update({tax_rate: 0.13})即可无缝降级。是否需要追溯“为什么这样决策”如果审计要求你提供“Agent为何将此工单分派给上海组而非北京组”的完整证据链包括当时获取的客户地域信息、上海组当前负载、历史分派准确率就必须选LangGraph。它的checkpoint机制自动记录每次state变更、LLM prompt、tool call参数及返回导出JSON即可生成审计报告Claude Agent SDK 仅保留最终action log中间推理链不可追溯。这三个判据我在给客户做技术尽调时用一张A4纸就能讲清楚。它不涉及任何代码却能避免团队在错误的技术路线上狂奔三个月。3. 实操拆解同一需求两种框架的实现差异与代价我们以一个真实案例切入银行信用卡逾期催收话术生成Agent。业务需求是输入客户逾期天数、历史还款次数、当前账户余额输出一段符合监管要求、语气得体、带个性化激励的话术如“王女士您已逾期12天近3个月有2次按时还款记录本次可享利息减免50%点击链接立即处理”。3.1 Claude Agent SDK 实现聚焦“出口确定性”第一步定义Tool Schema严格约束输出from typing import Literal from pydantic import BaseModel, Field class GenerateScriptInput(BaseModel): overdue_days: int Field(..., ge1, le90, description逾期天数1-90) repayment_count: int Field(..., ge0, le100, description近6个月还款次数) balance: float Field(..., ge0.01, le1000000.0, description当前欠款余额) class GenerateScriptOutput(BaseModel): script: str Field(..., min_length20, max_length300, description生成的话术必须包含客户称谓、逾期天数、激励措施、行动指引) compliance_score: float Field(..., ge0.0, le1.0, description合规性评分0.95以上才允许发送) risk_level: Literal[low, medium, high] Field(..., description风险等级依据balance和overdue_days计算) # 注册工具SDK自动校验输入输出 tool(schemaGenerateScriptInput, output_schemaGenerateScriptOutput) def generate_script(input: GenerateScriptInput) - GenerateScriptOutput: # 实际调用微调后的Claude模型prompt含严格格式指令 # 输出必须是valid JSON否则SDK抛异常 return GenerateScriptOutput( scriptf王女士您已逾期{input.overdue_days}天..., compliance_score0.98, risk_levelmedium )第二步配置Agent极简无状态管理from claude_agent import Agent agent Agent( modelclaude-3-haiku-20240307, tools[generate_script], timeout_ms1200, # 严格1.2秒超时 max_retries0, # 不重试失败即告警 ) # 调用输入原始数据输出确定结果 result agent.invoke({ overdue_days: 12, repayment_count: 2, balance: 8500.0 }) # result 是 GenerateScriptOutput 实例可直接序列化发短信代价与收益✅ 优势代码量仅50行部署后P99延迟1.1秒合规评分0.95时自动拒绝输出杜绝违规话术❌ 代价若监管突然新增“必须提及客户最近一笔还款日期”需重新训练模型更新schema全量回归测试无法在生成话术后让催收主管手动微调“激励力度”再发送。3.2 LangGraph 实现聚焦“入口可观测性”第一步定义State容纳所有中间态from typing import Optional, List, Dict, Any from pydantic import BaseModel class CallState(BaseModel): customer_name: str overdue_days: int repayment_count: int balance: float # 中间变量全部显式声明 last_repayment_date: Optional[str] None regulatory_rules: List[Dict[str, Any]] [] draft_script: Optional[str] None compliance_check_result: Optional[Dict[str, Any]] None human_approval: Optional[bool] None # 人工干预标记第二步构建图节点职责清晰状态可追踪from langgraph.graph import StateGraph, END from langgraph.checkpoint.sqlite import SqliteSaver def fetch_last_repayment(state: CallState): # 调用CRM API获取最近还款日期 date call_crm_api(state.customer_name) return {last_repayment_date: date} def load_regulations(state: CallState): # 加载最新监管规则可热更新 rules get_latest_regulations() return {regulatory_rules: rules} def generate_draft(state: CallState): # LLM生成初稿prompt含规则引用 script llm.invoke(f根据规则{state.regulatory_rules}生成话术...) return {draft_script: script} def check_compliance(state: CallState): # 调用合规引擎校验 result compliance_engine.validate(state.draft_script) return {compliance_check_result: result} def human_review(state: CallState): # 等待人工输入前端调用invoke时传入 if not state.human_approval: return {human_approval: None} # 触发interrupt return {human_approval: state.human_approval} # 构建图 builder StateGraph(CallState) builder.add_node(fetch_repayment, fetch_last_repayment) builder.add_node(load_rules, load_regulations) builder.add_node(generate, generate_draft) builder.add_node(check, check_compliance) builder.add_node(review, human_review) builder.set_entry_point(fetch_repayment) builder.add_edge(fetch_repayment, load_rules) builder.add_edge(load_rules, generate) builder.add_edge(generate, check) builder.add_conditional_edges( check, lambda state: approved if state.compliance_check_result[score] 0.95 else review, {approved: END, review: review} ) builder.add_edge(review, END) graph builder.compile(checkpointerSqliteSaver.from_conn_string(:memory:))第三步调用支持全流程干预# 初始调用 config {configurable: {thread_id: call_12345}} result graph.invoke({ customer_name: 王女士, overdue_days: 12, repayment_count: 2, balance: 8500.0 }, config) # 若合规分0.95系统自动暂停在review节点 # 前端可调用 graph.invoke({ human_approval: True, # 主管点击“通过” draft_script: 王女士您已逾期12天...微调后版本 }, config) # 查看完整决策链 state graph.get_state(config) print(state.values) # 输出所有中间变量、时间戳、节点执行日志代价与收益✅ 优势监管规则更新只需改load_regulations节点无需重训模型主管可在任意节点介入审计时graph.get_state()一键导出全链路证据❌ 代价代码量300行首次部署需配置SQLiteP99延迟2.8秒因多步IO运维复杂度显著提升。3.3 关键对比表选型决策的量化依据维度Claude Agent SDKLangGraph我的实际选择建议首屏响应时间P99 ≤ 1.3秒P99 ≤ 2.8秒单线程/ ≤ 1.9秒Redis checkpointer若业务SLA要求1.5秒优先SDK若可接受≤3秒LangGraph更灵活状态持久化成本无内置机制需自行集成DB内置checkpointSQLite免费PostgreSQL生产推荐小团队用SQLite够用中大型系统必须评估PostgreSQL连接池压力人工干预支持需hack在tool内加if manual_mode: return wait_for_human()原生.interrupt()invoke(..., config)凡涉及“人审”“人补”“人覆”LangGraph省90%胶水代码规则热更新能力工具schema变更需重启服务load_rules节点可独立更新不影响其他节点监管频繁变动的金融/医疗场景LangGraph是刚需调试成本日志只有input/outputLLM内部推理不可见get_state()返回完整state树含每个节点的prompt和tool call详情新人上手调试LangGraph学习曲线陡但长期省力SDK初期快但后期难排查扩展多智能体需手动编排多个Agent实例状态同步复杂原生支持send()跨图通信State可继承复用做“催收Agent风控Agent法务Agent”协同LangGraph架构更清晰这张表是我和架构师喝着咖啡拍板的依据。它不谈虚的概念只列工程师真正在意的数字和痛点。4. 避坑指南那些没人告诉你的“选型后遗症”4.1 Claude Agent SDK 的隐藏陷阱当“确定性”变成“僵化性”我最早用SDK做的一个HR面试邀约Agent跑得飞快P99 0.8秒。但上线两周后招聘BP提了个需求“如果候选人上周刚拒过我们offer话术末尾要加‘理解您上次的选择本次岗位有新升级’”。这看起来只是prompt微调但实际踩了三个深坑Schema耦合陷阱原tool output schema里script字段是str现在要加条件分支LLM可能生成“理解您上次的选择...”或“感谢您关注...”但SDK的schema校验只认固定格式。我被迫把script改成dict增加base_script和conditional_suffix两个字段结果所有下游系统短信网关、邮件模板引擎都要改解析逻辑——一个文案需求引发5个系统联调。Fallback失效陷阱SDK的max_retries0本是优点但当LLM因温度值设置过高为增加文案多样性偶尔生成不符合schema的JSON时整个请求直接500。监控里看到大量ValidationError却无法区分是LLM bug还是输入脏数据。最后只能加一层前置清洗对所有输入字段做正则校验把overdue_daystwelve这种字符串提前拦住——这违背了SDK“专注执行”的初衷。灰度发布陷阱想用A/B test验证新话术效果SDK不支持按thread_id路由到不同model版本。我不得不在外层加Nginx分流把/v1/generate?expnew_script的请求导向新服务但这样就失去了SDK的统一超时控制两套服务的P99指标完全不可比。实操心得Claude Agent SDK 适合“功能稳定、规则固化、下游系统不愿改”的场景。一旦业务进入快速迭代期它的强约束会迅速变成枷锁。我的经验是上线前务必问自己“未来6个月这个智能体的输入输出schema有无可能变更”如果有立刻选LangGraph。4.2 LangGraph 的认知负荷当“可观测”变成“过度设计”我们曾用LangGraph搭一个简单的“会议纪要生成Agent”结果陷入“状态焦虑”初始state只定义了transcript和summary第二版加了action_items待办事项第三版加了decision_points决策点第四版加了sentiment_score情绪分最后state膨胀到12个字段每个节点都要return {field_x: value}新人看代码像读天书。更糟的是为追求“完美可观测”我们在每个节点后加了logger.info(fNode X executed, state: {state})结果日志量暴增10倍ELK集群差点被打爆。运维同事找上门“你们的Agent每秒产生2000行日志比整个订单系统的日志还多”LangGraph真正的敌人不是技术是工程师的完美主义。它的state schema不是越细越好而是要遵循“最小必要原则”只存影响下一步决策或必须审计的字段。比如sentiment_score对会议纪要生成毫无价值删掉decision_points若只是供人看不参与后续逻辑就该移到前端渲染层而非塞进state。实操心得LangGraph的state不是数据库而是决策上下文快照。我现在的做法是每个节点只更新1-2个字段用state.update()而非全量覆盖所有只读信息如原始录音文本存OSSstate里只放URLaudit字段统一加_audit_前缀方便日志过滤。这套约定让团队新人三天就能上手维护。4.3 混合架构的实战平衡术不选边而是分层最成熟的方案往往不是二选一而是分层组合。我在一个保险核保Agent中实践了“SDKLangGraph”混合架构效果极佳外层用LangGraph做流程编排负责接收用户上传的体检报告PDF、调用OCR识别、触发风控规则引擎、决定是否需要人工复核——这一层需要状态追踪、人工中断、规则热更新内层用Claude Agent SDK做原子工具OCR识别、规则引擎调用、话术生成全部封装成SDK工具。LangGraph节点只负责传参调用不关心内部实现状态桥接LangGraph的state中ocr_result字段存SDK返回的结构化JSONrule_engine_output字段存SDK返回的风险等级所有SDK工具的timeout、retry策略由SDK自身管理LangGraph只处理“调用成功/失败”两种状态。这样既享受了LangGraph的流程灵活性又保留了SDK的执行确定性。关键在于清晰划分边界LangGraph管“做什么”和“何时做”SDK管“怎么做”和“做得多准”。实操心得混合架构不是炫技而是成本权衡。我的分层原则是凡涉及外部系统交互、人工干预、长周期状态交给LangGraph凡涉及高并发、低延迟、强一致性输出交给Claude Agent SDK。两者通过明确定义的DTOData Transfer Object通信绝不共享内存或状态。5. 选型之后如何让智能体真正跑起来5.1 监控不是锦上添花而是生存必需无论选哪个框架上线后第一件事不是优化prompt而是埋监控。我给自己定的铁律没有监控的智能体等于没上线。具体监控项必须覆盖三层基础设施层CPU/内存使用率LangGraph的checkpointer易吃内存、Redis连接数LangGraph用Redis时、API调用延迟Claude SDK的timeout命中率框架层LangGraph的checkpoint_sizestate序列化后大小超1MB要告警、node_execution_time各节点P95耗时Claude SDK的validation_error_rateschema校验失败率0.1%需立即排查业务层话术生成Agent的compliance_score 0.95占比、催收Agent的human_interrupt_rate人工介入率15%说明流程设计有问题、会议纪要Agent的summary_length_deviation摘要字数偏离均值±20%即告警。我们曾因忽略checkpoint_size监控导致LangGraph在处理大PDF时state膨胀到8MBSQLite写入超时整个图卡死。后来加了state_size_validator节点超过2MB自动压缩文本并告警问题根除。5.2 Prompt不是魔法而是接口契约很多团队把prompt当黑盒调优这是最大误区。Prompt本质是LLM与业务逻辑之间的API契约。Claude Agent SDK要求你把prompt约束写进tool schemaLangGraph要求你在节点函数里显式声明prompt模板——这恰恰是好事。我的做法是为每个tool/node建立prompt_contract.md文档包含输入变量说明如{customer_name}必须是中文姓名不含空格输出格式强制要求如“必须以‘尊敬的{customer_name}’开头结尾带‘点击链接’”错误示例如生成“亲爱的王先生”算违规因客户性别未知合规红线如禁止出现“保证”“绝对”等词。这份文档和代码一起提交GitPR评审时必须检查prompt契约是否与业务需求一致。它让prompt从玄学变成可测试的接口。5.3 迭代不是推倒重来而是渐进增强最后分享一个血泪教训别迷信“下一代框架”。我们曾计划把运行良好的Claude Agent SDK项目迁到LangGraph理由是“LangGraph更先进”。结果花了6周重写上线后P99延迟从1.1秒升到2.4秒业务方投诉“比原来慢一倍”。最后发现原SDK的轻量级设计恰恰匹配了业务——催收话术生成本就不需要状态回溯强行加LangGraph只是增加复杂度。真正的迭代应该是基于监控数据的渐进增强当validation_error_rate持续升高说明输入数据质量下降该加数据清洗层当human_interrupt_rate突增说明LLM输出与业务预期偏差变大该重训模型而非换框架当checkpoint_size缓慢增长说明state设计冗余该做字段精简而非升级checkpointer。智能体开发最终拼的不是框架多酷而是你对业务问题的理解深度以及把这种理解精准翻译成技术约束的能力。那个“先问的问题”就是翻译的起点。