Agent 类完整签名
Agent 是 SDK 的核心类，它的每个参数都有明确的语义。理解这些参数，是写出高质量 Agent 的前提：
from agents import Agent
from agents.models import ModelSettings
agent = Agent(
# ── 必填参数 ───────────────────────────────────────────
name="代码审查员", # Agent 的唯一名称，出现在追踪日志中
instructions="...", # 系统提示词（详见下节）
model="gpt-4o", # 使用的 OpenAI 模型
# ── 工具与协作 ─────────────────────────────────────────
tools=[...], # 可调用的工具列表
handoffs=[...], # 可移交的 Agent 列表
# ── 安全护栏 ───────────────────────────────────────────
input_guardrails=[...], # 输入护栏列表
output_guardrails=[...], # 输出护栏列表
# ── 模型参数 ───────────────────────────────────────────
model_settings=ModelSettings(
temperature=0.2, # 创造性（0=确定，1=随机）
top_p=0.9, # 核采样（与 temperature 二选一）
max_tokens=4096, # 最大输出 Token 数
),
# ── 输出类型 ───────────────────────────────────────────
output_type=None, # None=纯文本，Pydantic 模型=结构化输出
)Instructions 最佳实践
Instructions 是 Agent 的系统提示词，直接决定 Agent 的行为质量。好的 instructions 应该包含四个要素：
角色定义（Who you are）
清晰说明 Agent 是谁，有什么专长。避免模糊表述如"你是一个有帮助的助手"，应具体到"你是一名拥有 10 年经验的 Python 后端开发专家，专注于代码质量、性能优化和安全审查"。
能力边界（What you can/cannot do）
明确说明 Agent 的能力范围和限制。例如："你只审查 Python 代码，对于其他语言的代码审查请求，说明你的专长并建议用户寻找对应语言专家。"这避免 Agent 在超出能力范围时给出不可靠的回答。
行为规范（How to behave）
指定输出格式、语气、详细程度。例如："审查结果用 Markdown 格式输出，包含三部分：1) 总体评分（1-10分）2) 问题清单（按严重程度排序）3) 改进建议（附示例代码）。"
工具使用指引（When to use tools）
如果 Agent 有工具，在 instructions 中说明工具的使用时机。例如："当用户提供 GitHub URL 时，使用 fetch_code 工具获取代码内容，不要让用户手动粘贴代码。"
# 高质量 Instructions 示例：代码审查 Agent
CODE_REVIEW_INSTRUCTIONS = """你是一名专业的 Python 代码审查专家，拥有丰富的生产环境经验。
## 你的专长
- Python 3.10+ 最新特性与最佳实践
- 代码安全（SQL 注入、XSS、密钥泄露等）
- 性能优化（算法复杂度、内存使用、异步编程）
- 代码可读性与可维护性
## 审查流程
当用户提交代码时，按以下顺序审查：
1. 安全性：是否有明显的安全漏洞
2. 正确性：逻辑是否正确，边界情况是否处理
3. 性能：是否有明显的性能问题
4. 可读性：命名是否清晰，注释是否充分
## 输出格式
使用以下 Markdown 结构输出：
### 总体评分: X/10
### 🔴 严重问题
### 🟡 需要改进
### 🟢 值得肯定
### 💡 改进建议（附代码示例）
## 注意事项
- 只审查 Python 代码，其他语言礼貌说明
- 评分要客观，不要为了鼓励而虚高评分
- 改进建议必须附上具体代码示例
"""
code_reviewer = Agent(
name="代码审查员",
instructions=CODE_REVIEW_INSTRUCTIONS,
model="gpt-4o", # 代码审查用高质量模型
model_settings=ModelSettings(temperature=0.1) # 低温度，减少幻觉
)模型选择策略
选择合适的模型是控制成本和质量的关键。以下是各模型的适用场景：
| 模型 | 适用场景 | 特点 | 相对成本 |
|---|---|---|---|
gpt-4o |
复杂推理、代码审查、多步骤任务 | 质量最高，多模态（视觉+文字） | 高 |
gpt-4o-mini |
日常对话、简单分类、快速响应 | 速度快，成本低，质量良好 | 低 |
o1 |
数学、逻辑推理、复杂规划 | 深度思考，准确率极高 | 很高 |
o3-mini |
代码生成、STEM 问题、推理任务 | 推理能力强，比 o1 更快更便宜 | 中高 |
成本优化技巧
在多 Agent 系统中，让 Orchestrator 使用 gpt-4o-mini（负责分类和路由），让专家 Agent 使用 gpt-4o（负责具体业务）。这通常能在不显著降低质量的前提下，将整体成本降低 60-70%。
model_settings 调参详解
from agents.models import ModelSettings
# temperature：控制输出随机性
# 0.0 = 完全确定（工具调用、结构化任务）
# 0.2-0.4 = 轻微创造性（报告、分析）
# 0.7-1.0 = 高创造性（创意写作、头脑风暴）
# 场景 1：代码生成 — 低温度，需要精确
code_agent = Agent(
name="代码生成器",
instructions="生成高质量的 Python 代码。",
model="gpt-4o",
model_settings=ModelSettings(
temperature=0.0, # 确定性输出，减少幻觉
max_tokens=8192, # 代码可能较长
)
)
# 场景 2：创意写作 — 高温度，需要多样性
writer_agent = Agent(
name="创意写作助手",
instructions="创作有创意的文章和故事。",
model="gpt-4o",
model_settings=ModelSettings(
temperature=0.9, # 高随机性，增加创意
max_tokens=2048,
)
)
# 场景 3：分类 Agent — 极低温度，输出可预测
classifier = Agent(
name="问题分类器",
instructions="将用户问题分类为：技术/账单/投诉/其他。",
model="gpt-4o-mini",
model_settings=ModelSettings(
temperature=0.0,
max_tokens=50, # 分类只需要很少 Token
)
)Agent 克隆：快速创建变体
当需要创建多个相似但有细微差异的 Agent 时，agent.clone() 避免重复配置：
# 基础 Agent，包含公共配置
base_support_agent = Agent(
name="客服基础",
instructions="你是友善专业的客服代表，使用礼貌的中文回复。",
model="gpt-4o-mini",
model_settings=ModelSettings(temperature=0.3)
)
# 克隆并覆盖部分配置——继承 model 和 model_settings
tech_support = base_support_agent.clone(
name="技术支持专员",
instructions="""你是技术支持专员，专注于解决产品技术问题。
当问题无法解决时，收集以下信息：系统版本、错误信息、复现步骤。
"""
)
billing_support = base_support_agent.clone(
name="账单专员",
instructions="""你是账单处理专员，专注于处理付款、退款和发票问题。
涉及退款超过 500 元时，需要先核实用户身份。
"""
)
print(tech_support.model) # gpt-4o-mini（继承自 base）
print(billing_support.model) # gpt-4o-mini（继承自 base）Dynamic Instructions：动态生成系统提示词
Static instructions（固定字符串）无法应对个性化需求。Dynamic Instructions 允许根据运行时上下文动态生成系统提示词：
from agents import Agent, RunContextWrapper
from dataclasses import dataclass
# ── 定义上下文数据模型 ────────────────────────────────────
@dataclass
class UserContext:
user_name: str
user_language: str # "zh" | "en" | "ja"
subscription_tier: str # "free" | "pro" | "enterprise"
timezone: str
# ── Dynamic Instructions 函数 ─────────────────────────────
def build_instructions(
ctx: RunContextWrapper[UserContext],
agent: Agent
) -> str:
"""根据当前用户上下文动态生成系统提示词"""
user = ctx.context
# 根据语言选择回复方式
lang_instruction = {
"zh": "始终使用中文回复",
"en": "Always reply in English",
"ja": "常に日本語で返答してください"
}.get(user.user_language, "使用用户的语言回复")
# 根据订阅等级调整能力
tier_note = {
"free": "用户使用免费版，功能有限制，复杂需求建议升级到 Pro。",
"pro": "用户使用 Pro 版，可以使用所有功能。",
"enterprise": "用户是企业客户，优先响应，可提供自定义方案。"
}.get(user.subscription_tier, "")
return f"""你是 AI 助手，正在服务用户 {user.user_name}。
语言要求：{lang_instruction}
当前时区：{user.timezone}
用户等级：{tier_note}
提供准确、个性化的帮助。时间相关问题请参考用户时区。
"""
# ── 使用 Dynamic Instructions ──────────────────────────────
personalized_agent = Agent(
name="个性化助手",
instructions=build_instructions, # 传入函数，而非字符串
model="gpt-4o-mini"
)
# 运行时传入上下文
async def handle_user_request(user_query: str, user: UserContext):
result = await Runner.run(
personalized_agent,
user_query,
context=user # 注入用户上下文
)
return result.final_output
# 测试
import asyncio
user = UserContext(
user_name="Alice",
user_language="zh",
subscription_tier="pro",
timezone="Asia/Shanghai"
)
result = asyncio.run(handle_user_request("现在几点？", user))
print(result) # 以上海时区为准的中文回复实战：专业代码审查 Agent 完整实现
from agents import Agent, Runner, function_tool
from agents.models import ModelSettings
from pydantic import BaseModel
import asyncio
# ── 结构化输出模型 ─────────────────────────────────────────
class ReviewIssue(BaseModel):
severity: str # "critical" | "warning" | "info"
location: str # 行号或函数名
description: str
suggestion: str
class CodeReviewResult(BaseModel):
score: int # 1-10
summary: str
issues: list[ReviewIssue]
highlights: list[str] # 值得肯定的地方
# ── 工具：获取 GitHub 代码 ─────────────────────────────────
@function_tool
async def fetch_github_code(url: str) -> str:
"""从 GitHub URL 获取代码内容。支持 raw 链接和普通文件链接。"""
import httpx
# 将普通 GitHub 链接转为 raw 链接
raw_url = url.replace("github.com", "raw.githubusercontent.com")
raw_url = raw_url.replace("/blob/", "/")
async with httpx.AsyncClient() as client:
response = await client.get(raw_url, timeout=10)
response.raise_for_status()
return response.text[:10000] # 限制长度，避免超出 Context
# ── 代码审查 Agent ─────────────────────────────────────────
code_reviewer = Agent(
name="Python 代码审查员",
instructions="""你是经验丰富的 Python 工程师，专注代码质量审查。
审查维度（按重要性排序）：
1. 安全漏洞：SQL 注入、路径遍历、硬编码密钥
2. 逻辑错误：边界条件、空值处理、异常捕获
3. 性能问题：N+1 查询、不必要循环、内存泄漏
4. 代码风格：PEP 8、命名规范、函数长度
用户提供 GitHub URL 时，使用 fetch_github_code 工具获取代码。
用户直接粘贴代码时，直接审查。
以 JSON 格式输出审查结果。
""",
model="gpt-4o",
model_settings=ModelSettings(temperature=0.1),
tools=[fetch_github_code],
output_type=CodeReviewResult # 结构化输出
)
async def review_code(code_or_url: str):
result = await Runner.run(code_reviewer, code_or_url)
review: CodeReviewResult = result.final_output_as(CodeReviewResult)
print(f"评分：{review.score}/10")
print(f"摘要：{review.summary}")
print(f"发现 {len(review.issues)} 个问题")
for issue in review.issues:
print(f" [{issue.severity}] {issue.location}: {issue.description}")
asyncio.run(review_code("https://github.com/user/repo/blob/main/app.py"))
本章小结
Agent 的质量在很大程度上由 instructions 决定——角色定义、能力边界、行为规范、工具使用指引缺一不可。模型选择遵循"够用原则"：gpt-4o-mini 处理简单任务，gpt-4o 处理复杂推理。Dynamic Instructions 实现个性化 Agent，将运行时数据注入系统提示词。下一章学习如何定义和集成各类工具。