智能体工程 · 附录B
需要一段骨架代码,先核对哪些运行条件?
读完能做的判断:从原环境、循环、工具与检查单定位示例,保留代码和用途限制。
📑 本页目录(点开跳转)
附录 B · 代码与检查单
📌 按主题查找。各代码块是独立示例或接口骨架,不应整页串接执行;先读依赖和未实现项。只有第 01 节的假模型循环无需凭证即可直接运行。
📦 环境
pip install anthropic # 官方 SDK
pip install requests # 第 17 节项目一
pip install pytest # 第 17 节项目二
export ANTHROPIC_API_KEY=... # Windows PowerShell 当前会话:$env:ANTHROPIC_API_KEY="..."(使用自己的凭证,不写入仓库或日志)
零成本开发:先用第 1 节的 MockModel 把逻辑跑通,再换真模型。
🔁 最小 Agent 循环(第 1 节)
import json
def run_agent(model, tools, task, system, max_steps=10):
messages = [{"role": "system", "content": system},
{"role": "user", "content": task}]
for step in range(max_steps):
reply = model.chat(messages)
messages.append({"role": "assistant", "content": reply})
try:
call = json.loads(reply); assert "tool" in call
except (json.JSONDecodeError, AssertionError):
return reply # 最终答案
fn = tools.get(call["tool"])
result = fn(**call["args"]) if fn else f"错误:无 {call['tool']}"
messages.append({"role": "user", "content": f"工具结果:\n{result}"})
return "达到最大步数" # 护栏
🔌 接官方 tool use API
import anthropic
client = anthropic.Anthropic()
TOOLS = [{
"name": "search_logs",
"description": "在服务日志中搜索匹配的行。返回匹配行及前后各2行上下文。",
"input_schema": {
"type": "object",
"properties": {
"pattern": {"type": "string", "description": "正则或关键词"},
"max_lines": {"type": "integer", "description": "最多返回行数,默认50"},
},
"required": ["pattern"],
},
}]
def agent_turn(messages):
resp = client.messages.create(
model="claude-sonnet-5", max_tokens=2048,
tools=TOOLS, messages=messages)
if resp.stop_reason == "tool_use":
calls = [b for b in resp.content if b.type == "tool_use"]
if not calls:
raise ValueError("tool_use 停止却没有调用块")
messages.append({"role": "assistant", "content": resp.content})
results = []
for block in calls: # 一轮可能有多个调用,不能只处理第一个
try:
result = str(dispatch(block.name, block.input)) # 自行实现白名单与参数/权限校验
failed = False
except Exception:
result, failed = "工具失败;请检查参数或转人工。", True
results.append({"type": "tool_result", "tool_use_id": block.id,
"content": result, "is_error": failed})
messages.append({"role": "user", "content": results})
return None
if resp.stop_reason != "end_turn":
raise RuntimeError(f"本轮未完成:{resp.stop_reason}")
return "".join(b.text for b in resp.content if b.type == "text")
🏷️ @tool 装饰器(第 18 节挑战 A)
import inspect
def tool(fn):
sig = inspect.signature(fn)
fn._schema = {
"name": fn.__name__,
"description": (fn.__doc__ or "").strip(),
"input_schema": {
"type": "object",
"properties": {n: {"type": "string"} for n in sig.parameters},
"required": [n for n, p in sig.parameters.items()
if p.default is inspect.Parameter.empty],
},
}
return fn
@tool
def search_logs(pattern: str, max_lines: str = "50"):
"""在服务日志中搜索匹配的行,返回匹配行及上下文。"""
...
🗜️ 上下文压缩(第 4、18 节)
COMPACT_PROMPT = """总结以下 Agent 工作历史。必须显式保留:
1. 已完成的事
2. 当前状态
3. 下一步计划
4. 所有关键事实:文件路径、做过的决策、报错原文、数字
不要省略任何路径或报错——省略会导致重复犯错。
历史:
{history}"""
def compact(model, messages):
history = "\n".join(f"{m['role']}: {m['content']}" for m in messages[1:])
summary = model.chat([{"role": "user",
"content": COMPACT_PROMPT.format(history=history)}])
return [messages[0], # 保留 system
{"role": "user", "content": f"【历史摘要】\n{summary}\n\n请继续。"}]
def est_tokens(messages):
return sum(len(m["content"]) for m in messages) // 3 # 仅占用近似;中文和不同 tokenizer 误差另测,不能当累计消费预算
🌿 子 Agent(第 4、13 节)
def spawn_subagent(model, task, tools, system, depth=0, max_depth=2):
if depth >= max_depth:
return "已达子 Agent 深度上限" # 防无限递归
return run_agent(model, tools, task, system, max_steps=15)
# 只有返回值进入主上下文,子 Agent 的完整历史被丢弃
👮 好的工具错误信息(第 7 节)
def calculator(expression: str) -> str:
"""有界的四则/幂运算教学解释器;不执行 Python 代码。"""
import ast, math, operator
ops = {ast.Add: operator.add, ast.Sub: operator.sub,
ast.Mult: operator.mul, ast.Div: operator.truediv, ast.Pow: operator.pow}
def number(value):
if type(value) not in (int, float) or not math.isfinite(value) or abs(value) > 1e12:
raise ValueError("只接受绝对值不超过 1e12 的有限实数")
return value
def visit(node, depth=0):
if depth > 32:
raise ValueError("表达式嵌套过深")
if isinstance(node, ast.Constant):
return number(node.value)
if isinstance(node, ast.UnaryOp) and type(node.op) in (ast.UAdd, ast.USub):
value = visit(node.operand, depth + 1)
return number(value if isinstance(node.op, ast.UAdd) else -value)
if isinstance(node, ast.BinOp) and type(node.op) in ops:
left, right = visit(node.left, depth + 1), visit(node.right, depth + 1)
if isinstance(node.op, ast.Pow) and abs(right) > 10:
raise ValueError("指数绝对值上限为 10")
return number(ops[type(node.op)](left, right))
raise ValueError("只支持数字和 + - * / ** ( ),不支持名称、属性或函数")
try:
if not isinstance(expression, str) or len(expression) > 160:
raise ValueError("expression 应为不超过 160 字符的字符串")
tree = ast.parse(expression, mode="eval")
if sum(1 for _ in ast.walk(tree)) > 64:
raise ValueError("表达式节点过多")
return str(visit(tree.body))
except (ValueError, SyntaxError, ArithmeticError, RecursionError) as exc:
return f"计算出错:{exc}。示例:3.14 * 2**2"
🛡️ 环境层硬边界(第 15、20 节)
class Guard:
"""本地预检;actor 来自可信认证上下文,不来自模型参数。"""
def __init__(self):
self.whitelist = {"user_alice": frozenset({"user_bob"})}
def check_transfer(self, actor, to_u, amt):
if not isinstance(actor, str) or not isinstance(to_u, str):
return False, "拒绝:身份或收款账户类型错误"
if to_u not in self.whitelist.get(actor, ()):
return False, "拒绝:收款账户未授权"
if type(amt) is not int or amt <= 0:
return False, "拒绝:金额必须是正整数分"
if amt > 1000:
return False, "需要服务端独立审批;本例不实现批准后的执行"
return True, "ok"
def transfer(actor, to_u, amt, guard, confirmed=False):
# 保留旧参数以展示:模型填写的布尔值不改变任何授权判断。
ok, reason = guard.check_transfer(actor, to_u, amt)
if not ok:
return f"转账被拒:{reason}"
return "仅预检通过;本例未转账。余额、幂等和真实审批见 12b。"
⚠️ 反例:把「不许转给白名单外的人」写进系统提示词——那是软防御,不是硬边界。
📏 评测循环(第 14、19 节)
from collections import defaultdict
def evaluate(agent, tasks, code_scorer, runs=1):
if type(runs) is not int or runs <= 0 or not tasks:
raise ValueError("需要非空题集与正整数 runs")
results = []
for task in tasks:
for attempt in range(runs):
row = {"id": task["id"], "type": task["type"], "attempt": attempt,
"score": 0.0, "status": "failed"}
try:
out = agent.run(task["input"])
row["score"], row["note"] = code_scorer(out, task["reference"])
row["status"] = "completed"
except Exception as exc:
row["error_type"] = type(exc).__name__ # 不记录可能含隐私的异常原文
results.append(row) # 异常与超时也留在全部题次分母
return results
def summarize(results):
if not results:
raise ValueError("结果不能为空")
by = defaultdict(list)
for row in results:
by[row["type"]].append(row["score"])
return {kind: round(sum(scores) / len(scores), 3) for kind, scores in by.items()}
def pass_hat_k(results_per_task, k):
"""每题取前 k 次,计算全部成功的题目比例;不足 k 次不可计作成功。"""
if type(k) is not int or k <= 0 or not results_per_task:
raise ValueError("需要非空结果与正整数 k")
for scores in results_per_task.values():
if len(scores) < k:
raise ValueError("每道题必须保留至少 k 次结果,包括失败与超时")
if any(type(s) not in (int, float) or not 0 <= s <= 1 for s in scores[:k]):
raise ValueError("分数须为 0 到 1 的有限数值,未知先补完或单列")
return sum(all(s == 1.0 for s in scores[:k])
for scores in results_per_task.values()) / len(results_per_task)
🧪 LLM 评委 rubric 模板
RUBRIC = """按以下维度给输出打分,每项 0-25 分:
- 准确性:结论与事实/参考解一致吗
- 完整性:要求的要素都覆盖了吗
- 边界处理:异常/模糊输入处理得当吗
- 恰当拒绝:该说"不知道"时说了吗(不该拒绝的别拒绝)
输出 JSON:{"准确":分,"完整":分,"边界":分,"拒绝":分,"理由":"一句话"}
参考解:{reference}
实际输出:{output}"""
# ⭐ 用前以人工确认的正确、错误与边界答案校准;参考解得高分只是正向控制,还要能识别错误
📋 上生产检查单
要点
【架构】
☐ 做过降级测试,有数据证明当前复杂度必要(第6节)
☐ 能说清为什么用工作流/Agent、为什么用这种多Agent模式
☐ 多Agent的实测额外成本与协调开销对得起价值
【上下文】
☐ 系统提示词砍到最小,删掉了为旧模型写的补丁
☐ 长任务有压缩机制,且摘要保留关键事实
☐ 工具超过20个上了Tool Search
☐ 大量阅读类任务派给了子Agent
【工具】
☐ 工具按意图分组,不是API的一比一镜像
☐ 返回里没有模型用不上的字段
☐ 错误信息是可行动的(告诉模型怎么改)
☐ 危险操作做了防呆
【验证】
☐ Agent有能自己跑的验证(测试/编译/lint)
☐ 验证者不是干活的那个Agent
☐ 主观标准转成了可回答的rubric条目
【评测】
☐ 至少20个来自真实失败的任务,每个有参考解
☐ 评分器评产出不评路径,同时验证权限、审批、预算与副作用约束
☐ 读过转录,人工核对过评分器
☐ 明确该看pass@k还是pass^k
☐ 对小于3个百分点的差距保持怀疑
【安全】
☐ 做过威胁建模:Agent被完全控制最坏会怎样
☐ 至少一道环境层硬边界(代码里的if,不是提示词)
☐ 高危动作权限分离(能写≠能部署)
☐ 只在高危动作要确认,避免审批疲劳
☐ 外部内容当不可信数据处理
【运维】
☐ 有max_steps/超时/预算三道护栏,且优雅退出
☐ 状态可从出错点恢复,不用从头重跑
☐ 有结构化trace能回放决策路径
☐ 部署不打断运行中的Agent(彩虹部署)
【长期】
☐ 日历上有"模型升级后重审harness"的提醒
☐ 定期问:我可以停止做什么?
🐛 常见问题速查
| 症状 | 可能原因 | 处理 |
|---|---|---|
| Agent 跳步骤、草草收尾 | effort 不够 / 上下文焦虑 | 提 effort;检查是不是快到 token 上限 |
| 认真做了但结论错 | 模型能力不够 | 换更大模型 |
| 长会话后变笨 | 上下文腐烂 | 压缩或 /clear 重开 |
| 同一问题纠正三次还错 | 上下文被失败尝试污染 | 清空重来,用吸收教训的新提示词 |
| 工具老是用错参数 | 描述含糊 | 补 input_examples;参数改枚举 |
| 工具定义吃掉几万 token | 工具太多 | Tool Search 延迟加载 |
| 中间结果撑爆上下文 | 数据过模型 | 程序化调用/代码执行,数据留沙箱 |
| 宣布完成但根本没做完 | 没有验证闭环 | 给一个能跑的检查,要求跑到通过 |
| 自评总说自己做得好 | 自评正面偏差 | 生成与评估分离,独立上下文审查 |
| 多 Agent 重复劳动 | 委派指令含糊 | 结构化委派:目标+输出格式+边界 |
| 离线涨线上不涨 | 评测失真 | 查基础设施噪声、任务是否饱和、分维度看 |
| 加了分类器还是被注入 | 只有软防御 | 上环境层硬边界 |
👉 回到首页