从零开始构建一个简单的 AI Agent 框架：完整新手教程

本教程将带你从零开始，一步步构建一个具备工具调用能力的简单 Agent 框架。即使你是编程新手，也能跟着教程完成并能成功运行代码。

---

📚 目录

• 什么是 Agent？
• 准备工作
• 第一步：构建"大脑"- 统一的大模型适配层
• 第二步：实现基础 Agent - 对话记忆系统
• 第三步：装备工具 - 让 Agent 能"做事"
• 第四步：消息标准化 - 统一通信格式
• 第五步：整合一切 - 完整的 ToolAgent
• 运行与测试
• 常见问题排查
• 总结与进阶

---

什么是 Agent？

🤖 概念理解

Agent（智能体） = 大模型（大脑）+ 记忆系统 + 工具调用能力 + 任务规划能力

比喻：

• 大模型

  = 大脑（思考、理解、决策）

• 记忆系统

  = 记忆（记住对话历史）

• 工具调用

  = 手脚（执行实际任务，如搜索、计算）

• 任务规划

  = 规划能力（分解复杂任务）

🎯 我们的实现目标

构建一个简单的 Agent，具备以下能力：

1. ✅ 与用户对话并保持上下文记忆
2. ✅ 调用 Google 搜索工具获取实时信息
3. ✅ 自动决定何时调用工具
4. ✅ 综合工具结果生成最终答案

---

准备工作

1 创建项目目录

# 在你的桌面创建项目目录cd ~/Desktopmkdir agentcd agent

2 创建依赖管理文件

创建 requirements.txt 文件：

openai>=1.0.0python-dotenv>=1.0.0google-search-results>=2.4.2

3 安装依赖

pip3 install -r requirements.txt

4 配置环境变量

创建 .env 文件（不要提交到 Git）：

# 方案1：使用 DeepSeek（推荐，有免费额度）API_KEY=sk-your-deepseek-api-keyBASE_URL=xxxxxMODEL_NAME=deepseek-chat# 方案2：使用 OpenAI（需要 API Key）# API_KEY=sk-your-openai-api-key# BASE_URL=xxxxx# MODEL_NAME=gpt-3.5-turbo# Google 搜索 API（用于工具功能）SERPAPI_API_KEY=your-serpapi-key

---

第一步：构建"大脑"- 统一的大模型适配层

🎯 目标

创建一个统一的大模型调用接口，屏蔽不同厂商的 API 差异。

📝 创建文件：llm.py

# llm.pyfrom openai import OpenAIimport osfrom dotenv import load_dotenvload_dotenv()  # 加载环境变量class LLMClient:    def __init__(self):        # 通过环境变量配置，轻松切换不同厂商        self.client = OpenAI(            api_key=os.getenv("API_KEY"),            base_url=os.getenv("BASE_URL")         )        self.model = os.getenv("MODEL_NAME", "gpt-4o")    def chat(self, messages, tools=None):        """        统一的对话入口，屏蔽底层差异        参数:            messages: 对话历史列表            tools: 工具定义列表（可选）        返回:            OpenAI API 的响应对象        """        params = {            "model": self.model,            "messages": messages,        }        if tools:            params["tools"] = tools        # 这里为了演示简洁，暂不开启流式输出        return self.client.chat.completions.create(**params)

💡 代码解释

核心设计思想：

1. 环境变量配置

api_key=os.getenv("API_KEY")base_url=os.getenv("BASE_URL")

• 将敏感信息（API Key）放在 .env 文件中
• 避免硬编码在代码里，提高安全性

2. 统一接口

def chat(self, messages, tools=None):    return self.client.chat.completions.create(**params)

• 封装 OpenAI API 的调用细节
• 提供简单易用的 chat() 方法
• 支持 tools 参数，让 Agent 能调用工具

3. 易于切换厂商

• 只需修改 .env 中的 BASE_URL 和 MODEL_NAME
• 代码完全不需要改动

🔍 为什么需要这个适配层？

❌ 没有适配层

# 硬编码，不安全，难以维护import openairesponse = openai.ChatCompletion.create(    model="gpt-4o",    messages=[...],    api_key="sk-xxx"  # 暴露在代码中)

✅ 使用适配层

# 简洁、安全、易切换from llm import LLMClientllm = LLMClient()response = llm.chat([{"role": "user", "content": "你好"}])

---

第二步：实现基础 Agent - 对话记忆系统

🎯 目标

创建一个能记住对话历史的 Agent，实现多轮对话。

📝 创建文件：agent.py

# agent.py (基础版)from llm import LLMClientclass SimpleAgent:    def __init__(self):        self.llm = LLMClient()        # 初始化记忆，设定基础背景        self.messages = [{"role": "system", "content": "你是一个乐于助人的AI助手。"}]    def chat(self, user_input):        # 1. 接收：将用户输入存入记忆        self.messages.append({"role": "user", "content": user_input})        # 2. 思考：带着所有历史记录去请求 LLM        response = self.llm.chat(self.messages)        content = response.choices[0].message.content        # 3. 闭环：将 AI 的回答也存入记忆        self.messages.append({"role": "assistant", "content": content})        return content

💡 代码解释

核心概念：消息角色

# system: 设定 AI 的身份和行为规则{"role": "system", "content": "你是一个乐于助人的AI助手。"}# user: 用户的输入{"role": "user", "content": "我叫小明"}# assistant: AI 的回答{"role": "assistant", "content": "你好小明，很高兴认识你！"}

工作流程（三步闭环）：

📥 用户输入 → 💾 存入记忆 → 🧠 调用 LLM（带上完整历史）→ 📤 获取回答 → 💾 存入记忆 → ✅ 返回给用户

为什么需要记忆？

• 大模型本身是无状态的，每次调用都是独立的
• 通过传递历史消息，让 AI 理解上下文
• 实现多轮对话和连贯性

🧪 测试基础 Agent

创建测试文件 test_agent.py：

# test_agent.pyfrom agent import SimpleAgentdef main():    agent = SimpleAgent()    print("=== 简单的AI助手 ===")    print("输入'quit'退出\n")    while True:        user_input = input("你: ")        if user_input.lower() == 'quit':            break        response = agent.chat(user_input)        print(f"Agent: {response}\n")if __name__ == "__main__":    main()

运行测试：

python3 test_agent.py

示例对话：

=== 简单的AI助手 === 输入'quit'退出  你: 我叫susie Agent: 你好susie！我是SimpleAgent，有什么我可以帮助你的吗？  你: 你记得我叫什么吗？ Agent: 当然记得，你叫susie！  你: quit

---

第三步：装备工具 - 让 Agent 能"做事"

🎯 目标

实现工具注册和调用系统，让 Agent 能执行实际任务（如 Google 搜索）。

📝 创建文件：tools.py

# tools.pyimport inspectimport jsonimport osfrom functools import wrapsfrom google_search_results import GoogleSearchclass ToolRegistry:    """工具注册中心：管理所有可用工具"""    def __init__(self):        self.tools = {}    # 存函数实体        self.schemas = []  # 存函数说明书（JSON Schema）    def register(self, func):        """        魔法装饰器：自动将 Python 函数转换为 OpenAI Tool Schema        """        name = func.__name__  # 函数名        doc = func.__doc__ or "No description"  # 函数文档字符串        # 解析函数签名        sig = inspect.signature(func)        params = {"type": "object", "properties": {}, "required": []}        # 遍历参数，生成 JSON Schema        for param_name, param in sig.parameters.items():            params["properties"][param_name] = {                "type": "string",                 "description": f"参数 {param_name}"            }            if param.default == inspect.Parameter.empty:                params["required"].append(param_name)        # 1. 生成说明书（给 LLM 看）        self.schemas.append({            "type": "function",            "function": {                "name": name,                 "description": doc,                 "parameters": params            }        })        # 2. 存储函数（实际执行）        self.tools[name] = func        @wraps(func)        def wrapper(*args, **kwargs):             return func(*args, **kwargs)        return wrapper    def execute(self, name, args_json):        """执行器：根据 LLM 的指令运行代码"""        if name in self.tools:            try:                args = json.loads(args_json)  # 将 JSON 字符串转为字典                print(f"⚙️ [System] 正在调用工具: {name} 参数: {args}")                return self.tools[name](**args)  # 执行函数，解包参数            except Exception as e:                return f"Error: {str(e)}"        return "Tool not found"# 创建全局注册表registry = ToolRegistry()# ========== 定义工具 ==========@registry.registerdef google_search(query: str):    """    当用户询问当前事件、新闻、天气或不知道的信息时，使用此工具进行搜索。    """    try:        search = GoogleSearch({            "q": query,             "api_key": os.getenv("SERPAPI_API_KEY"),        })        # 数据清洗：只提取前两条结果的标题和摘要，节省 Token        results = search.get_dict().get("organic_results", [])[:2]        return "\n".join([            f"- {r.get('title')}: {r.get('snippet')}"             for r in results        ])    except Exception as e:        return f"搜索失败: {e}"

💡 代码解释

核心设计：装饰器模式

@registry.registerdef google_search(query: str):    """函数描述"""    pass

装饰器做了什么？

1. 提取函数信息

• 名称：google_search
• 描述：函数的文档字符串
• 参数：从类型注解 query: str 中提取

2. 生成 JSON Schema（给 LLM 看的"说明书"）

{   "type": "function",   "function": {     "name": "google_search",     "description": "当用户询问当前事件、新闻、天气或不知道的信息时，使用此工具进行搜索。",     "parameters": {       "type": "object",       "properties": {         "query": {           "type": "string",           "description": "参数 query"         }       },       "required": ["query"]     }   } }

3. 存储函数（实际执行用的）

self.tools['google_search'] = google_search  # 存储真实的 Python 函数

为什么用装饰器？

没有装饰器时，需要手动写一遍函数，再写一遍 JSON Schema，容易出错。
使用装饰器后，只需写一次函数，自动生成说明书。

---

第四步：消息标准化 - 统一通信格式

🎯 目标

创建消息辅助函数，确保消息格式标准化，避免手动构造字典出错。

📝 创建文件：message.py

# message.pydef user_msg(content):    """用户消息"""    return {"role": "user", "content": content}def assistant_msg(content=None, tool_calls=None):    """    助手消息    - content: 文本回复（可选）    - tool_calls: 工具调用请求（可选）    """    msg = {"role": "assistant"}    if content:         msg["content"] = content    if tool_calls:         msg["tool_calls"] = tool_calls    return msgdef tool_msg(tool_call_id, content):    """    工具消息    - tool_call_id: 工具调用 ID（关键！）    - content: 工具返回结果    """    return {        "role": "tool",        "tool_call_id": tool_call_id,        "content": str(content)    }

💡 代码解释

为什么需要标准化？

❌ 手动构造消息

# 容易出错messages.append({"role": "user", "content": "你好"})messages.append({"rol": "assistant", "content": "你好"})  # 拼写错误！messages.append({"role": "tool", "content": "结果"})  # 缺少 tool_call_id！

✅ 使用辅助函数

# 标准化，不易出错messages.append(user_msg("你好"))messages.append(assistant_msg(content="你好"))messages.append(tool_msg("call_123", "搜索结果"))

核心概念：tool_call_id（快递单号）

LLM: “帮我搜索北京天气” → 生成单号 call_abc123
↓
调用搜索工具
↓
工具返回结果，附上单号 call_abc123
↓
LLM 看到单号，知道这是北京天气的搜索结果

消息类型总结：

函数	role	必需字段	可选字段	用途
user_msg()	“user”	content	-	用户输入
assistant_msg()	“assistant”	-	content, tool_calls	LLM 的回复（文本或工具调用）
tool_msg()	“tool”	tool_call_id, content	-	工具执行结果

---

第五步：整合一切 - 完整的 ToolAgent

🎯 目标

将前面所有组件整合，实现具备工具调用能力的完整 Agent。

📝 创建文件：tool_agent.py

# tool_agent.pyimport jsonfrom llm import LLMClientfrom tools import registry  # 导入工具注册表from message import user_msg, assistant_msg, tool_msgclass ToolAgent:    def __init__(self):        self.llm = LLMClient()  # 大脑        self.tools = registry   # 工具箱        # self.messages 记忆系统        self.messages = [{            "role": "system",             "content": "你是一个全能助手，可以调用工具获取实时信息。如果觉得已经足够回复用户了，就不用再调用工具了。"        }]    def chat(self, user_input):        """        支持工具调用的 ReAct 循环入口        注意：为了演示逻辑清晰，这里暂时使用非流式        """        # 1. 存入用户问题        self.messages.append(user_msg(user_input))        # 设置最大循环次数，防止 Agent 陷入死循环        max_turns = 5        turn_count = 0        while turn_count < max_turns:            turn_count += 1            # 2. 调用 LLM（带上 tools 定义）            print(f"\n🤖 [Thinking] 第 {turn_count} 轮思考...")            response = self.llm.chat(                messages=self.messages,                tools=self.tools.schemas  # 关键：把工具说明书发给 LLM            )            response_msg = response.choices[0].message            # 3. 判断 LLM 的意图            tool_calls = response_msg.tool_calls            if tool_calls:                # === 情况 A: LLM 想要调用工具 ===                # A1. 先把 LLM 的"调用指令"存入记忆（这步不能省！）                ai_msg_dict = assistant_msg(                    content=response_msg.content,                    tool_calls=tool_calls                )                self.messages.append(ai_msg_dict)                # A2. 遍历所有工具调用请求（LLM 可能一次想调多个工具）                for tool_call in tool_calls:                    func_name = tool_call.function.name                    func_args = tool_call.function.arguments                    call_id = tool_call.id                    print(f"✋ [Action] 正在调用工具: {func_name} ...")                    # A3. 执行真正的 Python 代码                    tool_result = self.tools.execute(func_name, func_args)                    # A4. 构建 Tool Message（观察结果）                    # 关键：一定要带上 call_id，否则 LLM 不认账                    tm = tool_msg(tool_call_id=call_id, content=tool_result)                    self.messages.append(tm)                    print(f"👀 [Observation] 工具返回: {tool_result[:50]}...")                # A5. 循环继续 -> 回到 while 开头，把结果发给 LLM            else:                # === 情况 B: LLM 没调工具，直接回复 ===                content = response_msg.content                self.messages.append(assistant_msg(content=content))                return content        return "❌ 任务太复杂，超过最大循环次数。"# --- 演示代码 ---if __name__ == "__main__":    # 确保 .env 里配置了 SERPAPI_API_KEY    agent = ToolAgent()    while True:        try:            user_input = input("\n👤 你：").strip()            # 检查用户输入            if user_input.lower() in ['exit', 'q', '退出']:                print("\n👏再见！")                break            # 如果用户输入为空，跳过            if not user_input:                continue            final_answer = agent.chat(user_input)            print("\n" + "=" * 30)            print(f"🤖 Final Answer:\n{final_answer}")            print("=" * 30)        except KeyboardInterrupt:            print("\n\n 🙏 检测到中断，退出程序")            break        except Exception as e:            print(f"\n❌ 发生错误: {e}")            import traceback            traceback.print_exc()  # 打印详细的错误信息

💡 代码解释

核心设计：ReAct 模式

ReAct = Reasoning + Acting（推理 + 行动）

用户：今天北京天气怎么样？
↓
LLM 思考：我需要查询天气信息
↓
LLM 行动：调用搜索工具
↓
观察结果：北京今天晴天，25度
↓
LLM 思考：现在我有了信息，可以回答用户了
↓
LLM 行动：生成最终回复

为什么需要循环？

一次对话可能需要多次工具调用：

用户：帮我规划北京一日游
↓
第1轮：LLM 决定先了解北京天气 → 调用搜索工具
↓
第2轮：LLM 得到天气信息，继续思考需要知道景点 → 再次调用搜索
↓
第3轮：LLM 得到景点信息，综合所有信息 → 生成完整旅游规划

关键设计点：

1. 存储调用指令（A1）

• 必须将 LLM 的工具调用请求存入记忆
• 否则下次调用时 LLM 会忘记

2. tool_call_id（A4）

• 必须带上调用 ID，让 LLM 知道结果对应哪个工具

3. 防止死循环

• 最多 5 轮工具调用，避免无限循环

---

运行与测试

🚀 运行 ToolAgent

python3 tool_agent.py

📝 示例对话

场景1：询问天气（需要调用工具）

👤 你：今天北京天气怎么样？  🤖 [Thinking] 第 1 轮思考... ✋ [Action] 正在调用工具: google_search ... ⚙️ [System] 正在调用工具: google_search 参数: {'query': '北京天气'} 👀 [Observation] 工具返回: - 北京今天天气预报: 晴天，气温25°C...  🤖 [Thinking] 第 2 轮思考...  ============================== 🤖 Final Answer: 根据搜索结果，北京今天是个好天气！晴天，气温25°C，非常适合外出活动。 ==============================

场景2：简单对话（不需要工具）

👤 你：你好  🤖 [Thinking] 第 1 轮思考...  ============================== 🤖 Final Answer: 你好！我是全能助手，有什么可以帮助你的吗？ ==============================

场景3：退出

👤 你：q  👏再见！

或使用 Ctrl+C（Mac 上是 Cmd+C）

👤 你：^C   🙏 检测到中断，退出程序

---

常见问题排查

❌ 问题1：ModuleNotFoundError

错误信息：

ModuleNotFoundError: No module named 'openai'

解决方法：

pip3 install -r requirements.txt

---

❌ 问题2：API Key 错误

错误信息：

Error code: 401 - Unauthorized

解决方法：

1. 检查 .env 文件中的 API_KEY 是否正确
2. 确认没有多余空格或引号
3. 重启脚本

---

❌ 问题3：余额不足

错误信息：

Error code: 402 - Insufficient Balance

解决方法：

1. 充值 DeepSeek 账户
2. 或切换到其他 API（如 Ollama 本地模型）

---

❌ 问题4：搜索失败

错误信息：

搜索失败: Invalid API Key

解决方法：

1. 在 .env 文件中配置 SERPAPI_API_KEY
2. 访问 SerpAPI 官网注册获取免费 Key

---

❌ 问题5：无法退出

现象： 输入 q 后程序不退出

解决方法：

1. 检查代码中是否有 break 语句
2. 确保保存了文件并重启脚本
3. 使用 Ctrl+C 强制退出

---

总结与进阶

🎯 我们实现了什么？

1. ✅ 统一的大模型适配层 - 轻松切换不同厂商
2. ✅ 对话记忆系统 - 实现多轮对话
3. ✅ 工具注册和执行 - 让 Agent 能"做事"
4. ✅ 消息标准化 - 确保通信规范
5. ✅ ReAct 循环 - 推理+行动的智能决策

🚀 可以继续扩展的方向

1. 添加更多工具

@registry.registerdef get_weather(city: str):    """获取天气信息"""    pass@registry.registerdef calculate(expression: str):    """计算数学表达式"""    pass

2. 记忆优化

• 实现记忆窗口（限制历史长度）
• 重要信息提取和总结
• 长期记忆存储（数据库）

3. 任务规划

• 分解复杂任务
• 多步骤执行
• 目标导向

4. 流式输出

• 实时显示 LLM 回复
• 提升用户体验

5. 多模态能力

• 图像处理
• 语音交互
• 文件操作

---

🎉 恭喜你！

如果你跟着这篇教程一步步完成了所有步骤，恭喜你已经成功构建了自己的第一个 AI Agent 框架！

这是一个简单但完整的实现，涵盖了 Agent 的核心概念。你可以基于这个框架继续探索和扩展，构建更复杂的智能应用。

有什么问题或想法？欢迎继续交流！😊

想入门 AI 大模型却找不到清晰方向？备考大厂 AI 岗还在四处搜集零散资料？别再浪费时间啦！2026 年 AI 大模型全套学习资料已整理完毕，从学习路线到面试真题，从工具教程到行业报告，一站式覆盖你的所有需求，现在全部免费分享！

👇👇扫码免费领取全部内容👇👇

​

一、学习必备：100+本大模型电子书+26 份行业报告 + 600+ 套技术PPT，帮你看透 AI 趋势

想了解大模型的行业动态、商业落地案例？大模型电子书？这份资料帮你站在 “行业高度” 学 AI：

1. 100+本大模型方向电子书

2. 26 份行业研究报告：覆盖多领域实践与趋势

报告包含阿里、DeepSeek 等权威机构发布的核心内容，涵盖：

• 职业趋势：《AI + 职业趋势报告》《中国 AI 人才粮仓模型解析》；
• 商业落地：《生成式 AI 商业落地白皮书》《AI Agent 应用落地技术白皮书》；
• 领域细分：《AGI 在金融领域的应用报告》《AI GC 实践案例集》；
• 行业监测：《2024 年中国大模型季度监测报告》《2025 年中国技术市场发展趋势》。

3. 600+套技术大会 PPT：听行业大咖讲实战

PPT 整理自 2024-2025 年热门技术大会，包含百度、腾讯、字节等企业的一线实践：

• 安全方向：《端侧大模型的安全建设》《大模型驱动安全升级（腾讯代码安全实践）》；
• 产品与创新：《大模型产品如何创新与创收》《AI 时代的新范式：构建 AI 产品》；
• 多模态与 Agent：《Step-Video 开源模型（视频生成进展）》《Agentic RAG 的现在与未来》；
• 工程落地：《从原型到生产：AgentOps 加速字节 AI 应用落地》《智能代码助手 CodeFuse 的架构设计》。

二、求职必看：大厂 AI 岗面试 “弹药库”，300 + 真题 + 107 道面经直接抱走

想冲字节、腾讯、阿里、蔚来等大厂 AI 岗？这份面试资料帮你提前 “押题”，拒绝临场慌！

1. 107 道大厂面经：覆盖 Prompt、RAG、大模型应用工程师等热门岗位

面经整理自 2021-2025 年真实面试场景，包含 TPlink、字节、腾讯、蔚来、虾皮、中兴、科大讯飞、京东等企业的高频考题，每道题都附带思路解析：

2. 102 道 AI 大模型真题：直击大模型核心考点

针对大模型专属考题，从概念到实践全面覆盖，帮你理清底层逻辑：

3. 97 道 LLMs 真题：聚焦大型语言模型高频问题

专门拆解 LLMs 的核心痛点与解决方案，比如让很多人头疼的 “复读机问题”：

三、路线必明： AI 大模型学习路线图，1 张图理清核心内容

刚接触 AI 大模型，不知道该从哪学起？这份「AI大模型 学习路线图」直接帮你划重点，不用再盲目摸索！

路线图涵盖 5 大核心板块，从基础到进阶层层递进：一步步带你从入门到进阶，从理论到实战。

L1阶段:启航篇丨极速破界AI新时代

L1阶段：了解大模型的基础知识，以及大模型在各个行业的应用和分析，学习理解大模型的核心原理、关键技术以及大模型应用场景。

L2阶段：攻坚篇丨RAG开发实战工坊

L2阶段：AI大模型RAG应用开发工程，主要学习RAG检索增强生成：包括Naive RAG、Advanced-RAG以及RAG性能评估，还有GraphRAG在内的多个RAG热门项目的分析。

L3阶段：跃迁篇丨Agent智能体架构设计

L3阶段：大模型Agent应用架构进阶实现，主要学习LangChain、 LIamaIndex框架，也会学习到AutoGPT、 MetaGPT等多Agent系统，打造Agent智能体。

L4阶段：精进篇丨模型微调与私有化部署

L4阶段：大模型的微调和私有化部署，更加深入的探讨Transformer架构，学习大模型的微调技术，利用DeepSpeed、Lamam Factory等工具快速进行模型微调，并通过Ollama、vLLM等推理部署框架，实现模型的快速部署。

L5阶段：专题集丨特训篇 【录播课】

四、资料领取：全套内容免费抱走，学 AI 不用再找第二份

不管你是 0 基础想入门 AI 大模型，还是有基础想冲刺大厂、了解行业趋势，这份资料都能满足你！
现在只需按照提示操作，就能免费领取：

👇👇扫码免费领取全部内容👇👇

​

2026 年想抓住 AI 大模型的风口？别犹豫，这份免费资料就是你的 “起跑线”！