《实用笔记》：为何没人谈论LangChain、LangGraph和AutoAgent
《实用笔记》操作指南：为何没人谈论LangChain、LangGraph和AutoAgent——适用于采用该架构的团队的合约、校验机制及可直接插入的代码模块。
来源: Why No One Talks About LangChain, LangGraph Or AutoAgent
本指南将逐步构建从原始材料到可运行系统的完整流程，内容涉及《为何没人谈论LangChain、LangGraph或AutoAgent》这一主题。重点在于可操作的步骤、明确的检查点，以及可直接放入代码库的代码，无需猜测其用途。 在修改代码之前，应先明确输入参数、各步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行相应步骤，而无需推测隐藏状态。 需同时记录正常流程与异常恢复流程。重试机制、人工审核环节以及错误处理都是产品不可或缺的部分，而非后续需要补充的功能。
┌────────────────────────────────────────┐
│ POST-FRAMEWORK PARADIGM │
└──────────────────┬─────────────────────┘
│
┌─────────────┴─────────────┐
▼ ▼
┌──────────────┐ ┌──────────────┐
│ PIPELINE │ │ HARNESS │
│ MODE │ │ MODE │
├──────────────┤ ├──────────────┤
│ • Bounded │ │ • Unbounded │
│ • Code-Run │ │ • Model-Run │
│ • Compute │ │ • Context │
│ Bound │ │ Bound │
└──────────────┘ └──────────────┘
目录
在处理目录结构时，首先写下相关约定：所需的输入参数、成功标志，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应指向单一的责任模块，而非复杂的流程链。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。
1. 无人负责的工作分类
在处理“1. 没人做的任务分类”时，首先写下相关契约：所需的输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 将此阶段视为输入与验证后输出之间的契约。为相关成果命名，明确成功判定标准，杜绝无声的半完成状态。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。
Is the work decomposable into a finite set of
named states with deterministic transitions?
[ YES ] ──► PIPELINE MODE
• Invoice Extraction
• Document Classification
• Approval Routing
• KYC Verification
• Data Enrichment
[ NO ] ──► HARNESS MODE
• Coding Agents
• Research Agents
• Ephemeral Tool/Shell Use
• Legacy Code Migrations
• Open-Ended Investigation
2. 流水线模式：当任务可分解时
在处理2.管道模式：任务可分解时，首先需明确相关规范：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。 在耗时较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次收取相同的LLM调用费用。 在处理2.管道模式：任务可分解时，首先需明确相关规范：所需输入、成功信号以及部分失败时的处理方式。这份清单能确保后续的代码修改保持一致性。 需同时记录正常流程与故障恢复流程。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。
[Input Data payload]
│
▼
┌──────────────┐
│ State 1 │ ──► [Structured LLM Call]
└──────┬───────┘ │
│ ▼
│ ┌──────────────┐
│ │ Validation │ ──► [Fail] ──► [Error State]
│ └──────┬───────┘
│ │ [Pass]
▼ ▼
┌──────────────┐
│ State 2 │ ──► [Structured LLM Call]
└──────┬───────┘ │
│ ▼
│ ┌──────────────┐
│ │ Validation │ ──► [Fail] ──► [Error State]
│ └──────┬───────┘
│ │ [Pass]
▼ ▼
[Final Success Output]
3. Harness模式：当任务无法拆分时
- Harness模式：当任务无法拆分时，若能将其视为可度量的对象则会更有效。在扩大范围之前，先记录一份优秀的测试用例、一个故障案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤出现故障时，故障应指向单一的责任模块，而非复杂的流程链。 使用结构明确的工具，并为各种操作添加清晰的副作用标签。主机需要在自动批准之前知道哪些调用会改变系统状态。
┌──────────────────────────────────────────────┐
│ HARNESS LAYER │
│ Executes container limits & system safety │
├──────────────────────────────────────────────┤
│ [Safety Hooks] [Budgets] [Time Constraints] │
├──────────────────────────────────────────────┤
│ ┌────────────────────────────────────────┐ │
│ │ MODEL OWNS LOOP │ │
│ │ Plan ──► Execute ──► Observe ──► Plan │ │
│ │ │ │
│ │ Native capabilities: │ │
│ │ • File / Sandboxed Shell access │ │
│ │ • Context-isolated subagent spawning │ │
│ │ • Skill discovery & loading │ │
│ └────────────────────────────────────────┘ │
└──────────────────────┬───────────────────────┘
▼
Result, Partial State, or Escalation
Harness模式的故障类型
将“束集模式”的故障模式视为可测量的表面来处理效果最佳。在扩大范围之前，先记录一份完美的测试用例、一个故障实例以及回滚说明。 将此阶段视为输入与已验证输出之间的契约。为相关成果命名，明确成功标准，绝不允许默许不完整的处理结果。 使用具有严格结构定义且带有明确副作用标注的工具。主机需要在自动批准之前知道哪些调用会改变状态。
4. 两种模式的数学本质
- 将这两种模式视为可测量的表面来处理时，其数学特性才能得到最佳体现。在扩大范围之前，需记录一份理想状态下的操作日志、一个故障案例以及回滚说明。在功能结果旁还需记录执行时间以及令牌或查询成本。提前了解这些成本信息，可避免在系统从演示环境过渡到共享环境时出现意外费用。同时要保持图表状态的简洁性与类型一致性，否则嵌套的数据结构会掩盖具体是哪个节点修改了哪一字段，且在出现中断后还会导致流程无法继续。
- 将这两种模式视为可测量的表面来处理时，其数学特性才能得到最佳体现。在扩大范围之前，需记录一份理想状态下的操作日志、一个故障案例以及回滚说明。应同时文档化正常流程与恢复流程，重试机制、人工审核环节以及死信处理都属于产品本身的组成部分，而非后续需要补充的功能。
管道模式：推理时间扩展定律
在流水线模式下：根据推理时间缩放定律，在修改代码之前需明确输入参数、各步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行相应步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型且易于测试的单元。当某个步骤出现故障时，故障原因应能明确指向单一责任主体，而非整个复杂的流水线。对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务功能的完整性。
利用模式：上下文退化曲线
对于Harness模式：在修改代码之前，需先确定上下文退化曲线、各步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行相应步骤，而无需猜测隐藏状态。 应将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功判定标准，并拒绝默许的半完成状态。 在网关处进行身份验证，在数据层面重新授权。仅凭承载令牌并不足以界定租户边界。
P(Success)
▲
1.0├───────────┐
│ │
│ └───┐
0.5│ │
│ └─────────────► Context Size (Tokens)
0└───────────┬───┬─────────────
50k 100k
5. 2026年Harness的架构（实现蓝图）
对于5. 2026年框架的架构（实施蓝图），在修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况可避免在从演示环境过渡到共享环境时出现意外账单。 在网关处进行身份验证，在数据层面重新授权。仅凭承载令牌并不足以界定租户边界。 对于5. 2026年框架的架构（实施蓝图），在修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及死信处理都属于专业方案的一部分。
先处理管道相关问题，之后再做优化。import logging
import os
from typing import Dict, Any, List
from pydantic import BaseModel, Field
# 2026 SDK abstractions (analogous across major provider frameworks)
from modern_agent_sdk import Agent, Skill, SubAgent
from modern_agent_sdk.hooks import PreToolUse, PostToolUse
from modern_agent_sdk.budgets import TokenBudget, StepBudget, WallTimeBudgetlogger = logging.getLogger("EnterpriseHarness")# 1. Skills are dynamically loaded from disk, not declared inline.
# Each skill is an isolated directory containing metadata (SKILL.md),
# runtime scripts, and specialized sandbox requirements.
SKILLS_DIR = "./skills"
all_skills = Skill.load_directory(SKILLS_DIR)# 2. Safety Hooks: Gateway controls running in the host environment.
# These run on the host *before* any action is committed inside the sandbox.
def pre_tool_execution_hook(context: Dict[str, Any], tool_call: BaseModel) -> PreToolUse:
"""
Validates security boundaries and consumption limits before the model executes a tool.
"""
# Hard safety boundary: Prevent destructive shell operations
if tool_call.name == "execute_shell":
command = tool_call.args.get("command", "")
if any(bad_cmd in command for bad_cmd in ["rm -rf", "chmod", "wget"]):
logger.error(f"Execution blocked: Blocked command detected: '{command}'")
return PreToolUse.deny("Destructive shell operations are prohibited in this sandbox.")
# Budget check: Halt network tools if API budget is running low
if tool_call.name == "network_request":
if context["budget"].remaining_tokens < 15_000:
return PreToolUse.deny("Insufficient remaining token budget to execute external network calls.")
logger.info(f"Approved tool call: {tool_call.name}")
return PreToolUse.allow()def post_tool_execution_hook(context: Dict[str, Any], tool_call: BaseModel, result: Any) -> PostToolUse:
"""
Evaluates tool execution outcomes to detect systemic failure loops.
"""
# Detect repeating error patterns to prevent infinite execution loops
if result.is_error and context["consecutive_failures"] >= 3:
logger.warning("System detected a repeating error loop. Forcing escalation.")
return PostToolUse.escalate("Agent is stuck in an execution failure loop.")
return PostToolUse.continue_loop()# 3. Context Isolation via Subagents
# To prevent context poisoning, the parent agent never sees the child's
# scratchpad or intermediate execution steps—only the final verified output.
def spawn_research_subagent(target_query: str) -> str:
"""
Spawns a specialized subagent in a separate context window to perform a task,
keeping the parent's working context completely clean.
"""
logger.info(f"Spawning isolated subagent for query: '{target_query}'")
subagent = SubAgent(
model="claude-sonnet-4-5",
skills=all_skills.filter_by_tag("research"),
budgets=[
TokenBudget(max_input_tokens=40_000, max_output_tokens=8_000),
StepBudget(max_steps=12)
]
)
# Run task and return only the clean, compiled summary
output = subagent.execute(task=target_query)
return output.summary# 4. Assembling the Harness Container
# The harness manages the execution sandbox, enforces constraints, and handles state.
agent_harness = Agent(
model="claude-opus-4-7",
skills=all_skills,
subagent_factories={
"researcher": spawn_research_subagent
},
hooks={
"pre_tool_use": pre_tool_execution_hook,
"post_tool_use": post_tool_execution_hook
},
budgets=[
TokenBudget(max_total_tokens=600_000),
StepBudget(max_steps=100),
WallTimeBudget(max_seconds=1800) # 30-minute hard cap
],
persistence_store="./.agent_state_db", # State is persisted per step to survive restarts
escalation_handler=lambda issue: open_human_review_ticket(issue)
)# 5. Execution
if __name__ == "__main__":
task_input = "Migrate this legacy Django 4.2 codebase to FastAPI with 100% endpoint parity."
try:
# The agent loop is entirely internal to the model.
# There is no manual 'while True' in our orchestration code.
result = agent_harness.run(task=task_input)
logger.info(f"Task completed. Result: {result.status}")
except Exception as e:
logger.critical(f"Harness terminated execution: {e}")
与旧版2024框架的主要区别：
在分析与旧版2024框架的主要区别时，首先需明确契约内容：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应指向单一责任点，而非复杂的流程链。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的LLM接口。
6. 架构冲突：用错误的方案解决错误的问题
在完成“6. 架构冲突：将错误的解决方案用于错误的问题”这一章节时，首先需明确合同条款：所需的输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 将这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，定义成功判定标准，并杜绝无声的半完成状态。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。
┌─────────────────────────────────────────────────────┐
│ ARCHITECTURAL MATCH │
├──────────────────────────┬──────────────────────────┤
│ PIPELINE WORKLOAD │ HARNESS WORKLOAD │
├──────────────────────────┼──────────────────────────┤
│ • Goal: Exact Extraction │ • Goal: Code Refactoring,│
│ & Routing │ Agent Tasks, Migration │
│ │ │
│ • WRONG: Harness │ • WRONG: Pipeline │
│ (High latency, costly, │ (FSM State explosion, │
│ non-deterministic) │ inflexible schema) │
│ │ │
│ • RIGHT: Pipeline FSM │ • RIGHT: Sandbox Harness │
│ (Predictable transitions)│ (Dynamic loop execution)│
└──────────────────────────┴──────────────────────────┘
案例1：管道中的工具集成错误（过度设计）
在处理案例1“管道中的工具框架错误（过度设计）”时，首先需明确接口规范：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。 需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试过程将会浪费大量时间。 在处理案例1“管道中的工具框架错误（过度设计）”时，首先需明确接口规范：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 需同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。
案例2：流水线在集成环境中的错误（设计不足）
将案例2：流水线在集成环境中的错误（设计不足）视为可测量的对象来处理效果最佳。在扩大范围之前，先记录一份理想的流程文档、一个故障案例以及回滚说明。 优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤出现故障时，故障应指向单一的责任主体，而非复杂的流水线结构。 使用具有明确架构规范和清晰副作用标签的工具。主机需要在自动批准之前知道哪些调用会改变状态。
如何选择正确的架构
将“如何选择正确的架构”视为一个可度量的指标来处理效果最佳。在扩大范围之前，先记录一份优秀的案例、一个失败案例以及回滚说明。 把这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许默默地只完成部分工作。 保持图结构的状态简洁且具有类型定义。嵌套的数据块会掩盖是哪个节点修改了哪个字段，还会在中断后导致无法继续处理。
7. 技能层：2026年的开放标准
- 技能层：将2026年的开放标准视为可度量的对象时，其效果最佳。在扩大范围之前，需记录一份理想状态下的操作日志、一个故障案例以及回滚说明。在功能结果旁还需记录执行时间以及令牌或查询成本。提前明确成本情况，可避免在系统从演示环境过渡到共享环境时出现意外账单。同时要保持图表状态的简洁性与类型化，嵌套的数据结构会掩盖具体是哪个节点修改了哪个字段，且在出现中断后会导致状态无法恢复。
- 技能层：将2026年的开放标准视为可度量的对象时，其效果最佳。在扩大范围之前，需记录一份理想状态下的操作日志、一个故障案例以及回滚说明。应同时记录正常流程与异常恢复流程，重试机制、人工审核环节以及死信处理都属于产品本身的组成部分，而非后续需要补充的功能。
skills/
├── document_parser/
│ ├── SKILL.md <-- Human/Model readable metadata & capabilities
│ ├── run.py <-- The execution logic running inside the sandbox
│ └── reference_rules.pdf <-- Domain-specific constraints and edge-cases
8. 结论：新的工程岗位
8. 结论：对于新的工程任务，在修改代码之前需明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。对于涉及资金支出或修改生产数据的操作，必须经过人工审批——编译时的连接方式并不能等同于业务功能的完整性。
操作检查清单
若将操作检查清单视为可衡量的指标，其作用会更为显著。在扩大范围之前，应先记录一份标准操作流程、一个故障案例以及相应的回滚说明。
将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一处，这样操作人员无需查看整个系统结构即可进行审计。
保持系统状态结构的扁平化与类型化。嵌套的数据结构会掩盖具体是哪个节点修改了哪一字段，还会导致在任务中断后无法继续执行。
只要预算允许，就应在持续集成过程中使用测试用例而非真实的付费 API 来执行关键路径的冒烟测试。
需同时记录正常流程与故障恢复流程。重试机制、人工审核环节以及错误处理措施都是产品不可或缺的部分，而非后续需要补充的功能。
保持系统状态结构的扁平化与类型化。嵌套的数据结构会掩盖具体是哪个节点修改了哪一字段，还会导致在任务中断后无法继续执行。
在推广该技术栈之前，应先冻结版本，为关键流程记录标准输出日志，并明确回滚步骤。共享环境需要设置速率限制、租户验证机制，以及负责密钥轮换的明确责任人。与其展示花哨的一次性演示，不如注重扎实的可靠性。
关于9f921d978495的批注：请将提供商密钥移出代码仓库，设定单会话令牌上限，并将日志存储在评估用示例文件旁，以便后续模型更换时仍能保持数据可比性。