5.3 最佳实践与设计模式

5.3 最佳实践与设计模式

本节摘要：经验沉淀成模式，模式减少踩坑。本节汇总智能体开发的最佳实践：指令设计三原则、工具设计四要点、多智能体模式、成本与安全实践——把前四章的经验整理成"可复用的套路"。

本节目标

阅读完本节，你应当能够：

1. 应用指令设计三原则
2. 应用工具设计四要点
3. 识别常见设计模式
4. 应用成本与安全实践
5. 建立自己的实践清单

一、问题与直觉

"同样用 SDK，为什么高手做的智能体更好用？"——差别在"套路"。高手不是更聪明，而是踩过的坑沉淀成了模式。本节把这些模式直接给你：照着用，少走弯路。

本教程前四章分散讲了很多具体技巧，这一节把它们收拢成"清单式"的套路。清单的价值在于"可执行"：写指令时对照三原则，设计工具时对照四要点，新项目开工前把清单过一遍。有了清单，你不需要记住每个技巧的来龙去脉，只需要在正确的时候调用正确的检查项。

二、核心原理

2.1 指令设计三原则

• 明确：说清职责与边界，不给"自由发挥"留空间
• 可执行：每句都能被模型执行，不写抽象的"做好一点"
• 防越界：交代"不确定怎么办"，把兜底行为写进指令

2.2 工具设计四要点

三、工程实践要点

3.1 常用设计模式

💡 关键直觉：模式是"场景的答案"——遇到相似场景，先套模式再微调，比从零设计快得多、稳得多。

3.2 指令改写示例

改写前："回答用户关于产品的问题，语气要好。"
改写后："你是产品客服。用户问产品问题时，先检索知识库再回答；
        查不到就说明'暂时没有相关资料'；不评价竞品；
        一次回答不超过三句，语气温和。"
​

对比两组指令：改写前给了模型"模糊的自由"，改写后给了"确定的路径"。同样的模型，后者输出质量稳定得多——这就是"明确、可执行、防越界"在起作用。

3.3 成本实践清单

模型路由：简单小模型，复杂大模型
上下文管理：滚动窗口 + 摘要
缓存：无状态查询命中缓存
监控：记录每会话成本
​

3.4 安全实践清单

密钥：环境变量 + 密钥服务
护栏：输入输出双闸
日志：全量记录可回溯
权限：工具最小化授权
​

⚠️ 常见坑："安全实践"上线后补。安全是设计时的事，不是上线后的事——护栏、权限、日志在设计阶段就要进架构，事后补代价翻倍。

⚠️ 常见坑：把最佳实践当教条。模式是"大概率正确"的经验，不是"永远正确"的真理——遇到具体场景先理解为什么，再决定套不套。

3.5 建立自己的实践清单

把本节的清单做成自己的"项目检查表"
每个新项目开工前过一遍
踩到新坑就补进清单
​

清单会随着你的项目经验持续生长：今天踩的"模型温度没调导致输出不稳"，明天就变成清单里的一条。几个月后，这份清单就是你的"私有最佳实践"。

3.6 一个综合示例

from agents import Agent, Runner, function_tool

@function_tool
def check_stock(code: str) -> str:
    """查询股票现价，返回价格文本。"""
    try:
        return quote_api.get(code)
    except Exception as e:
        return f"行情暂不可用: {e}"

agent = Agent(
    name="投资助手",
    instructions=(
        "你是投资助手。规则："
        "1. 查行情必须调用工具，工具不可用时如实说明；"
        "2. 不提供买卖建议，只提供信息；"
        "3. 涉及风险时提示'投资有风险'。"
    ),
    tools=[check_stock],
)
​

这个示例同时用到：工具四要点（说明书清晰、错误可返回）、指令三原则（明确、可执行、防越界）、安全实践（不越权给建议）。

温故知新

• 要点一：指令三原则——明确、可执行、防越界
• 要点二：工具四要点——说明书、单一、可错、最小权
• 要点三：三模式——前台交接、并行扇出、护栏包裹
• 要点四：模式是场景的答案，先套再调
• 要点五：成本与安全是设计时的事
• 要点六：把自己的实践沉淀成检查表

套路有了，最后一节看落地——案例研究与行业应用。