Agent SDK 入门教程

# Agent SDK 入门教程

本教程帮助你理解什么是 Agent SDK，并通过实际例子学会使用它。

---

一、什么是 Agent SDK？

生活化类比

想象你想开一家外卖店：

直接调用 API = 自己当厨师：

• 你需要自己打电话给餐厅点餐
• 需要记住每个餐厅的电话号码
• 需要自己处理订单状态、超时、退款等
• 每次都要重复这些流程

使用 Agent SDK = 使用外卖平台：

• 平台帮你连接所有餐厅
• 你只需要说"我要什么"
• 平台自动处理：下单、追踪、异常处理、退款
• 你专注自己的业务逻辑

正式定义

Agent SDK 是一个软件开发工具包，它封装了：

• 模型调用（LLM Client）
• 工具执行（Tools）
• 循环控制（ReAct Loop）
• 上下文管理（Context/Memory）
• 权限治理（Governance）

让你用几十行代码就能创建一个能自动思考、调用工具、完成复杂任务的智能代理。

---

二、Agent SDK 的核心组成

┌─────────────────────────────────────┐
│  应用：CLI / Web / 桌面程序          │
├─────────────────────────────────────┤
│  ⑤ 监控层：tracing / 日志 / 成本统计  │
├─────────────────────────────────────┤
│  ④ 上下文层：对话历史 / 持久化 / 压缩  │
├─────────────────────────────────────┤
│  ③ 工具层：工具注册 / 执行 / 结果返回  │
├─────────────────────────────────────┤
│  ② 循环层：ReAct 循环（思考→行动→观察 │
├─────────────────────────────────────┤
│  ① 模型层：LLM 客户端 / 流式 / 多模型 │
└─────────────────────────────────────┘

逐层说明

层	作用
① 模型层	统一调用不同模型（OpenAI/DeepSeek等）
② 循环层	核心跳：思考→调用工具→看结果→再思考
③ 工具层	把 Python 函数变成 LLM 能调用的工具
④ 上下文层	管理对话历史，避免上下文爆炸
⑤ 监控层	记录每一步做了什么、花了多少钱

关键点：SDK 的价值在于把每个层都做成了可配置、可组合的接口，而不是硬编码。

---

三、进阶：手写一个简易 Agent SDK

基于你的 mini_coding_agent.py，我们把它改成 SDK 形态：

# mini_agent_sdk.py
from dataclasses import dataclass
from typing import Callable, Dict, List, Any
import json

@dataclass
class AgentConfig:
    """Agent 的配置（静态）"""
    name: str
    instructions: str
    tools: Dict[str, Callable]
    model: str = "gpt-3.5-turbo"
    max_steps: int = 10

class AgentSDK:
    """简易 Agent SDK"""
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.agents: Dict[str, AgentConfig] = {}
    
    def create_agent(self, config: AgentConfig):
        """注册一个 Agent"""
        self.agents[config.name] = config
        return config
    
    def run(self, agent_name: str, user_input: str) -> str:
        """运行指定的 Agent"""
        agent = self.agents[agent_name]
        # 这里调用你的 run_agent 逻辑
        # 把 agent.config 的内容传进去
        return self._run_loop(agent, user_input)
    
    def _run_loop(self, agent: AgentConfig, user_input: str) -> str:
        """复用你的 run_agent 逻辑"""
        # ... 你的 ReAct 循环代码 ...
        pass

# 使用示例
sdk = AgentSDK(api_key="your-key")

assistant = sdk.create_agent(AgentConfig(
    name="助手",
    instructions="你是一个有用助手...",
    tools={"get_weather": get_weather_function}
))

result = sdk.run("助手", "北京天气怎么样？")

这就是最简 SDK：把配置和执行分离，支持多 Agent。

---

七、常见问题

Q1：为什么要用 SDK，不能直接调 API？

直接调 API 只能完成单轮对话。遇到需要多步推理的任务（比如"写一个排序函数并测试"），你自己要写循环、处理工具调用、管理历史——这些 SDK 都做好了。

Q2：哪个 SDK 最好？

没有最好，看场景：

• 快速上手：OpenAI Agents SDK
• 复杂工作流：LangGraph
• 编码 Agent：Claude Agent SDK
• 多 Agent 协作：OpenAI SDK 的 handoffs 机制

---

四、延伸阅读

下一步可以：

• 看看真实 SDK 的源码（OpenAI Agents SDK 是开源的）
• 用 SDK 改造你的 mini_coding_agent.py（看看能省多少代码）
• 尝试多 Agent 协作（handoffs 模式）

---

总结

Agent SDK = 把 Agent 引擎封装成可嵌入的库

它不面对终端用户，而是让你用几十行代码就组装出自己的 Agent 应用。

---