← Agents From First Principles

动作边界

通过定义有限动作空间、校验结构与语义、将授权与执行分离、把失败视为运行时证据,把概率性的模型输出变成显式、可检视的动作提案。

上一章以责任分工作为结尾:

模型负责提出。运行时决定什么可以执行。环境提供关于发生了什么的观察。

本章认真对待第一个子句。模型提出一个动作究竟意味着什么?

假设模型发出句子 “Search the documentation for the latest PyTorch optimizer API”。人类读到它,立刻理解意图。运行时却完全无法据此行动,因为它需要六个答案,而该句子一个都不包含:是哪个动作、哪些参数、这些参数是否合式、它们的值是否有意义、这个动作在本次运行中是否被允许、以及它的执行前置条件当前是否成立。

只有当所有六个问题都有了答案,环境中的任何东西才应该改变。所以本章增加的机制是一道按顺序提问它们的边界:

    flowchart TD
    M[模型输出] --> P[解析表示]
    P --> S[校验 schema]
    S --> V[校验语义]
    V --> A[授权]
    A --> C[检查前置条件]
    C --> X[执行]
    X --> O[观察]

    P -.rejected.-> R[拒绝<br/>标记阶段]
    S -.rejected.-> R
    V -.rejected.-> R
    A -.rejected.-> R
    C -.rejected.-> R
    R --> O
  

注意虚线边。每个阶段都可以拒绝,而每一次拒绝最终都落在同一个地方——作为下一次决策可用的观察。这就是全部设计,它建立在一个想法之上:

模型输出可以提案一个动作,而无需拥有执行它的权限。

这个区分把工具使用从提示词技巧变成了一个软件接口。


1. 从失败开始

想象一个智能体有两个能力:search(query) 和 calculate(expression),以及一个用自然语言询问命令的朴素实现:

def decide(task: str) -> str:
    return llm(
        f"""
        Available tools:
        - search(query)
        - calculate(expression)

        Task:
        {task}

        Tell me which tool to call.
        """
    )

有时它正好产出我们期望的东西。但往往产出别的东西,而那些"别的东西"并非单一问题的变体:

模型输出 发生了什么
SearchWeb("PyTorch optimizer state") 发明了一个不存在的能力
calculate(expression="2 +") 真实动作,不可用的参数
I should probably search the docs first. 描述意图而非编码动作
{"tool": "search", "query": 17} 结构化了,但形状与类型都错

这些在四个不同的地方失败,需要四种不同的响应。提示词工程无法把它们折叠成一个类别,因为它们根本不是一类。运行时需要的是一个它能检查的显式契约。


2. 从语言转向有限动作空间

修复始于改变提问方式。不再问 你想做什么?,而是问:从这个集合中选择一个动作,并提供它要求的参数。

有了 {search, calculate, final} 这样的动作空间,提案就变成了一个数据结构:

{
  "action": "search",
  "arguments": {
    "query": "PyTorch optimizer state"
  }
}

JSON 在这里很方便,但 JSON 不是原则。原生函数调用对象、类型化 Python 对象、Protocol Buffer、JSON Schema 或语法约束的表示都可以。关键在于从自由形式的意图转向一个有限的动作词汇表与显式参数——因为这才使提案能被软件检视,而不只是被读者检视。

工具使用研究把函数选择与参数构造视为不同的能力,正是出于这个原因。即使周围的自然语言回答听起来完全合理,模型仍会选择错误的函数、发明 API、提供不正确的参数。[1][4]


3. 解析不是校验,执行前的阶梯有五级

假设模型返回这个,且它完美解析:

{ "action": "launch_missiles", "arguments": {} }

解析器的成功只告诉我们一件事:表示可以被解码。它什么都没说关于该动作是否属于我们的系统。解码与校验是不同的工作,把它们合并就是 launch_missiles 到达分发表的方式。

把校验视为单一布尔值丢失的更多。一个提案可以通过一项检查却在下一项失败,它在哪一项失败是该边界产出的最有用调试信号。所以边界有五个不同的级:

级 问题 失败示例
1. 表示 输出能被解码吗? 截断的 JSON、代替对象的散文
2. Schema 结构正确吗? 未知动作、缺失字段、错误的基元类型
3. 语义 值对该动作有意义吗? 空 query、max_results 为 10,000,000
4. 授权 本次运行、用户和上下文允许吗? 只读运行中的合法 publish
5. 前置条件 当前能理智地执行吗? 文件缺失、预算耗尽、无连接

我们要把这五级变成真实的类型而不只是图,因为命名概念与实现它的差别构成了本书的大半:

from enum import StrEnum

class Stage(StrEnum):
    REPRESENTATION = "representation"
    SCHEMA = "schema"
    SEMANTICS = "semantics"
    AUTHORIZATION = "authorization"
    PRECONDITION = "precondition"
    EXECUTION = "execution"

前五个值命名的是副作用被允许之前发生的失败。EXECUTION 命名的是动作通过那些检查、环境被实际调用后的独立失败边界。它们一起给了本章一套从提案到观察的完整路径词汇。


4. 校验过的数据应该变成不同的类型

这里有一个值得单独陈述的设计动作,因为它做的工作比看起来多。

不要让任意字典流向执行。校验后,把提案转换成类型化动作:

from dataclasses import dataclass
from typing import Literal

@dataclass(frozen=True)
class SearchAction:
    kind: Literal["search"]
    query: str
    max_results: int

@dataclass(frozen=True)
class CalculateAction:
    kind: Literal["calculate"]
    expression: str

@dataclass(frozen=True)
class FinalAction:
    kind: Literal["final"]
    answer: str

Action = SearchAction | CalculateAction | FinalAction

执行器的签名现在写的是 Action,而不是 dict。这把边界显现在程序的类型结构里:静态分析能区分被接受的动作与不受信任的解码数据,且运行时可以组织成只有接受边界才构造 Action。Python 类型提示本身不强制这个边界。强制来自控制流:原始输出先被解码和校验,执行器只在校验路径产出的被接受对象上被调用。


5. 精确校验 schema

我们手工构建转换以便机制保持可见。首先,两个异常类型,让 schema 失败和语义失败一直可区分:

class SchemaError(ValueError):
    """Structure, keys or primitive types are wrong."""

class SemanticError(ValueError):
    """Structure is correct; the values are not usable."""

def require_exact_keys(data: dict, expected: set[str], *, where: str) -> None:
    actual = set(data)
    missing = expected - actual
    extra = actual - expected

    if missing:
        raise SchemaError(f"Missing fields in {where}: {sorted(missing)}")

    if extra:
        raise SchemaError(f"Unexpected fields in {where}: {sorted(extra)}")

拒绝额外键与要求缺失键同样重要。意外字段通常意味着模型发明了一个参数,静默丢弃它隐藏了模型以为自己在做出的一个决策。

现在是外层提案,它分派给每个动作的校验器:

def validate_proposal(data: object) -> Action:
    if not isinstance(data, dict):
        raise SchemaError("Action proposal must be an object")

    require_exact_keys(data, {"action", "arguments"}, where="action proposal")

    name, arguments = data["action"], data["arguments"]

    if not isinstance(name, str):
        raise SchemaError("action must be a string")

    if not isinstance(arguments, dict):
        raise SchemaError("arguments must be an object")

    validators = {
        "search": validate_search,
        "calculate": validate_calculate,
        "final": validate_final,
    }

    if name not in validators:
        raise SchemaError(f"Unknown action: {name}")

    return validators[name](arguments)

未知动作现在在这里失败,永远不会到达工具实现。


6. Schema 有效不等于语义有效

考虑一个类型全对的提案:

{
  "action": "search",
  "arguments": { "query": "", "max_results": 0 }
}

query 是字符串。max_results 是整数。仅类型的 schema 因此可以接受该提案,即使搜索毫无用处。更丰富的 schema 可以编码最小值、最大值、字符串长度、模式和枚举值等约束。哪里有稳定不变量能干净地放进 schema,就在那里编码。但并非每条语义规则只是结构性的。应用可能仍需在当前域和上下文中决定一个值是否有意义。所以每个校验器做两件事,并说明失败在哪一项:

def validate_search(args: dict) -> SearchAction:
    require_exact_keys(args, {"query", "max_results"}, where="search arguments")

    query, max_results = args["query"], args["max_results"]

    if not isinstance(query, str):
        raise SchemaError("query must be a string")

    if type(max_results) is not int:
        raise SchemaError("max_results must be an integer")

    query = query.strip()

    if not query:
        raise SemanticError("query cannot be empty")

    if not 1 <= max_results <= 20:
        raise SemanticError("max_results must be between 1 and 20")

    return SearchAction("search", query, max_results)

validate_calculate 和 validate_final 遵循相同形状:精确键、类型作为 SchemaError、值作为 SemanticError。这个模式刻意枯燥,而这种枯燥正是重点——这是我们想要零聪明才智的层。


7. 授权又是第三个问题

假设动作空间后来增长到包含 read_file、write_file、send_message 和 publish。一个 publish 提案可以完美合式、完全有意义,却仍不被当前运行允许。

这不是 schema 失败,也不是语义失败。这是一个授权决策,它依赖提案本身不包含的上下文:

@dataclass(frozen=True)
class RunPolicy:
    allowed_actions: frozenset[str]

def authorize(action: Action, policy: RunPolicy) -> None:
    if action.kind not in policy.allowed_actions:
        raise PermissionError(f"Action not allowed in this run: {action.kind}")

校验问 这是否描述了一个合法动作? 授权问 本次运行可否执行它? 把它们分开至关重要,一旦工具拥有副作用,因为它们按不同的时间表、出于不同的理由变化——动作契约是系统的属性,而策略是特定运行的属性。

模型可以提案超过运行时允许的。运行时拥有权限。


8. 约束生成有帮助,但不替代边界

许多生产系统不再只依赖提示词 please return valid JSON。它们可能使用原生函数调用、JSON Schema 约束输出、形式文法或约束解码。这是真正的改进:它可以消除整类表示和 schema 失败,且视约束语言而定,还能强制某些值限制。

它不消除运行时边界。授权和执行前置条件仍在约束生成之外,应用层级的语义不变量仍可能依赖解码器不拥有的上下文。约束解码可以产出结构完美的 {"action": "search", "arguments": {"query": "", "max_results": 20}},它语义上无用;也能产出完美合式的 publish 动作,而运行中没有发布权限。

四个机制回答四个不同的问题:

机制 回答的问题 所在位置
约束生成 输出能被正确塑形吗? 模型调用内部
运行时校验 结构与值满足应用不变量吗? 边界上
授权 本次运行有权限吗? 边界上,对照策略
前置条件检查 环境当前处于可执行该动作的状态吗? 边界上,对照当前运行时状态

用上全部四个。别指望任何一个替代另一个。


9. 修复表示,绝不捏造意图

假设模型把原本合法的 JSON 包在 Markdown 围栏里。剥离已知围栏是确定性的表示归一化,可以:

def strip_json_fence(text: str) -> str:
    text = text.strip()

    if text.startswith("``json"):
        text = text[len("``json"):]
    elif text.startswith("``"):
        text = text[len("``"):]

    if text.endswith("``"):
        text = text[:-3]

    return text.strip()

现在比较这个,表面上看很相似:

if "query" not in arguments:
    arguments["query"] = "something useful"

第一个恢复的是模型明确提供的值。第二个捏造了模型从未做出的决策,然后把捏造藏在通过的校验背后。每条下游日志都将显示一个合式的搜索,而智能体从未选择过它。

当预期值已无歧义时修复表示。绝不为了让校验通过而捏造语义意图。

这不禁止属于动作契约本身的默认值。如果 max_results 可选且运行时定义其默认值为 5,应用那个默认值是确定性契约行为,而非重构模型意图。危险的是仅因为某个特定提案校验失败就发明一个值。

当必需的语义意图缺失或模糊时,可见的拒绝优于静默捏造。拒绝保留了智能体未做出必需决策这一事实;临时替换抹除了它。


10. 拒绝变成观察

无效提案不必结束运行。它是信息,上一章给了我们放信息的地方。

这正是 Stage enum 存在的意义。我们需要一个结果类型,它不仅携带 失败了,还携带 在哪里失败了:

@dataclass(frozen=True)
class Accepted:
    action: Action

@dataclass(frozen=True)
class Rejected:
    stage: Stage
    message: str

Decision = Accepted | Rejected

拒绝直接转换成上一章的观察格式:

observation = {
    "kind": "invalid_action",
    "stage": rejection.stage,
    "error": rejection.message,
}

而策略可以带着确切的抱怨重试,而不是模糊的"再努力一次"指令:

def correction_prompt(previous_output: str, error: str) -> str:
    return f"""
Your previous action proposal was rejected.

Previous proposal:
{previous_output}

Validation error:
{error}

Return one corrected action proposal.
"""

因果结构——提案、拒绝、观察、新提案——就是上一章的循环第一次变得具体。注意校验器做了什么、没做什么。它没让智能体变聪明。它让失败可观察且可归因,这给了下一个决策具体的响应对象。


11. 修正需要预算

修正循环必须有界,且界限必须可见:

MAX_REPAIRS = 2

REPAIRABLE_STAGES = {
    Stage.REPRESENTATION,
    Stage.SCHEMA,
    Stage.SEMANTICS,
}

def get_valid_action(prompt: str, llm, policy: RunPolicy, context) -> Decision:
    raw = llm(prompt)

    for attempt in range(MAX_REPAIRS + 1):
        decision = prepare_action(raw, policy, context)

        if isinstance(decision, Accepted):
            return decision

        if decision.stage not in REPAIRABLE_STAGES:
            return decision

        if attempt == MAX_REPAIRS:
            return decision

        raw = llm(correction_prompt(raw, decision.message))

    raise RuntimeError("unreachable")

表示、schema 和语义失败可以证明修正提案本身是合理的。授权和前置条件失败通常应回到主智能体循环,因为同一提案的措辞改变不该改变运行时允许什么、或环境当前可能什么。

同一个模型连续三次失败同一个契约,在告诉我们一些值得知道的事——通常是动作 schema 模糊、或任务无法用我们定义的动作空间表达。无界重试循环通过纯重采样最终碰巧成功,毁掉了这个信号。

循环预算与终止稍后在构建运行时状态与进度时再详细处理。这里我们只需一个承诺:

校验修正策略必须有显式的失败状态。


12. 任何副作用前完全校验

从校验器角度看边界应当是原子的:完整解析提案、完全校验它、完全授权它、检查前置条件、然后仅执行一次。

这是普通软件工程,随机模型输出提高了赌注。一个半解读、已开始写文件的提案,把系统留在了阶梯任何一级都从未批准的状态里。执行器应该只操作运行时已完全接受的东西:

def execute(action: Action, tools):
    if isinstance(action, SearchAction):
        return tools.search(query=action.query, max_results=action.max_results)

    if isinstance(action, CalculateAction):
        return tools.calculate(action.expression)

    if isinstance(action, FinalAction):
        return action.answer

    raise TypeError(f"Unsupported validated action: {type(action)}")

模型从不调用工具。它从不持有工具引用。


13. 执行是另一道边界

通过校验不保证执行成功。搜索服务可能宕机、引用文件可能消失、API 可能拒绝提案时合法的请求。环境自由地在决策与行动之间改变。

所以执行返回观察,而不是静默变成真相:

from typing import Any

class ToolExecutionError(RuntimeError):
    """Expected operational failure reported by a capability adapter."""

@dataclass(frozen=True)
class Observation:
    ok: bool
    kind: str
    data: Any
    failure_stage: Stage | None = None

def execute_as_observation(action: Action, tools) -> Observation:
    try:
        value = execute(action, tools)
    except ToolExecutionError as exc:
        return Observation(
            ok=False,
            kind="execution_error",
            data=repr(exc),
            failure_stage=Stage.EXECUTION,
        )

    return Observation(
        ok=True,
        kind="action_result",
        data=value,
    )

这是第六个 Stage,也是运行时无法预防——只能观察和上报——的一个。

一次执行失败值得特殊对待:模糊的结果不是证明无副作用发生的证据。如果 charge_card() 发出后网络连接消失,盲目重试可能扣款两次。重试策略因此取决于能力契约。真正幂等的操作可在其声明条件下重复;非幂等变更应先通过幂等键、事务标识、收据或状态检查与环境核对。后续章节把幂等性变成能力契约的一部分。现在规则足矣:失败的响应不证明动作失败了。


14. 组装边界

以上一切组合成一个函数,值得仔细读,因为它是本章的压缩:

import json

def prepare_action(raw: str, policy: RunPolicy, context) -> Decision:
    try:
        data = json.loads(strip_json_fence(raw))
    except json.JSONDecodeError as exc:
        return Rejected(Stage.REPRESENTATION, str(exc))

    try:
        action = validate_proposal(data)
    except SchemaError as exc:
        return Rejected(Stage.SCHEMA, str(exc))
    except SemanticError as exc:
        return Rejected(Stage.SEMANTICS, str(exc))

    try:
        authorize(action, policy)
    except PermissionError as exc:
        return Rejected(Stage.AUTHORIZATION, str(exc))

    try:
        check_preconditions(action, context)
    except PreconditionError as exc:
        return Rejected(Stage.PRECONDITION, str(exc))

    return Accepted(action)

§3 的五个执行前级现在成了程序可执行的东西,而非读者必须记住的东西。每次拒绝都带着它掉落的那级标签。

这里重要的属性是架构性的而非句法的:原始输出无法在不经过这个函数的情况下到达 execute()。框架可能用装饰器、生成的 schema 或 provider 原生函数调用隐藏同样的责任。责任不会消失;只是变成别人的代码。

完整实现,包括 validate_calculate、validate_final 和前置条件级,在配套仓库中。


15. 先测边界,再度量它

动作边界是普通软件,配得上普通测试。因为拒绝现在带着级,我们可以断言在哪里失败,而不只是它失败了:

提案 预期级
畸形表示 REPRESENTATION
未知动作 SCHEMA
缺失参数 SCHEMA
意外参数 SCHEMA
错误基元类型 SCHEMA
空值或越界值 SEMANTICS
合法但被禁止的动作 AUTHORIZATION
合法、授权但运行时要求未满足 PRECONDITION
合法、授权、前置条件满足 到达执行器
执行期间预期的操作失败 EXECUTION,作为观察返回
def test_unknown_action_is_rejected_at_the_schema_rung():
    raw = json.dumps({"action": "teleport", "arguments": {}})
    policy = RunPolicy(allowed_actions=frozenset({"search", "calculate", "final"}))

    decision = prepare_action(raw, policy, context=None)

    assert isinstance(decision, Rejected)
    assert decision.stage is Stage.SCHEMA

def test_forbidden_action_is_rejected_at_the_authorization_rung():
    raw = json.dumps({
        "action": "search",
        "arguments": {"query": "PyTorch", "max_results": 5},
    })
    policy = RunPolicy(allowed_actions=frozenset({"final"}))

    decision = prepare_action(raw, policy, context=None)

    assert isinstance(decision, Rejected)
    assert decision.stage is Stage.AUTHORIZATION

两个测试刻意传 context=None,因为它们预期在前置条件级读取运行时上下文前就终止。前置条件测试必须改为提供能让要求成立或失败的具体状态。

这两个测试因不同理由失败,而断言说出了原因。如果每次拒绝都折叠成 bad tool call,我们就丢失了这个机制产出的诊断结构。

同一结构让度量变得直接:按级统计边界失败,而不是只报告单一成功率。执行前失败来自 Rejected.stage;预期执行失败来自 Observation.failure_stage。像 智能体成功率 = 72% 这样的数字对本章机制什么都不说,且可能在误导方向移动。假设一个 schema 变更导致静默错误执行下降、可见校验失败上升。聚合数字看起来更差。系统却变得更安全、且更容易调试得多。

这也是为什么像 BFCL 这样的函数调用基准把函数选择、参数匹配、相关性和多轮行为分开评估:“能调用工具"不是不可分割的单一能力。[4] 完全可观察性留待后续章节。现在:

记录提案动作失败的那个级。


16. 边界何时配得上它的成本

并非每个模型调用都需要这道边界。测试在于模型输出是否即将获得操作权威:

    flowchart TD
    Q{模型输出<br/>触发外部行为?} -->|no| T[普通输出]
    Q -->|yes| A[定义动作空间]
    A --> B[结构化提案]
    B --> C[校验]
    C --> D[授权]
    D --> E[执行]
  

Rewrite this paragraph 留在左支。 Choose one of these executable capabilities and supply its arguments 属于右支。

右支里藏着一个有用的诊断。如果一个能力无法被精确描述到可校验,那是设计信号而非校验问题。往往意味着动作接口太宽。像 run_anything(command) 这样的能力仍可通过沙箱、允许列表、路径策略和资源限制来约束,但它的语义契约比 read_file(path) 或 run_test(test_name) 粗糙得多。越难陈述什么是合法调用,运行时约束和推理该能力就要做越多工作。


17. 我们赢得了什么

上一章给了我们自适应控制。本章让那个循环的 act 步骤显式化,重要的增加从来不是 JSON。是概率性提案与确定性运行时权威的分离,这让我们能精确陈述契约:

模型可以提案它能生成的任何输出。只有运行时能把被接受的提案变成环境动作。

这是加到我们开始的那个智能体上的第一个机制,它立刻暴露了下一个问题。

一个提案可以合式、语义有效、授权通过、可执行——却仍是个糟糕的选择。我们的边界擅长拒绝畸形、无效、未授权或当前不可执行的提案。它对通过所有那些检查却仍是糟糕选择的提案完全无能为力。合法性与质量是不同属性。那么如何在不改变底层模型的情况下改进决策?一个答案在推理时花费额外计算来创造替代方案:不接受第一个提案,生成若干个,然后比较它们。


研究渊源

本章从普通软件工程原则推导动作边界,但有几个研究线索使动机具体化。

  1. Patil et al. — Gorilla: Large Language Model Connected with Massive APIs (2023). API 与工具使用暴露了错误的 API 选择与参数等失败,激发了显式接口与工具使用行为评估。
    https://arxiv.org/abs/2305.15334

  2. Geng et al. — Grammar-Constrained Decoding for Structured NLP Tasks without Finetuning (EMNLP 2023). 展示形式文法如何把生成约束在合法结构上,而不只依赖提示词合规。
    https://arxiv.org/abs/2305.13971

  3. Geng et al. — Generating Structured Outputs from Language Models: Benchmark and Studies (2025). 引入 JSONSchemaBench,在真实 JSON schema 上研究约束解码,包括效率、覆盖率与质量。
    https://arxiv.org/abs/2501.10868

  4. Patil et al. — The Berkeley Function Calling Leaderboard (BFCL): From Tool Use to Agentic Evaluation of Large Language Models (ICML 2025). 跨模型评估函数选择、参数构造、相关性、多轮工具使用及相关失败模式。
    https://gorilla.cs.berkeley.edu/leaderboard

下一章:候选生成与选择

我们有了一个运行时,能拒绝无效、未授权或当前不可执行的提案,并接受满足其边界的提案。它仍接受通过那些检查的第一个提案,意味着提案质量仍是单次模型调用的单次采样质量。

下一章保持边界完全不变,改变流入它的东西。我们不再生成一个提案,而是生成若干个,然后在它们中选择——这把智能体质量分成两个可度量的半边:是否曾产出过一个好候选,以及我们是否设法选中了它。