动作边界
通过定义有限动作空间、校验结构与语义、将授权与执行分离、把失败视为运行时证据,把概率性的模型输出变成显式、可检视的动作提案。
上一章以责任分工作为结尾:
模型负责提出。运行时决定什么可以执行。环境提供关于发生了什么的观察。
本章认真对待第一个子句。模型提出一个动作究竟意味着什么?
假设模型发出句子 “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。是概率性提案与确定性运行时权威的分离,这让我们能精确陈述契约:
模型可以提案它能生成的任何输出。只有运行时能把被接受的提案变成环境动作。
这是加到我们开始的那个智能体上的第一个机制,它立刻暴露了下一个问题。
一个提案可以合式、语义有效、授权通过、可执行——却仍是个糟糕的选择。我们的边界擅长拒绝畸形、无效、未授权或当前不可执行的提案。它对通过所有那些检查却仍是糟糕选择的提案完全无能为力。合法性与质量是不同属性。那么如何在不改变底层模型的情况下改进决策?一个答案在推理时花费额外计算来创造替代方案:不接受第一个提案,生成若干个,然后比较它们。
研究渊源
本章从普通软件工程原则推导动作边界,但有几个研究线索使动机具体化。
-
Patil et al. — Gorilla: Large Language Model Connected with Massive APIs (2023). API 与工具使用暴露了错误的 API 选择与参数等失败,激发了显式接口与工具使用行为评估。
https://arxiv.org/abs/2305.15334 -
Geng et al. — Grammar-Constrained Decoding for Structured NLP Tasks without Finetuning (EMNLP 2023). 展示形式文法如何把生成约束在合法结构上,而不只依赖提示词合规。
https://arxiv.org/abs/2305.13971 -
Geng et al. — Generating Structured Outputs from Language Models: Benchmark and Studies (2025). 引入 JSONSchemaBench,在真实 JSON schema 上研究约束解码,包括效率、覆盖率与质量。
https://arxiv.org/abs/2501.10868 -
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
下一章:候选生成与选择
我们有了一个运行时,能拒绝无效、未授权或当前不可执行的提案,并接受满足其边界的提案。它仍接受通过那些检查的第一个提案,意味着提案质量仍是单次模型调用的单次采样质量。
下一章保持边界完全不变,改变流入它的东西。我们不再生成一个提案,而是生成若干个,然后在它们中选择——这把智能体质量分成两个可度量的半边:是否曾产出过一个好候选,以及我们是否设法选中了它。