从 0 到 1 开发一个 AI Agent：完整实战指南

1. 引言大模型时代AI Agent智能体已经成为最热门的技术方向之一。从简单的聊天机器人到能自主调用工具、规划任务、完成复杂工作的智能助手Agent 正在重塑我们与软件交互的方式。很多开发者想从零开始开发一个属于自己的 AI Agent却常常被各种概念和技术栈搞得一头雾水Agent 到底是什么它和普通的大模型 API 调用有什么区别需要掌握哪些技术从哪里开始写第一行代码这篇文章将带你从 0 到 1 完整走一遍 AI Agent 的开发流程。我会从核心概念讲起逐步拆解 Agent 的架构组成然后手把手带你搭建开发环境、编写核心代码、接入工具调用最后给出一个可运行的完整示例并分享一些进阶优化思路。2. 什么是 AI Agent在动手写代码之前先搞清楚概念。AI Agent 是一个能够感知环境、做出决策并采取行动的智能系统。它不只是简单地一问一答而是能围绕一个目标自主地规划步骤、调用工具、评估结果并在必要时自我纠错直到完成任务。2.1 Agent 与普通 LLM 应用的区别维度普通 LLM 应用AI Agent交互模式单轮问答多轮自主推理与行动能力边界只能生成文本可调用工具、访问外部数据任务处理一次生成规划-执行-观察-再规划的循环自主性低完全依赖用户提示高可自主拆解并完成任务2.2 Agent 的核心能力一个完整的 Agent 通常具备以下四种核心能力规划Planning把复杂任务拆解成可执行的子步骤。记忆Memory记住对话历史、中间结果和长期知识。工具使用Tool Use调用外部 API、数据库、代码解释器等完成实际操作。反思与纠错Reflection根据执行结果评估进展失败时调整策略重试。3. Agent 的架构组成理解了概念之后我们来看一个典型 Agent 的架构。它通常由以下几个核心模块组成是否用户输入Agent 核心LLM是否需要调用工具工具调用执行结果生成最终回复输出给用户3.1 核心组件拆解LLM 大脑负责理解意图、推理决策、生成回复。这是 Agent 的思考中枢。提示词Prompt定义 Agent 的角色、能力边界、工作流程和输出格式。工具集ToolsAgent 可以调用的外部能力如搜索引擎、计算器、数据库查询、HTTP 请求等。记忆系统Memory短期记忆保存当前任务的上下文长期记忆保存跨会话的知识。编排器Orchestrator控制 Agent 的循环流程——思考、行动、观察结果、再思考。4. 技术选型与开发环境准备4.1 技术栈选择对于初学者我推荐以下技术栈生态成熟、上手快语言Python 3.10LLM 框架LangChain 或 LlamaIndex封装了 Agent 的常用组件大模型 APIOpenAI、DeepSeek、通义千问等支持 OpenAI 兼容接口即可依赖管理pip venv 或 Poetry4.2 安装依赖首先创建项目目录和虚拟环境mkdirmy-agentcdmy-agent python-mvenv venvsourcevenv/bin/activate# Windows 下用 venv\Scripts\activate然后安装核心依赖pipinstalllangchain langchain-openai python-dotenv4.3 配置环境变量在项目根目录创建.env文件填入你的 API KeyOPENAI_API_KEYsk-xxxxxxxxxxxxxxxx# 如果使用其他兼容 OpenAI 接口的服务可配置# OPENAI_API_BASEhttps://api.deepseek.com/v1# OPENAI_MODEL_NAMEdeepseek-chat5. 从零编写第一个 Agent下面我们从一个最简单的 Agent 开始逐步增加能力。5.1 最小可运行的 Agent先写一个最基础的版本——它只有一个 LLM能根据用户输入生成回复importosfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAI load_dotenv()# 初始化大模型llmChatOpenAI(modelos.getenv(OPENAI_MODEL_NAME,gpt-4o-mini),temperature0.7,)# 最简单的对话responsellm.invoke(你好请用一句话介绍你自己)print(response.content)运行这段代码你就拥有了一个最原始的Agent 雏形。但它还称不上 Agent因为它没有规划能力也不能调用工具。5.2 给 Agent 添加工具调用能力工具调用是 Agent 与普通 LLM 应用的关键区别。下面我们定义一个简单的计算器工具并让 Agent 学会使用它importosfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromlangchain.agentsimportcreate_tool_calling_agent,AgentExecutorfromlangchain.toolsimporttoolfromlangchain_core.promptsimportChatPromptTemplate load_dotenv()# 1. 定义工具tooldefadd(a:float,b:float)-float:计算两个数字的和。returnabtooldefmultiply(a:float,b:float)-float:计算两个数字的乘积。returna*b# 2. 初始化 LLMllmChatOpenAI(modelos.getenv(OPENAI_MODEL_NAME,gpt-4o-mini),temperature0,)# 3. 创建提示词模板promptChatPromptTemplate.from_messages([(system,你是一个智能助手可以调用工具来帮助用户解决问题。),(human,{input}),(placeholder,{agent_scratchpad}),])# 4. 创建 Agenttools[add,multiply]agentcreate_tool_calling_agent(llm,tools,prompt)agent_executorAgentExecutor(agentagent,toolstools,verboseTrue)# 5. 运行resultagent_executor.invoke({input:请计算 (23 45) * 2 的结果})print(result[output])运行后你会看到 Agent 的完整推理过程它先调用add计算 234568再调用multiply计算 68×2136最后给出答案。这就是一个真正的 Agent 循环。5.3 理解 Agent 的执行循环上面的例子背后Agent 实际上经历了一个思考-行动-观察的循环否是接收用户任务LLM 思考需要哪个工具生成工具调用指令执行工具把结果返回给 LLM任务完成了吗生成最终答案6. 构建一个完整的实战项目掌握了基础之后我们来构建一个更完整的 Agent一个能联网搜索并总结信息的智能助手。6.1 项目结构my-agent/ ├── .env ├── requirements.txt ├── main.py └── agent/ ├── __init__.py ├── tools.py # 自定义工具 ├── memory.py # 记忆管理 └── agent.py # Agent 组装6.2 定义工具集# agent/tools.pyimportrequestsfromlangchain.toolsimporttooltooldefsearch_web(query:str)-str:在互联网上搜索信息返回前几条搜索结果摘要。# 这里以 DuckDuckGo 为例实际可替换为 SerpAPI、Bing 等urlhttps://api.duckduckgo.com/params{q:query,format:json}resprequests.get(url,paramsparams,timeout10)dataresp.json()results[]fortopicindata.get(RelatedTopics,[])[:5]:ifTextintopic:results.append(topic[Text])return\n.join(results)ifresultselse未找到相关结果。tooldefget_current_time()-str:获取当前日期和时间。fromdatetimeimportdatetimereturndatetime.now().strftime(%Y-%m-%d %H:%M:%S)6.3 添加记忆能力为了让 Agent 能记住多轮对话的上下文我们给它加上记忆# agent/memory.pyfromlangchain.memoryimportConversationBufferMemoryfromlangchain_core.chat_historyimportInMemoryChatMessageHistorydefbuild_memory():构建对话记忆。returnConversationBufferMemory(chat_memoryInMemoryChatMessageHistory(),return_messagesTrue,memory_keychat_history,)6.4 组装 Agent# agent/agent.pyimportosfromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromlangchain.agentsimportcreate_tool_calling_agent,AgentExecutorfromlangchain_core.promptsimportChatPromptTemplate,MessagesPlaceholderfromagent.toolsimportsearch_web,get_current_timefromagent.memoryimportbuild_memory load_dotenv()defcreate_agent():创建并返回一个带记忆和工具的 Agent。# 初始化 LLMllmChatOpenAI(modelos.getenv(OPENAI_MODEL_NAME,gpt-4o-mini),temperature0.3,)# 工具集tools[search_web,get_current_time]# 提示词promptChatPromptTemplate.from_messages([(system,你是一个乐于助人的 AI 助手。你可以使用工具获取实时信息。回答要简洁、准确并注明信息来源。),MessagesPlaceholder(variable_namechat_history),(human,{input}),MessagesPlaceholder(variable_nameagent_scratchpad),])# 组装 Agentagentcreate_tool_calling_agent(llm,tools,prompt)executorAgentExecutor(agentagent,toolstools,memorybuild_memory(),verboseTrue,handle_parsing_errorsTrue,)returnexecutor6.5 主程序入口# main.pyfromagent.agentimportcreate_agentdefmain():agentcreate_agent()print(AI Agent 已启动输入 exit 退出。\n)whileTrue:user_inputinput(你)ifuser_input.lower()in(exit,quit):breakresponseagent.invoke({input:user_input})print(fAgent{response[output]}\n)if__name____main__:main()运行python main.py你就可以和这个 Agent 对话了。试试问它今天几号“或帮我搜索一下 LangChain 的最新版本”它会自动调用对应工具来回答。7. 进阶优化方向完成一个能跑通的 Agent 只是第一步。要把它做成生产级应用还需要关注以下几个方面7.1 规划能力增强ReAct 模式让模型先思考Reason再行动Act交替进行提升复杂任务的处理能力。Plan-and-Execute先让 LLM 生成完整计划再逐步执行适合步骤明确的长任务。任务分解把大任务拆成多个子任务分别交给不同的子 Agent 处理。7.2 记忆系统升级向量数据库用 Chroma、FAISS 等存储长期记忆支持语义检索。摘要记忆当对话过长时自动总结历史压缩上下文。分层记忆区分工作记忆、情景记忆和语义记忆按需调用。7.3 工具生态扩展代码解释器让 Agent 写代码并执行处理数据分析任务。API 集成接入企业内部的业务系统 API。多模态工具支持图像生成、语音合成等能力。7.4 安全与可靠性权限控制限制 Agent 可调用的工具范围敏感操作需人工确认。输出校验对 Agent 的最终输出做格式和内容校验。成本控制设置 token 上限、超时机制避免无限循环。日志与审计记录 Agent 的每一步决策和工具调用便于排查问题。8. 常见问题与排查8.1 Agent 不调用工具怎么办检查工具的描述是否清晰LLM 需要理解什么时候该用这个工具。适当降低temperature让模型更稳定地遵循指令。在系统提示词中明确说明当需要实时信息时必须调用搜索工具。8.2 工具调用报错确认工具函数的参数类型标注正确LLM 依赖类型信息生成调用参数。在工具内部做好异常捕获返回友好的错误信息。开启handle_parsing_errorsTrue让 Agent 在解析失败时能自我纠正。8.3 上下文过长使用摘要记忆压缩历史对话。限制单轮工具返回结果的长度。必要时切换支持更长上下文的模型。9. 总结从 0 到 1 开发一个 AI Agent核心路径可以概括为四步理解概念明确 Agent 与普通 LLM 应用的区别掌握规划、记忆、工具、反思四大能力。搭建环境选好技术栈配置好 LLM API 和依赖。编写核心从最小可运行版本开始逐步加入工具调用、记忆和编排逻辑。持续优化在规划能力、记忆系统、工具生态和安全可靠性上不断迭代。AI Agent 的开发是一个实践性很强的领域最好的学习方式就是动手写代码。建议你先跑通本文的示例然后尝试给它添加新的工具、接入自己的业务场景在实践中逐步深入。希望这篇文章能帮你迈出 AI Agent 开发的第一步。如果你在实践过程中遇到问题欢迎在评论区交流讨论。