2.2 智能体 Agent 核心

2.2 智能体（Agent）核心

本节摘要：Agent 是"行为定义"的容器。本节讲透 Agent 的配置项：指令（怎么做事）、模型（用什么思考）、工具（能做什么）、动态行为（运行时调整），并给出一份"配置检查清单"，让你能写出"靠谱的 Agent"。

核心问题

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

1. 说出 Agent 的核心配置项
2. 写出高质量指令
3. 按需配置模型与工具
4. 理解动态行为调整
5. 用检查清单验证 Agent 配置

一、问题与直觉

"同样的模型，有的 Agent 好用，有的不好用"——差别几乎全在 Agent 的配置上：指令清不清晰、工具配得对不对、模型选得合不合适。Agent 是"岗位说明书"，写得好不好，直接决定"员工"干得好不好。

把 Agent 想成一份完整的岗位说明书，它有四个必填项：身份（name）、职责说明（instructions）、可用资源（tools）、思考引擎（model）。除此之外还有可选项：动态行为（hooks）、输出格式（output_type）、交接对象（handoffs）、护栏（guardrails）。每个配置项都对应一种"行为影响"，配置得当，模型的行为就符合预期；配置含糊，模型就会"自由发挥"。

二、核心原理

Agent 是行为定义的核心容器：

2.1 Agent 的结构

一个最小可用的 Agent 只需要 name 与 instructions；挂上 tools 就能调用工具；指定 model 就能换思考引擎。

2.2 高质量指令的写法

坏指令："回答用户问题"
好指令："你是售后客服。先查订单再回答；查不到就说明；
          语气专业温和；不确定时明说不编造"
​

好指令有三个特征：明确（职责与边界清楚）、可执行（每句都能被模型执行）、防越界（不确定时怎么办有交代）。写指令的视角是"模型照着做不会错"，而不是"这句话听起来专业"。

2.3 完整配置示例

from agents import Agent, function_tool
from agents.model_settings import ModelSettings

@function_tool
def get_order(order_id: str) -> str:
    """查询订单状态。"""
    return f"订单 {order_id} 已发货"

agent = Agent(
    name="售后专员",
    instructions=(
        "你是电商售后客服。规则："
        "1. 先调用订单查询工具，拿到真实状态再回答；"
        "2. 查不到订单时如实说明，绝不编造；"
        "3. 语气专业温和，一次回答不超过 3 句；"
        "4. 用户要求退款时，引导联系人工客服。"
    ),
    model="gpt-4o-mini",
    tools=[get_order],
    model_settings=ModelSettings(temperature=0.3),
)
​

注意 temperature=0.3：客服场景要稳定、少发挥，温度调低；创意写作场景才需要高温度。模型参数也是 Agent 配置的一部分。

三、工程实践要点

3.1 配置检查清单

3.2 动态行为调整

# 概念：运行时修改 Agent
agent.instructions = "现在开始用幽默的语气回答"
agent.tools.append(新工具)
​

动态调整让"同一个 Agent 适应不同场景"成为可能——比如早班用正式语气、晚班用轻松语气。不过要注意：运行时改配置虽然方便，但不利于排查——生产环境建议把"不同场景"建模成"不同 Agent 实例"，而不是反复修改同一个对象。

⚠️ 常见坑：工具挂太多。每个工具都会占模型上下文，工具越多，模型"选错工具"的概率越大——只挂任务必需的，宁少勿多。

💡 关键直觉：指令是"给模型的规矩"，不是"给用户的文案"——写指令想着"模型照着做不会错"，而不是"听起来专业"。

3.3 多 Agent 的命名规范

多智能体场景，name 要能区分职责：

bad: agent1, agent2
good: 订单查询员, 物流跟踪员, 售后专员
​

名字不仅给人看，也出现在 Trace 日志和交接提示里——清晰的名字能大幅降低排错成本。

3.4 配置治理：把 Agent 当代码管理

Agent 配置多了以后，要像管理代码一样管理配置：指令文本纳入版本管理，每次修改可追溯；不同环境的指令差异（测试环境要不要真调工具）用配置项区分；关键 Agent 的配置写文档，说明"为什么这么设计"。最常见的问题是把 Agent 配置散落在各处，改一处忘了另一处，行为变得不可预期。把配置集中、命名清晰、版本可查，多智能体项目的可维护性会上一个台阶。

本章回顾

• 要点一：Agent 四块——身份、指令、模型、工具
• 要点二：指令是给模型的规矩，要清晰可执行
• 要点三：工具宁少勿多，防选错
• 要点四：模型按任务复杂度选，温度按场景调
• 要点五：动态行为让 Agent 适应场景
• 要点六：配置即产品，Agent 写得好应用才好用

Agent 定义好了，下一节看"司机"——运行器 Runner 机制。