🏠 总目录📚 本教程 附录B · 代码与检查单 ← →

智能体工程 · 附录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 重复劳动 委派指令含糊 结构化委派:目标+输出格式+边界
离线涨线上不涨 评测失真 查基础设施噪声、任务是否饱和、分维度看
加了分类器还是被注入 只有软防御 上环境层硬边界

👉 回到首页

打卡记录保存在你的浏览器里,首页能看到总进度