当你看到一个 AI Agent 编辑多个文件、运行命令、处理错误并迭代解决问题时,似乎很复杂,感觉就像魔法一样。但事实并非如此。构建 Agent 的秘密就是没有秘密。
Agent 的核心出奇地简单:它是一个在循环中运行的大型语言模型(LLM),配备了它可以选择使用的工具。
如果你能用 Python 写一个循环,你就能构建一个 Agent。本指南将引导你完成整个过程,从简单的 API 调用到一个功能完整的 CLI Agent。
什么是 Agent?
传统的软件工作流是规范性的,遵循预定义的路径(步骤 A -> 步骤 B -> 步骤 C),而 Agent 是使用 LLM 动态决定应用程序控制流以实现用户目标的系统。
一个 Agent 通常由以下核心组件组成:
- 模型(大脑):推理引擎,在我们的案例中是 Gemini 模型。它通过模糊性进行推理,规划步骤,并决定何时需要外部帮助。
- 工具(手和眼睛):Agent 可以执行的函数,用于与外部世界/环境交互(例如,搜索网络、读取文件、调用 API)。
- 上下文/记忆(工作空间):Agent 在任何时刻可以访问的信息。有效地管理这一点,被称为上下文工程。
- 循环(生命):一个 while 循环,允许模型:观察 → 思考 → 行动 → 再次观察,直到任务完成。
几乎每个 Agent 的"循环"都是一个迭代过程:
- 定义工具集:你使用结构化的 JSON 格式向模型描述可用的工具(例如 get_weather)。
- 调用 LLM:你将用户的提示和工具定义发送给模型。
- 模型决策:模型分析请求。如果需要工具,它会返回一个结构化的 tool use,包含工具名称和参数。
- 执行工具(客户端责任):客户端/应用程序代码拦截这个 tool use,执行实际的代码或 API 调用,并捕获结果。
- 响应和迭代:你将结果(tool response)发送回模型。模型使用这些新信息来决定下一步,要么调用另一个工具,要么生成最终响应。
构建 Agent
让我们逐步构建一个 Agent,从基本的文本生成到使用 Gemini 3 Pro 和 Python SDK 的功能性 CLI Agent。
前提条件:安装 SDK(pip install google-genai)并设置你的 GEMINI_API_KEY 环境变量(在 AI Studio 中获取[1])。
步骤 1:基本文本生成和抽象
第一步是创建与 LLM 的基线交互,对我们来说是 Gemini 3 Pro。我们将创建一个简单的 Agent 类抽象来构建我们的代码,并在本指南中进行扩展。我们首先从一个维护对话历史的简单聊天机器人开始。
from google import genai from google.genai import types class Agent: def __init__(self, model: str): self.model = model self.client = genai.Client() self.contents = [] def run(self, contents: str): self.contents.append({"role": "user", "parts": [{"text": contents}]}) response = self.client.models.generate_content(model=self.model, contents=self.contents) self.contents.append(response.candidates[0].content) return response agent = Agent(model="gemini-3-pro-preview") response1 = agent.run( contents="你好,德国最值得游览的前 3 个城市是什么?只返回城市名称。" ) print(f"模型: {response1.text}") # 输出: Berlin, Munich, Cologne response2 = agent.run( contents="告诉我关于第二个城市的一些事情。" ) print(f"模型: {response2.text}") # 输出: Munich is the capital of Bavaria and is known for its Oktoberfest.这还不是一个 Agent。它是一个标准的聊天机器人。它维护状态但不能采取行动,没有"手或眼睛"。
步骤 2:赋予它手和眼睛(工具使用)
要开始将其转变为 Agent,我们需要工具使用或函数调用。我们为 Agent 提供工具。这需要定义实现(Python 代码)和定义(LLM 看到的模式)。如果 LLM 认为该工具将有助于解决用户的提示,它将返回一个结构化的请求来调用该函数,而不仅仅是文本。
我们将创建 3 个工具:read_file、write_file 和 list_dir。工具定义是一个 JSON 模式,定义了工具的 name、description 和 parameters。
最佳实践:使用 description 字段来解释何时以及如何使用该工具。模型严重依赖这些来理解何时以及如何使用该工具。要明确和清晰。
import os import json read_file_definition = { "name": "read_file", "description": "读取文件并返回其内容。", "parameters": { "type": "object", "properties": { "file_path": { "type": "string", "description": "要读取的文件路径。", } }, "required": ["file_path"], }, } list_dir_definition = { "name": "list_dir", "description": "列出目录的内容。", "parameters": { "type": "object", "properties": { "directory_path": { "type": "string", "description": "要列出的目录路径。", } }, "required": ["directory_path"], }, } write_file_definition = { "name": "write_file", "description": "使用给定内容写入文件。", "parameters": { "type": "object", "properties": { "file_path": { "type": "string", "description": "要写入的文件路径。", }, "contents": { "type": "string", "description": "要写入文件的内容。", }, }, "required": ["file_path", "contents"], }, } def read_file(file_path: str) -> dict: with open(file_path, "r") as f: return f.read() def write_file(file_path: str, contents: str) -> bool: """使用给定内容写入文件。""" with open(file_path, "w") as f: f.write(contents) return True def list_dir(directory_path: str) -> list[str]: """列出目录的内容。""" full_path = os.path.expanduser(directory_path) return os.listdir(full_path) file_tools = { "read_file": {"definition": read_file_definition, "function": read_file}, "write_file": {"definition": write_file_definition, "function": write_file}, "list_dir": {"definition": list_dir_definition, "function": list_dir}, }现在我们将 tools 和函数调用与系统指令一起集成到我们的 Agent 类中。
from google import genai from google.genai import types class Agent: def __init__(self, model: str,tools: list[dict]): self.model = model self.client = genai.Client() self.contents = [] self.tools = tools def run(self, contents: str): self.contents.append({"role": "user", "parts": [{"text": contents}]}) config = types.GenerateContentConfig( tools=[types.Tool(function_declarations=[tool["definition"] for tool in self.tools.values()])], ) response = self.client.models.generate_content(model=self.model, contents=self.contents, config=config) self.contents.append(response.candidates[0].content) return response agent = Agent(model="gemini-3-pro-preview", tools=file_tools) response = agent.run( contents="你能列出我当前目录中的文件吗?" ) print(response.function_calls) # 输出: [FunctionCall(name='list_dir', arguments={'directory_path': '.'})]太棒了!模型已成功调用了工具。现在,我们需要将工具执行逻辑添加到我们的 Agent 类中,并循环将结果返回给模型。
步骤 3:闭合循环(Agent)
Agent 不是生成一个工具调用,而是生成一系列工具调用,将结果返回给模型,然后生成另一个工具调用,依此类推,直到任务完成。
Agent 类处理核心循环:拦截 FunctionCall,在客户端执行工具,并发送回 FunctionResponse。我们还向模型添加了 SystemInstruction,以指导模型该做什么。
注意:Gemini 3 使用**思维签名[2]**在 API 调用之间维护推理上下文。你必须将这些签名原样返回给模型,就像接收时一样。
# ... 步骤 2 中的工具和工具定义代码应该在这里 ... from google import genai from google.genai import types class Agent: def __init__(self, model: str,tools: list[dict], system_instruction: str = "你是一个有帮助的助手。"): self.model = model self.client = genai.Client() self.contents = [] self.tools = tools self.system_instruction = system_instruction def run(self, contents: str | list[dict[str, str]]): if isinstance(contents, list): self.contents.append({"role": "user", "parts": contents}) else: self.contents.append({"role": "user", "parts": [{"text": contents}]}) config = types.GenerateContentConfig( system_instruction=self.system_instruction, tools=[types.Tool(function_declarations=[tool["definition"] for tool in self.tools.values()])], ) response = self.client.models.generate_content(model=self.model, contents=self.contents, config=config) self.contents.append(response.candidates[0].content) if response.function_calls: functions_response_parts = [] for tool_call in response.function_calls: print(f"[函数调用] {tool_call}") if tool_call.name in self.tools: result = {"result": self.tools[tool_call.name]["function"](**tool_call.args)} else: result = {"error": "未找到工具"} print(f"[函数响应] {result}") functions_response_parts.append({"functionResponse": {"name": tool_call.name, "response": result}}) return self.run(functions_response_parts) return response agent = Agent( model="gemini-3-pro-preview", tools=file_tools, system_instruction="你是一个有帮助的编码助手。回应时像 Linus Torvalds 一样。" ) response = agent.run( contents="你能列出我当前目录中的文件吗?" ) print(response.text) # 输出: [函数调用] id=None args={'directory_path': '.'} name='list_dir' # [函数响应] {'result': ['.venv', ... ]} # There. Your current directory contains: `LICENSE`,恭喜你。你刚刚构建了你的第一个功能性 Agent。
阶段 4:多轮 CLI Agent
现在我们可以在一个简单的 CLI 循环中运行我们的 Agent。创建高度功能性的行为所需的代码少得令人惊讶。
# ... 步骤 3 中的 Agent、工具和工具定义代码应该在这里 ... agent = Agent( model="gemini-3-pro-preview", tools=file_tools, system_instruction="你是一个有帮助的编码助手。回应时像 Linus Torvalds 一样。" ) print("Agent 已就绪。让它检查此目录中的文件。") while True: user_input = input("你: ") if user_input.lower() in ['exit', 'quit']: break response = agent.run(user_input) print(f"Linus: {response.text}\n")Agent 工程的最佳实践
构建循环很容易;使其可靠、透明和可控却很难。以下是源自顶级行业实践的关键工程原则,按功能领域分组。
1. 工具定义和人机工程学
你的工具是模型的接口。不要只是包装你现有的内部 API。如果一个工具对人类来说很混乱,那么对模型来说也很混乱:
- 清晰的命名:使用明显的名称,如 search_customer_database,而不是 cust_db_v2_query。
- 精确的描述:Gemini 读取函数文档字符串以理解何时以及如何使用工具。花时间仔细编写这些,这本质上是工具的"提示工程"。
- 返回有意义的错误:不要返回 50 行的 Java 堆栈跟踪。如果工具失败,返回一个清晰的字符串,如 错误:未找到文件。你是指 ‘data.csv’ 吗?。这允许 Agent 自我纠正。
- 容忍模糊输入:如果模型经常猜错文件路径,更新你的工具以处理相对路径或模糊输入,而不仅仅是出错。
2. 上下文工程
模型有有限的"注意力预算"。管理什么信息进入上下文对性能和成本至关重要。
- 不要"倾倒"数据:不要有一个返回整个 10MB 数据库表的工具。而不是 get_all_users(),创建 search_users(query: str)。
- 即时加载:而不是预加载所有数据(传统的 RAG),使用即时策略。Agent 应该维护轻量级标识符(文件路径、ID),并仅在需要时使用工具动态加载内容。
- 压缩:对于运行时间很长的 Agent,总结历史记录,删除旧上下文或开始新会话。
- Agent 记忆:允许 Agent 维护在上下文窗口之外持久化的笔记或草稿本,仅在相关时将它们拉回。
3. 不要过度工程化
构建复杂的多 Agent 系统很诱人。不要这样做。
- 首先最大化单个 Agent:不要立即构建复杂的多 Agent 系统。Gemini 在单个提示中处理数十个工具的能力非常强。
- 逃生舱口:确保循环可以停止,如 max_iterations 中断(例如,15 轮)。
- 护栏和系统指令:使用 system_instruction 用硬性规则引导模型(例如,“你严格禁止提供超过 50 美元的退款”)或使用外部分类器。
- 人在回路中:对于敏感操作(如 send_email 或 execute_code),在实际执行工具之前暂停循环并要求用户确认。
- 优先考虑透明度和调试:记录工具调用和参数。分析模型的推理有助于识别问题,并随着时间的推移改进 Agent。
结论
构建 Agent 不再是魔法;这是一项实际的工程任务。正如我们所展示的,你可以在不到 100 行代码中构建一个可工作的原型。虽然理解这些基础知识是关键,但不要陷入一遍又一遍地重新设计相同模式的困境。AI 社区创建了出色的开源库,可以帮助你更快地构建更复杂和健壮的 Agent。
想入门 AI 大模型却找不到清晰方向？备考大厂 AI 岗还在四处搜集零散资料？别再浪费时间啦！2025 年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 大模型，还是有基础想冲刺大厂、了解行业趋势，这份资料都能满足你！
现在只需按照提示操作，就能免费领取：
👇👇扫码免费领取全部内容👇👇
2025 年想抓住 AI 大模型的风口？别犹豫，这份免费资料就是你的 “起跑线”！
