Agent 不是更长的 Prompt：
任务、工具、记忆、评估

我更愿意把 Agent 看成一个受约束的执行系统，而不是一个“会自己思考的聊天框”。它接收目标，形成计划，调用工具，观察结果，然后决定下一步。模型负责判断，代码负责边界。

一、任务层：先定义“做完”是什么

“帮我处理一下这个文件”不是一个可执行任务。Agent 需要知道输入是什么、输出给谁、成功条件是什么、哪些动作需要人确认。

• 目标：把一份试卷照片整理成可打印的练习。
• 约束：不要改动题目含义；答案必须单独放；图片不清晰时暂停询问。
• 完成条件：题目数量一致、答案可核对、文件能打开。

任务层写清楚，后面的工具和评估才有落点。否则模型只能靠猜，猜错以后你也不知道该改哪一层。

二、工具层：给能力，不要给 API 清单

把后端所有接口原样暴露给模型，通常不是好设计。模型需要的是面向任务的工具：名字说明意图，参数有明确约束，返回结果包含足够的观察信息。

// 不推荐：模型需要自己拼 URL、猜字段
GET /api/v1/records?type=homework&child=3

// 更推荐：一个意图明确的工具
search_homework({
  child_id: "3",
  subject: "math",
  date_range: "last_7_days"
})

工具设计会在另一篇展开，但先记住一个判断：工具的错误信息，也是模型继续工作的输入。只返回 500，模型无法恢复；返回“图片分辨率不足，请重新上传”，它才有下一步。

三、状态层：上下文不是记忆

聊天记录会越来越长，但它不是可靠的状态。一个可恢复的 Agent 至少要分开保存：

• 任务状态：当前步骤、已完成动作、待确认事项；
• 工作记忆：这次任务里需要反复引用的中间结果；
• 长期事实：用户偏好、稳定约束、历史结论；
• 原始轨迹：工具调用、观察、失败与重试，用于复盘。

把状态存成结构化数据，重试时就不必把整段对话再喂一遍；多轮之间也能明确“现在到底做到哪”。

四、评估层：不要只看最后一次回答

Agent 的输出是一个过程，不是一段文本。至少要记录：计划是否合理、工具是否选对、参数是否正确、观察是否被正确使用、最终结果是否满足完成条件。

最有效的起步方式不是搭一个庞大评测平台，而是准备 10–20 个真实任务，固定输入，记录轨迹，给失败分类。每次改 Prompt、工具或模型，都跑同一组任务。

failure_taxonomy = {
  "wrong_tool": "选错工具或漏掉必要工具",
  "bad_args": "参数缺失、格式错误、越权",
  "misread_observation": "工具返回后理解错",
  "premature_stop": "没完成就结束",
  "looping": "重复调用，无法收敛"
}

最小闭环

把四层压成一个最小循环，就是：

while not done:
    plan = decide_next_step(task, state, tools)
    result = execute(plan.tool, plan.args)
    state = observe(state, plan, result)
    done = check_done(task, state)

先让这个循环可观测、可暂停、可恢复，再考虑多 Agent、自主规划和长期记忆。否则你只是在一个黑盒外面又套了几个黑盒。