这类教程最值得先看的不是它列了多少功能而是能不能让你在本地环境里把从零到一的流程真正跑通。很多人学完一堆概念卡在环境、依赖或者第一个可运行的例子上最后只能放弃。所以这篇内容会围绕一个核心目标用最少的理论带你从零搭建一个能实际响应、能执行简单任务的 Python AI Agent并理解每一步为什么这么做以及出问题时该往哪里看。它适合两类人一是想从传统 Python 开发转向 AI 应用开发的工程师二是对 AI Agent 感兴趣但被各种框架和概念搞晕想亲手做一个最小原型来理解全貌的学习者。最关键的价值在于你会得到一个可复现的、模块清晰的代码骨架而不是一堆散乱的知识点。这个骨架能帮你理解智能体的核心循环感知理解输入、决策规划任务、执行调用工具、学习更新记忆并知道如何扩展它。下面我们就按实际落地的顺序从环境准备到第一个能对话的智能体再到给它增加工具能力最后聊聊生产化需要考虑的边界问题。1. 环境与工具链别在第一步就卡住很多人教程看了一大堆代码复制下来却跑不起来问题往往出在环境上。对于 AI Agent 开发环境不仅仅是 Python 解释器还包括大模型访问权限、必要的库以及一个趁手的代码编辑器。1.1 核心三件套Python、包管理器和 IDE首先你需要一个 Python 环境。我建议直接使用Python 3.10 或 3.11。这两个版本是目前大多数 AI 库兼容性最好的太老的版本如 3.7可能缺少新特性太新的版本如 3.12可能有些库还没适配好。安装与验证去 Python 官网下载安装包安装时务必勾选 “Add Python to PATH”。安装后打开终端Windows 用 CMD 或 PowerShellMac/Linux 用 Terminal输入python --version确认输出是Python 3.10.x或Python 3.11.x。如果显示Python 2.x说明系统里有老版本可能需要使用python3命令。为了避免混淆后续我们都假设命令是python。接下来是包管理器。Python 自带的pip是基础但我强烈建议你使用虚拟环境。这能把你项目的依赖和系统全局的 Python 包隔离开避免版本冲突。创建虚拟环境很简单# 在当前目录下创建名为 venv 的虚拟环境 python -m venv venv然后激活它Windows:venv\Scripts\activateMac/Linux:source venv/bin/activate激活后你的命令行提示符前通常会显示(venv)表示你正在这个独立环境中工作。对于 IDEVSCode是首选因为它轻量、插件生态丰富。安装后务必安装 Python 扩展由 Microsoft 发布。打开 VSCode按CtrlShiftP输入 “Python: Select Interpreter”然后选择你刚创建的虚拟环境路径下的python.exeWindows或pythonMac/Linux。这样VSCode 就会使用虚拟环境来运行和调试代码。1.2 大模型访问钥匙从哪里来AI Agent 的核心是“大脑”也就是大语言模型LLM。你不能在本地凭空变出一个 GPT-4所以需要获取一个 API 密钥。目前国内开发者常用的有智谱 AIChatGLM提供免费额度适合学习和测试。百度文心一言有公开 API。阿里通义千问同样提供 API 服务。月之暗面Kimi等。这里以智谱 AI为例因为它对新手比较友好。去其开放平台官网注册账号通常能在“控制台”或“个人中心”找到“创建 API Key”的选项。创建后你会得到一串类似sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx的密钥。请妥善保管不要提交到代码仓库。为什么强调这个因为你的第一个 Agent 很可能因为 API Key 配置错误而“失聪”。常见的错误包括没设置环境变量、Key 拼写错误、或者 Key 对应的服务未开通。1.3 基础依赖库安装与版本锁定在激活的虚拟环境中我们安装最核心的几个库。创建一个requirements.txt文件不是必须的但对于可复现性至关重要。# 在项目根目录下执行 pip install openai注意这里安装的openai库是一个通用客户端它可以通过配置base_url和api_key来兼容众多提供了 OpenAI 兼容接口的国产大模型包括智谱、DeepSeek等这比每个模型都学一套 SDK 要方便得多。pip install langchainlangchain是一个流行的框架它把和大模型交互、管理对话历史、调用工具等常见模式封装成了组件。对于初学者用它能快速搭建原型理解 Agent 的工作流。但注意不要被它的抽象层吓到我们初期只使用最核心的几块。pip install python-dotenv这个库用于从.env文件加载环境变量比如你的 API Key避免硬编码在代码里。安装完成后可以用pip list查看已安装的包和版本。我建议把当前环境冻结成一个清单pip freeze requirements.txt这样别人或你自己在其他机器上重建环境时只需pip install -r requirements.txt即可能最大程度避免“在我机器上是好的”这类问题。2. 从零搭建第一个会对话的智能体现在我们开始写代码。目标不是造一个万能 Agent而是先实现一个能理解你的问题并用大模型生成回复的“对话机器人”。这是所有智能体的基础。2.1 项目结构与配置管理在项目根目录下创建如下结构my_ai_agent/ ├── .env # 存放敏感配置API Key ├── .gitignore # 忽略 .env 和 __pycache__ 等 ├── requirements.txt # 依赖列表 ├── config.py # 读取配置的模块 ├── simple_agent.py # 第一个简单智能体 └── tools/ # 后续放自定义工具首先在.gitignore文件里加入.env __pycache__/ *.pyc venv/这能防止你把密钥和缓存文件提交到 Git。然后在.env文件中写入你的 API Key 和模型端点# .env 文件内容 ZHIPU_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ZHIPU_API_BASEhttps://open.bigmodel.cn/api/paas/v4/ # 以智谱为例 MODEL_NAMEglm-4-flash # 选择一个轻量模型响应快成本低这里用glm-4-flash是因为它速度快、成本低适合用来做大量的调试和迭代。等核心逻辑跑通后可以换更强大的模型。接着创建config.py来安全地读取配置# config.py import os from dotenv import load_dotenv # 加载 .env 文件中的变量 load_dotenv() class Config: 配置类集中管理所有环境变量和常量 API_KEY os.getenv(ZHIPU_API_KEY) API_BASE os.getenv(ZHIPU_API_BASE) MODEL_NAME os.getenv(MODEL_NAME, glm-4-flash) # 默认值 classmethod def validate(cls): 验证必要配置是否存在 if not cls.API_KEY: raise ValueError(请在 .env 文件中设置 ZHIPU_API_KEY) # API_BASE 如果没有某些库会使用默认的 OpenAI 端点这里我们要求明确指定 if not cls.API_BASE: raise ValueError(请在 .env 文件中设置 ZHIPU_API_BASE (例如智谱的端点)) print(配置加载成功。)这种集中管理的方式比在代码里到处写os.getenv要清晰和安全得多。2.2 实现最简单的对话循环现在创建simple_agent.py。我们将使用langchain的ChatOpenAI来封装对大模型的调用因为它处理了对话格式和流式输出等细节。# simple_agent.py from langchain_openai import ChatOpenAI from langchain.schema import HumanMessage, SystemMessage from config import Config def initialize_agent(): 初始化与大模型对话的客户端 Config.validate() # 先验证配置 llm ChatOpenAI( openai_api_keyConfig.API_KEY, openai_api_baseConfig.API_BASE, model_nameConfig.MODEL_NAME, temperature0.1, # 控制创造性越低越稳定和确定 streamingFalse, # 初次调试先关闭流式输出更完整 ) return llm def run_conversation(): 运行一个简单的对话循环 print(初始化智能体...) agent initialize_agent() # 系统提示词定义智能体的角色和行为 system_prompt SystemMessage(content你是一个乐于助人的AI助手。请用中文清晰、简洁地回答用户的问题。) print(\n智能体已就绪。输入 退出 或 quit 结束对话。) conversation_history [system_prompt] while True: try: user_input input(\n你: ) if user_input.lower() in [退出, quit, exit]: print(对话结束。) break # 将用户输入加入历史 conversation_history.append(HumanMessage(contentuser_input)) # 调用大模型生成回复 print(智能体思考中...) response agent.invoke(conversation_history) # 提取回复内容 ai_reply response.content print(f智能体: {ai_reply}) # 将AI回复也加入历史实现多轮对话记忆 conversation_history.append(response) except KeyboardInterrupt: print(\n用户中断。) break except Exception as e: print(f\n调用模型时出错: {e}) # 可以选择从历史中移除出错的上轮用户输入避免污染 if conversation_history and isinstance(conversation_history[-1], HumanMessage): conversation_history.pop() print(请检查网络连接和API配置或稍后重试。) if __name__ __main__: run_conversation()关键点解释ChatOpenAI虽然名字叫“OpenAI”但通过openai_api_base参数我们可以指向任何兼容 OpenAI 接口的服务器包括智谱、DeepSeek等。SystemMessage这是给模型的“幕后指令”用于设定其身份、回答风格和边界。好的系统提示词是智能体行为稳定的关键。temperature设置为较低的 0.1是为了在开发阶段让模型的输出更确定、可复现便于调试。上线或需要创造性时可以调高。对话历史 (conversation_history)我们把所有消息系统、用户、AI都保存在一个列表里每次提问都把这个完整的历史传给模型。这就是实现多轮对话记忆的最简单方式。错误处理网络超时、API限额、模型服务异常都可能发生。用try-except包裹调用过程并给出明确提示是生产级代码的基本素养。运行与验证在终端中确保虚拟环境已激活然后运行python simple_agent.py如果一切正常你会看到“初始化智能体...配置加载成功。”然后进入对话循环。问它“你好”或“你能做什么”它应该能用中文回复。如果出错了按这个顺序排查API Key 和 Base URL确认.env文件内容正确且config.py能正确读取。可以在config.py最后加print(Config.API_KEY)测试。网络连接尝试用curl或浏览器访问你的API_BASE看是否通。依赖版本确认openai,langchain-openai等库已正确安装。有时需要指定版本如pip install openai1.12.0。模型名称确认MODEL_NAME在你的 API 服务商那里是有效的模型标识符。3. 赋予智能体“手脚”工具调用与任务规划一个只会聊天的 Agent 是“残疾”的。真正的智能体应该能根据你的指令去调用外部工具完成任务比如查天气、算数学、读写文件。这就是Tool Calling和Task Planning的核心。3.1 创建你的第一个工具我们在tools/目录下创建一个calculator.py实现一个简单的计算器工具。# tools/calculator.py from typing import Union from pydantic import BaseModel, Field class CalculatorInput(BaseModel): 计算器工具的输入参数模式 a: Union[int, float] Field(description第一个数字) b: Union[int, float] Field(description第二个数字) operation: str Field(description运算类型可选add加, subtract减, multiply乘, divide除) def calculator_tool(a: int | float, b: int | float, operation: str) - str: 一个简单的计算器工具。 执行基本的算术运算。 try: if operation add: result a b elif operation subtract: result a - b elif operation multiply: result a * b elif operation divide: if b 0: return 错误除数不能为零。 result a / b else: return f错误不支持的操作 {operation}。支持的操作add, subtract, multiply, divide. return f计算结果{a} {operation} {b} {result} except Exception as e: return f计算过程中发生错误{e} # 为了被 LangChain 识别我们需要将函数和其输入模式包装起来 # 注意在较新的 LangChain 版本中推荐使用 tool 装饰器但为了清晰理解原理我们先手动创建这里有几个关键设计pydantic模型CalculatorInput类用pydantic定义了工具需要的参数及其类型、描述。这能让大模型更准确地理解如何调用这个工具。清晰的函数文档calculator_tool的文档字符串内的内容非常重要。大模型会阅读它来理解工具的功能。健壮的错误处理工具内部处理了除零错误和非法操作返回明确的错误信息而不是抛出异常导致整个 Agent 崩溃。3.2 使用 LangChain 构建可调用工具的智能体现在我们升级simple_agent.py创建一个新的文件agent_with_tools.py。# agent_with_tools.py from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain.tools import Tool from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.memory import ConversationBufferMemory from tools.calculator import calculator_tool, CalculatorInput from config import Config def create_agent(): 创建并返回一个具备工具调用能力的智能体执行器 Config.validate() # 1. 初始化LLM llm ChatOpenAI( openai_api_keyConfig.API_KEY, openai_api_baseConfig.API_BASE, model_nameConfig.MODEL_NAME, temperature0.1, streamingFalse, ) # 2. 将我们的计算器函数包装成 LangChain Tool 对象 calculator_tool_wrapped Tool.from_function( funccalculator_tool, nameCalculator, description用于执行加、减、乘、除运算。输入两个数字和操作类型。, args_schemaCalculatorInput, # 关联我们定义的Pydantic模型 return_directFalse, # 设为True则工具结果直接作为最终答案否则会经过LLM整理 ) # 3. 定义工具列表未来可以在这里添加更多工具 tools [calculator_tool_wrapped] # 4. 构建提示词模板 prompt ChatPromptTemplate.from_messages([ (system, 你是一个强大的AI助手可以调用工具来帮助用户解决问题。如果你需要计算请使用计算器工具。请用中文回答。), MessagesPlaceholder(variable_namechat_history), # 预留位置存放对话历史 (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), # 预留位置存放Agent的思考过程 ]) # 5. 初始化记忆用于多轮对话 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 6. 创建Agent agent create_openai_tools_agent(llmllm, toolstools, promptprompt) # 7. 创建Agent执行器它负责运行Agent并管理工具调用循环 agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, # 设为True会打印详细的思考过程调试时非常有用 handle_parsing_errorsTrue, # 处理模型输出解析错误 max_iterations5, # 限制最大迭代次数防止陷入死循环 ) return agent_executor def run_agent_with_tools(): 运行具备工具调用能力的智能体 print(正在初始化具备工具调用能力的智能体...) agent create_agent() print(智能体已就绪。输入‘退出’结束对话。\n) while True: try: user_input input(你: ) if user_input.lower() in [退出, quit, exit]: print(对话结束。) break # 调用执行器 response agent.invoke({input: user_input}) print(f\n智能体: {response[output]}\n) except KeyboardInterrupt: print(\n用户中断。) break except Exception as e: print(f\n发生错误: {e}) # 详细日志有助于调试 import traceback traceback.print_exc() if __name__ __main__: run_agent_with_tools()核心机制解析Tool对象Tool.from_function将我们的 Python 函数calculator_tool包装成 LangChain 能识别的工具并附上名称、描述和参数模式。大模型正是通过这些元数据来“知道”有这个工具以及如何调用它。AgentExecutor这是 LangChain 提供的“发动机”。它接收用户输入交给agent由LLM和提示词构成去思考agent可能会决定调用某个工具AgentExecutor就负责执行工具调用把结果返回给agent继续思考直到agent认为可以给出最终答案或者达到max_iterations限制。这个过程称为ReAct (Reasoning Acting)循环。verboseTrue这是调试神器。设为True后控制台会打印出 Agent 的完整思考链比如“我在想用户需要计算我应该调用 Calculator 工具参数是...”。通过这个输出你能清晰看到智能体是如何做决策的。max_iterations必须设置。防止智能体陷入“调用工具A - 分析结果 - 又调用工具A”的死循环。运行与测试运行python agent_with_tools.py。当verboseTrue时你会看到大量日志。试着问“123乘以456等于多少”。 观察控制台你应该能看到类似这样的日志 Entering new AgentExecutor chain... 思考用户问的是一个乘法计算问题。我需要使用计算器工具。 Action: Calculator Action Input: {a: 123, b: 456, operation: multiply} Observation: 计算结果123 multiply 456 56088 思考我得到了计算结果可以回答用户了。 Final Answer: 123乘以456等于56088。 Finished chain. 智能体: 123乘以456等于56088。这表明你的智能体成功理解了任务选择了正确的工具传入了正确的参数并给出了最终答案。恭喜你已经创建了一个具备基础工具调用能力的 AI Agent4. 从原型到生产架构扩展与避坑指南一个能在控制台对话的 Agent 只是起点。要让它真正有用我们需要考虑更复杂的场景处理长文本、管理复杂状态、接入真实API、以及部署成服务。同时开发过程中有很多“坑”需要提前避开。4.1 设计可扩展的智能体架构上面的例子把逻辑都写在一个文件里随着工具增多会变得混乱。一个更清晰的生产级架构可以这样组织my_ai_agent/ ├── core/ │ ├── __init__.py │ ├── config.py # 配置管理 │ ├── llm_client.py # LLM客户端封装支持不同厂商、模型切换 │ └── memory_manager.py # 记忆管理支持长上下文、向量存储 ├── tools/ │ ├── __init__.py │ ├── base_tool.py # 自定义工具基类 │ ├── calculator.py │ ├── web_search.py # 网络搜索工具示例 │ └── file_reader.py # 文件读取工具示例 ├── agents/ │ ├── __init__.py │ ├── base_agent.py # Agent基类 │ ├── chat_agent.py # 纯对话Agent │ └── tool_agent.py # 工具调用Agent ├── chains/ # 复杂任务链可选 ├── utils/ # 通用工具函数 ├── tests/ # 单元测试 ├── main.py # 应用入口CLI或Web服务 └── requirements.txt关键模块职责core/llm_client.py封装不同 LLM 供应商的调用细节。通过配置驱动可以轻松在智谱、OpenAI、本地模型之间切换。core/memory_manager.py当对话历史很长时全部传给模型会消耗大量 Token且可能超出上下文长度限制。这里需要实现记忆摘要、向量检索或分窗等策略只把最相关的历史片段传给模型。tools/base_tool.py定义一个所有工具都继承的基类统一工具注册、参数验证和错误处理逻辑。agents/base_agent.py定义 Agent 的通用接口如invoke,reset方便管理和测试。4.2 接入真实世界工具以搜索为例让我们在tools/下添加一个更实用的工具网络搜索。这里我们使用一个假设的搜索 API例如 SerpAPI 或 Tavily国内可用 Bing Search API 等。注意以下代码需要你替换为真实的 API 密钥和端点。# tools/web_search.py import requests from typing import Optional from pydantic import BaseModel, Field import json class WebSearchInput(BaseModel): query: str Field(description搜索查询词) num_results: Optional[int] Field(default5, description返回的结果数量默认5条) def web_search_tool(query: str, num_results: int 5) - str: 使用搜索引擎在网络上搜索信息。 返回搜索结果的摘要列表。 # 重要此处需要替换为真实的搜索API配置 api_key YOUR_SEARCH_API_KEY search_url https://api.example.com/search/v1 # 示例URL headers {Authorization: fBearer {api_key}} params {q: query, num: num_results} try: response requests.get(search_url, headersheaders, paramsparams, timeout10) response.raise_for_status() # 检查HTTP错误 data response.json() # 假设API返回格式为 {results: [{title: ..., snippet: ...}, ...]} results data.get(results, []) if not results: return 未找到相关结果。 summary [] for i, item in enumerate(results[:num_results], 1): title item.get(title, 无标题) snippet item.get(snippet, 无摘要) summary.append(f{i}. {title}: {snippet[:150]}...) # 截断长摘要 return 搜索到以下信息\n \n.join(summary) except requests.exceptions.Timeout: return 搜索请求超时请检查网络或稍后重试。 except requests.exceptions.RequestException as e: return f搜索请求失败: {e} except (KeyError, json.JSONDecodeError) as e: return f解析搜索结果时出错: {e}将这个工具像计算器一样注册到你的agent_with_tools.py的tools列表中你的智能体就具备了“上网”能力。你可以问它“今天北京天气怎么样” 它会尝试调用搜索工具来获取信息。4.3 开发与部署中的关键“坑点”成本控制大模型 API 调用是按 Token 收费的。长对话、复杂思考链verbose模式会消耗更多 Token都会增加成本。开发阶段使用便宜的模型如glm-4-flash。控制max_tokens参数限制单次回复长度。为你的 API 密钥设置用量告警和预算。速率限制与超时所有 API 都有调用频率限制Rate Limit。你的代码必须有重试机制和退避策略如指数退避。# 简单的带重试的调用示例 from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def safe_llm_invoke(llm, messages): return llm.invoke(messages)上下文长度限制模型能处理的文本长度有限如 8K, 32K, 128K Tokens。长文档处理或超长对话时需要使用memory管理定期总结或丢弃旧对话。对于长文档使用 RAG检索增强生成技术只检索相关片段传入上下文。工具调用的可靠性大模型可能生成错误的工具调用参数类型不对、字段缺失。除了使用Pydantic做验证还应该在工具函数内部进行防御性编程并让 Agent 有能力在工具调用失败后尝试修正或向用户澄清。安全与隐私API Key永远不要硬编码或提交到代码仓库。使用.env文件和环境变量。用户数据如果 Agent 能读取文件或访问数据库必须严格控制权限并对输入进行过滤防止路径遍历../或 SQL 注入。工具权限删除文件、执行系统命令等危险工具在开发环境可以测试但生产环境必须极度谨慎或完全禁止。测试与评估不要只靠手动聊天测试。为你的 Agent 核心功能编写单元测试和集成测试。单元测试测试单个工具函数在不同输入下的输出。集成测试模拟用户对话流验证 Agent 能否正确完成端到端任务如“计算一下(1234)*2 是多少”。使用pytest等框架并将测试加入 CI/CD 流程。4.4 部署为服务FastAPI 示例最终你可能需要将 Agent 部署成 Web API 供其他应用调用。使用 FastAPI 可以快速实现。# main.py (FastAPI 版本) from fastapi import FastAPI, HTTPException from pydantic import BaseModel from agent_with_tools import create_agent # 导入我们之前构建的agent import uvicorn app FastAPI(titleMy AI Agent API) # 在应用启动时初始化Agent避免每次请求都初始化 agent_executor None app.on_event(startup) async def startup_event(): global agent_executor print(正在初始化AI Agent...) agent_executor create_agent() print(AI Agent 初始化完成。) class ChatRequest(BaseModel): message: str session_id: str None # 用于区分不同会话 class ChatResponse(BaseModel): reply: str session_id: str app.post(/chat, response_modelChatResponse) async def chat_endpoint(request: ChatRequest): if agent_executor is None: raise HTTPException(status_code503, detailAgent未就绪) try: # 这里可以基于session_id从数据库或缓存中读取/保存对话历史 # 简化起见我们每次请求都是独立的 result agent_executor.invoke({input: request.message}) return ChatResponse(replyresult[output], session_idrequest.session_id or default) except Exception as e: raise HTTPException(status_code500, detailf处理请求时出错: {str(e)}) if __name__ __main__: # 运行服务: uvicorn main:app --reload --host 0.0.0.0 --port 8000 uvicorn.run(app, host0.0.0.0, port8000)运行后你就可以通过http://localhost:8000/docs访问自动生成的 API 文档并通过POST /chat接口与你的智能体交互了。5. 学习路线与面试准备下一步该学什么如果你跟着做到了这里已经掌握了 AI Agent 开发的核心闭环。但要达到“跳槽”或独立开发复杂 Agent 的水平还需要系统性地补全以下知识栈。5.1 技术栈深化框架精通LangChain/LlamaIndex深入理解其Chains,Agents,Retrievers,Memory等核心概念。学习如何自定义Agent和Tool。其他框架了解AutoGen,CrewAI等多智能体框架以及Semantic Kernel(微软) 等。提示词工程学习编写有效的System Prompt来精确控制 Agent 行为。掌握Few-Shot少样本提示在提示词中提供例子来引导模型。了解Chain-of-Thought思维链提示让模型展示推理过程。记忆与检索向量数据库学习使用Chroma,Pinecone,Weaviate或Milvus存储和检索文本嵌入Embeddings这是实现 RAG 的基础。记忆策略实现对话摘要、基于向量检索的关键记忆提取等。评估与监控学习如何设计评估指标忠实度、相关性、有用性来量化 Agent 表现。使用LangSmithLangChain 官方平台或自定义日志来追踪每次调用链分析性能瓶颈和错误。工程化与部署异步处理使用asyncio处理并发请求提高吞吐量。队列与缓存对于耗时任务引入CeleryRedis等消息队列。使用缓存如Redis存储频繁访问的模型响应或工具结果。容器化使用Docker打包你的 Agent 应用及其所有依赖。云部署了解如何在AWS,GCP,Azure或国内云服务器上部署和扩缩容你的服务。5.2 应对 Agent 开发面试题面试官不仅会问你会用什么更会问你怎么设计、怎么解决问题。以下是一些典型问题及回答思路Q: 请描述一下你设计的一个 AI Agent 系统架构。A:从用户请求入口API/Web讲起提到负载均衡、API网关。然后到核心的Orchestrator协调器它负责解析请求管理对话状态Memory调用LLM进行规划。LLM决策后可能调用Tool Layer工具层包括计算、搜索、数据库查询等。工具结果返回给Orchestrator再决定是继续思考还是返回最终答案。最后要提到监控、日志和评估模块。Q: 如何保证工具调用的安全性和稳定性A:安全性1) 工具权限分级危险操作如删文件需额外授权或禁止。2) 对用户输入和工具参数做严格的验证和清洗防注入。3) API Key 等机密信息通过环境变量或密钥管理服务获取。稳定性1) 为每个工具和 LLM 调用设置超时和重试机制。2) 实现熔断和降级当某个工具或模型持续失败时暂时屏蔽或提供备选方案。3) 全面的错误处理和日志记录便于快速定位问题。Q: 如何处理超出模型上下文长度的长文档A:采用 RAG 模式。1) 将长文档切分成有重叠的片段Chunking。2) 使用嵌入模型Embedding Model将每个片段转换为向量。3) 将向量存入向量数据库。4) 当用户提问时将问题也转换为向量在向量数据库中检索出最相关的几个片段。5) 只将这些相关片段和问题一起传给 LLM 生成答案。这样就避免了上下文长度限制。Q: 如何评估你的 Agent 表现好坏A:分几个层面1)功能性能否正确完成任务通过人工评估或自动化测试集。2)效率响应延迟、Token 消耗成本。3)用户体验回答的流畅性、相关性、有用性可通过用户反馈或评分收集。4)稳定性服务的可用性、错误率。我们会建立一套混合的评估体系结合自动化测试和人工抽查。5.3 项目进阶从 Demo 到作品集把上面这个简单的计算器搜索 Agent 扩展成以下任何一个项目都能成为你简历上的亮点个人知识库助手接入向量数据库上传你的 PDF、Word 文档让 Agent 基于你的私人资料回答问题。自动化数据分析助手集成pandas、matplotlib等工具让用户用自然语言描述Agent 自动执行数据清洗、分析和可视化。多智能体协作系统使用CrewAI或AutoGen创建多个具有不同角色研究员、写手、评审员的 Agent协作完成一份市场调研报告。与外部系统集成将 Agent 接入 Slack、钉钉、微信公众号成为一个聊天机器人或者接入 Zapier/Make根据邮件、日历事件自动触发任务。最后也是最关键的一点AI Agent 领域变化极快新的模型、框架、论文层出不穷。保持学习的唯一方法就是动手。把你学到的每一个新概念都立刻用代码实现一个最小可行原型。遇到报错就去读文档、查 Issue、看源码。这个从“跑通”到“理解”再到“优化”的过程才是构建你完整 Agent 开发体系最扎实的路径。 
长河君 · 2026/8/16 9:54:23 · 阅读 1.2k 从零搭建Python AI Agent：环境配置、工具调用与生产部署实战
这类教程最值得先看的不是它列了多少功能而是能不能让你在本地环境里把从零到一的流程真正跑通。很多人学完一堆概念卡在环境、依赖或者第一个可运行的例子上最后只能放弃。所以这篇内容会围绕一个核心目标用最少的理论带你从零搭建一个能实际响应、能执行简单任务的 Python AI Agent并理解每一步为什么这么做以及出问题时该往哪里看。它适合两类人一是想从传统 Python 开发转向 AI 应用开发的工程师二是对 AI Agent 感兴趣但被各种框架和概念搞晕想亲手做一个最小原型来理解全貌的学习者。最关键的价值在于你会得到一个可复现的、模块清晰的代码骨架而不是一堆散乱的知识点。这个骨架能帮你理解智能体的核心循环感知理解输入、决策规划任务、执行调用工具、学习更新记忆并知道如何扩展它。下面我们就按实际落地的顺序从环境准备到第一个能对话的智能体再到给它增加工具能力最后聊聊生产化需要考虑的边界问题。1. 环境与工具链别在第一步就卡住很多人教程看了一大堆代码复制下来却跑不起来问题往往出在环境上。对于 AI Agent 开发环境不仅仅是 Python 解释器还包括大模型访问权限、必要的库以及一个趁手的代码编辑器。1.1 核心三件套Python、包管理器和 IDE首先你需要一个 Python 环境。我建议直接使用Python 3.10 或 3.11。这两个版本是目前大多数 AI 库兼容性最好的太老的版本如 3.7可能缺少新特性太新的版本如 3.12可能有些库还没适配好。安装与验证去 Python 官网下载安装包安装时务必勾选 “Add Python to PATH”。安装后打开终端Windows 用 CMD 或 PowerShellMac/Linux 用 Terminal输入python --version确认输出是Python 3.10.x或Python 3.11.x。如果显示Python 2.x说明系统里有老版本可能需要使用python3命令。为了避免混淆后续我们都假设命令是python。接下来是包管理器。Python 自带的pip是基础但我强烈建议你使用虚拟环境。这能把你项目的依赖和系统全局的 Python 包隔离开避免版本冲突。创建虚拟环境很简单# 在当前目录下创建名为 venv 的虚拟环境 python -m venv venv然后激活它Windows:venv\Scripts\activateMac/Linux:source venv/bin/activate激活后你的命令行提示符前通常会显示(venv)表示你正在这个独立环境中工作。对于 IDEVSCode是首选因为它轻量、插件生态丰富。安装后务必安装 Python 扩展由 Microsoft 发布。打开 VSCode按CtrlShiftP输入 “Python: Select Interpreter”然后选择你刚创建的虚拟环境路径下的python.exeWindows或pythonMac/Linux。这样VSCode 就会使用虚拟环境来运行和调试代码。1.2 大模型访问钥匙从哪里来AI Agent 的核心是“大脑”也就是大语言模型LLM。你不能在本地凭空变出一个 GPT-4所以需要获取一个 API 密钥。目前国内开发者常用的有智谱 AIChatGLM提供免费额度适合学习和测试。百度文心一言有公开 API。阿里通义千问同样提供 API 服务。月之暗面Kimi等。这里以智谱 AI为例因为它对新手比较友好。去其开放平台官网注册账号通常能在“控制台”或“个人中心”找到“创建 API Key”的选项。创建后你会得到一串类似sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx的密钥。请妥善保管不要提交到代码仓库。为什么强调这个因为你的第一个 Agent 很可能因为 API Key 配置错误而“失聪”。常见的错误包括没设置环境变量、Key 拼写错误、或者 Key 对应的服务未开通。1.3 基础依赖库安装与版本锁定在激活的虚拟环境中我们安装最核心的几个库。创建一个requirements.txt文件不是必须的但对于可复现性至关重要。# 在项目根目录下执行 pip install openai注意这里安装的openai库是一个通用客户端它可以通过配置base_url和api_key来兼容众多提供了 OpenAI 兼容接口的国产大模型包括智谱、DeepSeek等这比每个模型都学一套 SDK 要方便得多。pip install langchainlangchain是一个流行的框架它把和大模型交互、管理对话历史、调用工具等常见模式封装成了组件。对于初学者用它能快速搭建原型理解 Agent 的工作流。但注意不要被它的抽象层吓到我们初期只使用最核心的几块。pip install python-dotenv这个库用于从.env文件加载环境变量比如你的 API Key避免硬编码在代码里。安装完成后可以用pip list查看已安装的包和版本。我建议把当前环境冻结成一个清单pip freeze requirements.txt这样别人或你自己在其他机器上重建环境时只需pip install -r requirements.txt即可能最大程度避免“在我机器上是好的”这类问题。2. 从零搭建第一个会对话的智能体现在我们开始写代码。目标不是造一个万能 Agent而是先实现一个能理解你的问题并用大模型生成回复的“对话机器人”。这是所有智能体的基础。2.1 项目结构与配置管理在项目根目录下创建如下结构my_ai_agent/ ├── .env # 存放敏感配置API Key ├── .gitignore # 忽略 .env 和 __pycache__ 等 ├── requirements.txt # 依赖列表 ├── config.py # 读取配置的模块 ├── simple_agent.py # 第一个简单智能体 └── tools/ # 后续放自定义工具首先在.gitignore文件里加入.env __pycache__/ *.pyc venv/这能防止你把密钥和缓存文件提交到 Git。然后在.env文件中写入你的 API Key 和模型端点# .env 文件内容 ZHIPU_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ZHIPU_API_BASEhttps://open.bigmodel.cn/api/paas/v4/ # 以智谱为例 MODEL_NAMEglm-4-flash # 选择一个轻量模型响应快成本低这里用glm-4-flash是因为它速度快、成本低适合用来做大量的调试和迭代。等核心逻辑跑通后可以换更强大的模型。接着创建config.py来安全地读取配置# config.py import os from dotenv import load_dotenv # 加载 .env 文件中的变量 load_dotenv() class Config: 配置类集中管理所有环境变量和常量 API_KEY os.getenv(ZHIPU_API_KEY) API_BASE os.getenv(ZHIPU_API_BASE) MODEL_NAME os.getenv(MODEL_NAME, glm-4-flash) # 默认值 classmethod def validate(cls): 验证必要配置是否存在 if not cls.API_KEY: raise ValueError(请在 .env 文件中设置 ZHIPU_API_KEY) # API_BASE 如果没有某些库会使用默认的 OpenAI 端点这里我们要求明确指定 if not cls.API_BASE: raise ValueError(请在 .env 文件中设置 ZHIPU_API_BASE (例如智谱的端点)) print(配置加载成功。)这种集中管理的方式比在代码里到处写os.getenv要清晰和安全得多。2.2 实现最简单的对话循环现在创建simple_agent.py。我们将使用langchain的ChatOpenAI来封装对大模型的调用因为它处理了对话格式和流式输出等细节。# simple_agent.py from langchain_openai import ChatOpenAI from langchain.schema import HumanMessage, SystemMessage from config import Config def initialize_agent(): 初始化与大模型对话的客户端 Config.validate() # 先验证配置 llm ChatOpenAI( openai_api_keyConfig.API_KEY, openai_api_baseConfig.API_BASE, model_nameConfig.MODEL_NAME, temperature0.1, # 控制创造性越低越稳定和确定 streamingFalse, # 初次调试先关闭流式输出更完整 ) return llm def run_conversation(): 运行一个简单的对话循环 print(初始化智能体...) agent initialize_agent() # 系统提示词定义智能体的角色和行为 system_prompt SystemMessage(content你是一个乐于助人的AI助手。请用中文清晰、简洁地回答用户的问题。) print(\n智能体已就绪。输入 退出 或 quit 结束对话。) conversation_history [system_prompt] while True: try: user_input input(\n你: ) if user_input.lower() in [退出, quit, exit]: print(对话结束。) break # 将用户输入加入历史 conversation_history.append(HumanMessage(contentuser_input)) # 调用大模型生成回复 print(智能体思考中...) response agent.invoke(conversation_history) # 提取回复内容 ai_reply response.content print(f智能体: {ai_reply}) # 将AI回复也加入历史实现多轮对话记忆 conversation_history.append(response) except KeyboardInterrupt: print(\n用户中断。) break except Exception as e: print(f\n调用模型时出错: {e}) # 可以选择从历史中移除出错的上轮用户输入避免污染 if conversation_history and isinstance(conversation_history[-1], HumanMessage): conversation_history.pop() print(请检查网络连接和API配置或稍后重试。) if __name__ __main__: run_conversation()关键点解释ChatOpenAI虽然名字叫“OpenAI”但通过openai_api_base参数我们可以指向任何兼容 OpenAI 接口的服务器包括智谱、DeepSeek等。SystemMessage这是给模型的“幕后指令”用于设定其身份、回答风格和边界。好的系统提示词是智能体行为稳定的关键。temperature设置为较低的 0.1是为了在开发阶段让模型的输出更确定、可复现便于调试。上线或需要创造性时可以调高。对话历史 (conversation_history)我们把所有消息系统、用户、AI都保存在一个列表里每次提问都把这个完整的历史传给模型。这就是实现多轮对话记忆的最简单方式。错误处理网络超时、API限额、模型服务异常都可能发生。用try-except包裹调用过程并给出明确提示是生产级代码的基本素养。运行与验证在终端中确保虚拟环境已激活然后运行python simple_agent.py如果一切正常你会看到“初始化智能体...配置加载成功。”然后进入对话循环。问它“你好”或“你能做什么”它应该能用中文回复。如果出错了按这个顺序排查API Key 和 Base URL确认.env文件内容正确且config.py能正确读取。可以在config.py最后加print(Config.API_KEY)测试。网络连接尝试用curl或浏览器访问你的API_BASE看是否通。依赖版本确认openai,langchain-openai等库已正确安装。有时需要指定版本如pip install openai1.12.0。模型名称确认MODEL_NAME在你的 API 服务商那里是有效的模型标识符。3. 赋予智能体“手脚”工具调用与任务规划一个只会聊天的 Agent 是“残疾”的。真正的智能体应该能根据你的指令去调用外部工具完成任务比如查天气、算数学、读写文件。这就是Tool Calling和Task Planning的核心。3.1 创建你的第一个工具我们在tools/目录下创建一个calculator.py实现一个简单的计算器工具。# tools/calculator.py from typing import Union from pydantic import BaseModel, Field class CalculatorInput(BaseModel): 计算器工具的输入参数模式 a: Union[int, float] Field(description第一个数字) b: Union[int, float] Field(description第二个数字) operation: str Field(description运算类型可选add加, subtract减, multiply乘, divide除) def calculator_tool(a: int | float, b: int | float, operation: str) - str: 一个简单的计算器工具。 执行基本的算术运算。 try: if operation add: result a b elif operation subtract: result a - b elif operation multiply: result a * b elif operation divide: if b 0: return 错误除数不能为零。 result a / b else: return f错误不支持的操作 {operation}。支持的操作add, subtract, multiply, divide. return f计算结果{a} {operation} {b} {result} except Exception as e: return f计算过程中发生错误{e} # 为了被 LangChain 识别我们需要将函数和其输入模式包装起来 # 注意在较新的 LangChain 版本中推荐使用 tool 装饰器但为了清晰理解原理我们先手动创建这里有几个关键设计pydantic模型CalculatorInput类用pydantic定义了工具需要的参数及其类型、描述。这能让大模型更准确地理解如何调用这个工具。清晰的函数文档calculator_tool的文档字符串内的内容非常重要。大模型会阅读它来理解工具的功能。健壮的错误处理工具内部处理了除零错误和非法操作返回明确的错误信息而不是抛出异常导致整个 Agent 崩溃。3.2 使用 LangChain 构建可调用工具的智能体现在我们升级simple_agent.py创建一个新的文件agent_with_tools.py。# agent_with_tools.py from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_tools_agent from langchain.tools import Tool from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.memory import ConversationBufferMemory from tools.calculator import calculator_tool, CalculatorInput from config import Config def create_agent(): 创建并返回一个具备工具调用能力的智能体执行器 Config.validate() # 1. 初始化LLM llm ChatOpenAI( openai_api_keyConfig.API_KEY, openai_api_baseConfig.API_BASE, model_nameConfig.MODEL_NAME, temperature0.1, streamingFalse, ) # 2. 将我们的计算器函数包装成 LangChain Tool 对象 calculator_tool_wrapped Tool.from_function( funccalculator_tool, nameCalculator, description用于执行加、减、乘、除运算。输入两个数字和操作类型。, args_schemaCalculatorInput, # 关联我们定义的Pydantic模型 return_directFalse, # 设为True则工具结果直接作为最终答案否则会经过LLM整理 ) # 3. 定义工具列表未来可以在这里添加更多工具 tools [calculator_tool_wrapped] # 4. 构建提示词模板 prompt ChatPromptTemplate.from_messages([ (system, 你是一个强大的AI助手可以调用工具来帮助用户解决问题。如果你需要计算请使用计算器工具。请用中文回答。), MessagesPlaceholder(variable_namechat_history), # 预留位置存放对话历史 (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), # 预留位置存放Agent的思考过程 ]) # 5. 初始化记忆用于多轮对话 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 6. 创建Agent agent create_openai_tools_agent(llmllm, toolstools, promptprompt) # 7. 创建Agent执行器它负责运行Agent并管理工具调用循环 agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, # 设为True会打印详细的思考过程调试时非常有用 handle_parsing_errorsTrue, # 处理模型输出解析错误 max_iterations5, # 限制最大迭代次数防止陷入死循环 ) return agent_executor def run_agent_with_tools(): 运行具备工具调用能力的智能体 print(正在初始化具备工具调用能力的智能体...) agent create_agent() print(智能体已就绪。输入‘退出’结束对话。\n) while True: try: user_input input(你: ) if user_input.lower() in [退出, quit, exit]: print(对话结束。) break # 调用执行器 response agent.invoke({input: user_input}) print(f\n智能体: {response[output]}\n) except KeyboardInterrupt: print(\n用户中断。) break except Exception as e: print(f\n发生错误: {e}) # 详细日志有助于调试 import traceback traceback.print_exc() if __name__ __main__: run_agent_with_tools()核心机制解析Tool对象Tool.from_function将我们的 Python 函数calculator_tool包装成 LangChain 能识别的工具并附上名称、描述和参数模式。大模型正是通过这些元数据来“知道”有这个工具以及如何调用它。AgentExecutor这是 LangChain 提供的“发动机”。它接收用户输入交给agent由LLM和提示词构成去思考agent可能会决定调用某个工具AgentExecutor就负责执行工具调用把结果返回给agent继续思考直到agent认为可以给出最终答案或者达到max_iterations限制。这个过程称为ReAct (Reasoning Acting)循环。verboseTrue这是调试神器。设为True后控制台会打印出 Agent 的完整思考链比如“我在想用户需要计算我应该调用 Calculator 工具参数是...”。通过这个输出你能清晰看到智能体是如何做决策的。max_iterations必须设置。防止智能体陷入“调用工具A - 分析结果 - 又调用工具A”的死循环。运行与测试运行python agent_with_tools.py。当verboseTrue时你会看到大量日志。试着问“123乘以456等于多少”。 观察控制台你应该能看到类似这样的日志 Entering new AgentExecutor chain... 思考用户问的是一个乘法计算问题。我需要使用计算器工具。 Action: Calculator Action Input: {a: 123, b: 456, operation: multiply} Observation: 计算结果123 multiply 456 56088 思考我得到了计算结果可以回答用户了。 Final Answer: 123乘以456等于56088。 Finished chain. 智能体: 123乘以456等于56088。这表明你的智能体成功理解了任务选择了正确的工具传入了正确的参数并给出了最终答案。恭喜你已经创建了一个具备基础工具调用能力的 AI Agent4. 从原型到生产架构扩展与避坑指南一个能在控制台对话的 Agent 只是起点。要让它真正有用我们需要考虑更复杂的场景处理长文本、管理复杂状态、接入真实API、以及部署成服务。同时开发过程中有很多“坑”需要提前避开。4.1 设计可扩展的智能体架构上面的例子把逻辑都写在一个文件里随着工具增多会变得混乱。一个更清晰的生产级架构可以这样组织my_ai_agent/ ├── core/ │ ├── __init__.py │ ├── config.py # 配置管理 │ ├── llm_client.py # LLM客户端封装支持不同厂商、模型切换 │ └── memory_manager.py # 记忆管理支持长上下文、向量存储 ├── tools/ │ ├── __init__.py │ ├── base_tool.py # 自定义工具基类 │ ├── calculator.py │ ├── web_search.py # 网络搜索工具示例 │ └── file_reader.py # 文件读取工具示例 ├── agents/ │ ├── __init__.py │ ├── base_agent.py # Agent基类 │ ├── chat_agent.py # 纯对话Agent │ └── tool_agent.py # 工具调用Agent ├── chains/ # 复杂任务链可选 ├── utils/ # 通用工具函数 ├── tests/ # 单元测试 ├── main.py # 应用入口CLI或Web服务 └── requirements.txt关键模块职责core/llm_client.py封装不同 LLM 供应商的调用细节。通过配置驱动可以轻松在智谱、OpenAI、本地模型之间切换。core/memory_manager.py当对话历史很长时全部传给模型会消耗大量 Token且可能超出上下文长度限制。这里需要实现记忆摘要、向量检索或分窗等策略只把最相关的历史片段传给模型。tools/base_tool.py定义一个所有工具都继承的基类统一工具注册、参数验证和错误处理逻辑。agents/base_agent.py定义 Agent 的通用接口如invoke,reset方便管理和测试。4.2 接入真实世界工具以搜索为例让我们在tools/下添加一个更实用的工具网络搜索。这里我们使用一个假设的搜索 API例如 SerpAPI 或 Tavily国内可用 Bing Search API 等。注意以下代码需要你替换为真实的 API 密钥和端点。# tools/web_search.py import requests from typing import Optional from pydantic import BaseModel, Field import json class WebSearchInput(BaseModel): query: str Field(description搜索查询词) num_results: Optional[int] Field(default5, description返回的结果数量默认5条) def web_search_tool(query: str, num_results: int 5) - str: 使用搜索引擎在网络上搜索信息。 返回搜索结果的摘要列表。 # 重要此处需要替换为真实的搜索API配置 api_key YOUR_SEARCH_API_KEY search_url https://api.example.com/search/v1 # 示例URL headers {Authorization: fBearer {api_key}} params {q: query, num: num_results} try: response requests.get(search_url, headersheaders, paramsparams, timeout10) response.raise_for_status() # 检查HTTP错误 data response.json() # 假设API返回格式为 {results: [{title: ..., snippet: ...}, ...]} results data.get(results, []) if not results: return 未找到相关结果。 summary [] for i, item in enumerate(results[:num_results], 1): title item.get(title, 无标题) snippet item.get(snippet, 无摘要) summary.append(f{i}. {title}: {snippet[:150]}...) # 截断长摘要 return 搜索到以下信息\n \n.join(summary) except requests.exceptions.Timeout: return 搜索请求超时请检查网络或稍后重试。 except requests.exceptions.RequestException as e: return f搜索请求失败: {e} except (KeyError, json.JSONDecodeError) as e: return f解析搜索结果时出错: {e}将这个工具像计算器一样注册到你的agent_with_tools.py的tools列表中你的智能体就具备了“上网”能力。你可以问它“今天北京天气怎么样” 它会尝试调用搜索工具来获取信息。4.3 开发与部署中的关键“坑点”成本控制大模型 API 调用是按 Token 收费的。长对话、复杂思考链verbose模式会消耗更多 Token都会增加成本。开发阶段使用便宜的模型如glm-4-flash。控制max_tokens参数限制单次回复长度。为你的 API 密钥设置用量告警和预算。速率限制与超时所有 API 都有调用频率限制Rate Limit。你的代码必须有重试机制和退避策略如指数退避。# 简单的带重试的调用示例 from tenacity import retry, stop_after_attempt, wait_exponential retry(stopstop_after_attempt(3), waitwait_exponential(multiplier1, min4, max10)) def safe_llm_invoke(llm, messages): return llm.invoke(messages)上下文长度限制模型能处理的文本长度有限如 8K, 32K, 128K Tokens。长文档处理或超长对话时需要使用memory管理定期总结或丢弃旧对话。对于长文档使用 RAG检索增强生成技术只检索相关片段传入上下文。工具调用的可靠性大模型可能生成错误的工具调用参数类型不对、字段缺失。除了使用Pydantic做验证还应该在工具函数内部进行防御性编程并让 Agent 有能力在工具调用失败后尝试修正或向用户澄清。安全与隐私API Key永远不要硬编码或提交到代码仓库。使用.env文件和环境变量。用户数据如果 Agent 能读取文件或访问数据库必须严格控制权限并对输入进行过滤防止路径遍历../或 SQL 注入。工具权限删除文件、执行系统命令等危险工具在开发环境可以测试但生产环境必须极度谨慎或完全禁止。测试与评估不要只靠手动聊天测试。为你的 Agent 核心功能编写单元测试和集成测试。单元测试测试单个工具函数在不同输入下的输出。集成测试模拟用户对话流验证 Agent 能否正确完成端到端任务如“计算一下(1234)*2 是多少”。使用pytest等框架并将测试加入 CI/CD 流程。4.4 部署为服务FastAPI 示例最终你可能需要将 Agent 部署成 Web API 供其他应用调用。使用 FastAPI 可以快速实现。# main.py (FastAPI 版本) from fastapi import FastAPI, HTTPException from pydantic import BaseModel from agent_with_tools import create_agent # 导入我们之前构建的agent import uvicorn app FastAPI(titleMy AI Agent API) # 在应用启动时初始化Agent避免每次请求都初始化 agent_executor None app.on_event(startup) async def startup_event(): global agent_executor print(正在初始化AI Agent...) agent_executor create_agent() print(AI Agent 初始化完成。) class ChatRequest(BaseModel): message: str session_id: str None # 用于区分不同会话 class ChatResponse(BaseModel): reply: str session_id: str app.post(/chat, response_modelChatResponse) async def chat_endpoint(request: ChatRequest): if agent_executor is None: raise HTTPException(status_code503, detailAgent未就绪) try: # 这里可以基于session_id从数据库或缓存中读取/保存对话历史 # 简化起见我们每次请求都是独立的 result agent_executor.invoke({input: request.message}) return ChatResponse(replyresult[output], session_idrequest.session_id or default) except Exception as e: raise HTTPException(status_code500, detailf处理请求时出错: {str(e)}) if __name__ __main__: # 运行服务: uvicorn main:app --reload --host 0.0.0.0 --port 8000 uvicorn.run(app, host0.0.0.0, port8000)运行后你就可以通过http://localhost:8000/docs访问自动生成的 API 文档并通过POST /chat接口与你的智能体交互了。5. 学习路线与面试准备下一步该学什么如果你跟着做到了这里已经掌握了 AI Agent 开发的核心闭环。但要达到“跳槽”或独立开发复杂 Agent 的水平还需要系统性地补全以下知识栈。5.1 技术栈深化框架精通LangChain/LlamaIndex深入理解其Chains,Agents,Retrievers,Memory等核心概念。学习如何自定义Agent和Tool。其他框架了解AutoGen,CrewAI等多智能体框架以及Semantic Kernel(微软) 等。提示词工程学习编写有效的System Prompt来精确控制 Agent 行为。掌握Few-Shot少样本提示在提示词中提供例子来引导模型。了解Chain-of-Thought思维链提示让模型展示推理过程。记忆与检索向量数据库学习使用Chroma,Pinecone,Weaviate或Milvus存储和检索文本嵌入Embeddings这是实现 RAG 的基础。记忆策略实现对话摘要、基于向量检索的关键记忆提取等。评估与监控学习如何设计评估指标忠实度、相关性、有用性来量化 Agent 表现。使用LangSmithLangChain 官方平台或自定义日志来追踪每次调用链分析性能瓶颈和错误。工程化与部署异步处理使用asyncio处理并发请求提高吞吐量。队列与缓存对于耗时任务引入CeleryRedis等消息队列。使用缓存如Redis存储频繁访问的模型响应或工具结果。容器化使用Docker打包你的 Agent 应用及其所有依赖。云部署了解如何在AWS,GCP,Azure或国内云服务器上部署和扩缩容你的服务。5.2 应对 Agent 开发面试题面试官不仅会问你会用什么更会问你怎么设计、怎么解决问题。以下是一些典型问题及回答思路Q: 请描述一下你设计的一个 AI Agent 系统架构。A:从用户请求入口API/Web讲起提到负载均衡、API网关。然后到核心的Orchestrator协调器它负责解析请求管理对话状态Memory调用LLM进行规划。LLM决策后可能调用Tool Layer工具层包括计算、搜索、数据库查询等。工具结果返回给Orchestrator再决定是继续思考还是返回最终答案。最后要提到监控、日志和评估模块。Q: 如何保证工具调用的安全性和稳定性A:安全性1) 工具权限分级危险操作如删文件需额外授权或禁止。2) 对用户输入和工具参数做严格的验证和清洗防注入。3) API Key 等机密信息通过环境变量或密钥管理服务获取。稳定性1) 为每个工具和 LLM 调用设置超时和重试机制。2) 实现熔断和降级当某个工具或模型持续失败时暂时屏蔽或提供备选方案。3) 全面的错误处理和日志记录便于快速定位问题。Q: 如何处理超出模型上下文长度的长文档A:采用 RAG 模式。1) 将长文档切分成有重叠的片段Chunking。2) 使用嵌入模型Embedding Model将每个片段转换为向量。3) 将向量存入向量数据库。4) 当用户提问时将问题也转换为向量在向量数据库中检索出最相关的几个片段。5) 只将这些相关片段和问题一起传给 LLM 生成答案。这样就避免了上下文长度限制。Q: 如何评估你的 Agent 表现好坏A:分几个层面1)功能性能否正确完成任务通过人工评估或自动化测试集。2)效率响应延迟、Token 消耗成本。3)用户体验回答的流畅性、相关性、有用性可通过用户反馈或评分收集。4)稳定性服务的可用性、错误率。我们会建立一套混合的评估体系结合自动化测试和人工抽查。5.3 项目进阶从 Demo 到作品集把上面这个简单的计算器搜索 Agent 扩展成以下任何一个项目都能成为你简历上的亮点个人知识库助手接入向量数据库上传你的 PDF、Word 文档让 Agent 基于你的私人资料回答问题。自动化数据分析助手集成pandas、matplotlib等工具让用户用自然语言描述Agent 自动执行数据清洗、分析和可视化。多智能体协作系统使用CrewAI或AutoGen创建多个具有不同角色研究员、写手、评审员的 Agent协作完成一份市场调研报告。与外部系统集成将 Agent 接入 Slack、钉钉、微信公众号成为一个聊天机器人或者接入 Zapier/Make根据邮件、日历事件自动触发任务。最后也是最关键的一点AI Agent 领域变化极快新的模型、框架、论文层出不穷。保持学习的唯一方法就是动手。把你学到的每一个新概念都立刻用代码实现一个最小可行原型。遇到报错就去读文档、查 Issue、看源码。这个从“跑通”到“理解”再到“优化”的过程才是构建你完整 Agent 开发体系最扎实的路径。