使用 Gemini 3 从零开始构建 Agent 的实用指南！-程序员充电站

当你看到一个 AI 代理编辑多个文件、运行命令、处理错误并迭代解决问题时，可能会觉得这像魔法一样复杂。但其实不然。构建代理的秘诀在于：它根本没有秘密。

一个 Agent 的核心原理非常简单：它是一个大型语言模型（LLM）在一个循环中运行，并配备了它可以选择使用的工具。

只要你会用 Python 编写循环，你就能构建一个 Agent。本指南将带你一步步完成整个过程，从简单的 API 调用到功能完备的命令行接口（CLI）代理。

Agent 的真正定义是什么？

传统的软件工作流是预设的，遵循预定义的路径（步骤 A -> 步骤 B -> 步骤 C）。而Agent是一个系统，它利用 LLM动态地决定应用程序的控制流程，以达成用户的目标。

一个 Agent 通常由以下核心组件构成：

模型（大脑）：推理引擎，在本例中是 Gemini 模型。它负责处理歧义、规划步骤，并决定何时需要外部帮助。
工具（手和眼）：代理可以执行的功能，用于与外部世界/环境交互（例如，搜索网页、读取文件、调用 API）。
上下文/记忆（工作区）：代理在任何时刻都能获取的信息。有效地管理这些信息，也就是所谓的“上下文工程（Context Engineering）”。
循环（生命）：一个while循环，允许模型：观察 → 思考 → 行动 → 再次观察，直到任务完成。

“循环”的工作流程

几乎所有 Agent 的“循环”都是一个迭代过程：

定义工具：你使用结构化的 JSON 格式向模型描述你可用的工具（例如，get_weather）。
调用 LLM：你将用户的提示词和工具定义发送给模型。
模型决策：模型分析请求。如果需要工具，它会返回一个结构化的工具调用请求，其中包含工具名称和参数。
执行工具（客户端责任）：客户端/应用程序代码拦截这个工具调用请求，执行实际的代码或 API 调用，并捕获结果。
响应与迭代：你将结果（工具响应）发回给模型。模型利用这一新信息来决定下一步，可能是调用另一个工具，也可能是生成最终的回答。

构建 Agent

让我们使用 Gemini 3 Pro 和 Python SDK 一步步构建一个 Agent，从基本的文本生成逐步过渡到功能完备的 CLI 代理。

先决条件：安装 SDK (pip install google-genai) 并设置你的GEMINI_API_KEY环境变量（可在 AI Studio 中获取）。

步骤 1：基础文本生成和抽象

第一步是创建与 LLM（即 Gemini 3 Pro）交互的基线。我们将创建一个简单的Agent类抽象来组织代码，并在后续步骤中对其进行扩展。首先从一个维护会话历史的简单聊天机器人开始。

from google import genaifrom google.genai import typesclass Agent: def __init__(self, model: str): self.model = model self.client = genai.Client() self.contents = [] # 用于存储会话历史 def run(self, contents: str): # 1. 将用户输入添加到历史记录 self.contents.append({"role": "user", "parts": [{"text": contents}]}) # 2. 调用模型生成内容 response = self.client.models.generate_content(model=self.model, contents=self.contents) # 3. 将模型的响应添加到历史记录 self.contents.append(response.candidates[0].content) return responseagent = Agent(model="gemini-3-pro-preview")response1 = agent.run( contents="Hello, What are top 3 cities in Germany to visit? Only return the names of the cities.")print(f"Model: {response1.text}")# 输出: Berlin, Munich, Cologne response2 = agent.run( contents="Tell me something about the second city.")print(f"Model: {response2.text}")# 输出: Munich is the capital of Bavaria and is known for its Oktoberfest.

请注意，这还不是一个 Agent。它是一个标准的聊天机器人。它能保持状态（记忆），但不能采取行动，没有“手和眼”。

步骤 2：赋予它手和眼（工具使用）

要开始将它转变为 Agent，我们需要工具使用或函数调用能力。我们为 Agent 提供工具。这需要定义实现（Python 代码）和定义（LLM 看见的 Schema）。如果 LLM 认为某个工具将有助于解决用户的提示，它将返回一个结构化的请求来调用该函数，而不是仅仅返回文本。

我们将创建 3 个工具：read_file、write_file和list_dir。工具定义是一个 JSON Schema，它定义了工具的name、description和parameters。

最佳实践：使用description字段来解释何时以及如何使用该工具。模型高度依赖这些描述来理解工具的使用时机和方法。务必清晰明了。

import osimport json# --- 工具定义（Schema） ---read_file_definition = { "name": "read_file", "description": "Reads a file and returns its contents.", # ... 省略其余参数定义 ...}list_dir_definition = { "name": "list_dir", "description": "Lists the contents of a directory.", # ... 省略其余参数定义 ...}write_file_definition = { "name": "write_file", "description": "Writes a file with the given contents.", # ... 省略其余参数定义 ...}# --- 工具实现（Python 函数） ---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: """Writes a file with the given contents.""" with open(file_path, "w") as f: f.write(contents) returnTruedef list_dir(directory_path: str) -> list[str]: """Lists the contents of a directory.""" 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},}# --- Agent 类集成工具 ---from google import genaifrom google.genai import typesclass Agent: def __init__(self, model: str, tools: 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 responseagent = Agent(model="gemini-3-pro-preview", tools=file_tools)response = agent.run( contents="Can you list my files in the current directory?")print(response.function_calls)# 输出: [FunctionCall(name='list_dir', arguments={'directory_path': '.'})]

太棒了！模型成功调用了工具。现在，我们需要将工具执行逻辑添加到Agent类中，并让循环将结果返回给模型。

3：闭合循环（Agent 的诞生）

一个 Agent 的意义不仅在于生成一个工具调用，而在于生成一系列工具调用，将结果返回给模型，然后模型再生成下一个工具调用，如此循环，直到任务完成。

Agent类将处理核心循环：拦截FunctionCall，在客户端执行工具，然后将FunctionResponse发回。我们还添加了SystemInstruction来指导模型的行为。

注意：Gemini 3 使用思维签名（Thought signatures）来在 API 调用中维护推理上下文。你必须将这些签名原封不动地在请求中返回给模型。

# ... 此处省略了步骤 2 的工具和工具定义代码 ... from google import genaifrom google.genai import typesclass Agent: def __init__(self, model: str, tools: dict, system_instruction: str = "You are a helpful assistant."): # ... 初始化代码与步骤 2 相同 ... self.system_instruction = system_instruction def run(self, contents: str | list[dict[str, str]]): # 处理用户输入或函数响应的 parts 列表 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"[Function Call] {tool_call}") # 客户端执行工具 if tool_call.name in self.tools: result = {"result": self.tools[tool_call.name]["function"](**tool_call.args)} else: result = {"error": "Tool not found"} print(f"[Function Response] {result}") # 准备函数响应部分 functions_response_parts.append({ "functionResponse": {"name": tool_call.name, "response": result} }) # 递归调用 run()，将结果返回给模型进行下一步推理 return self.run(functions_response_parts) return responseagent = Agent( model="gemini-3-pro-preview", tools=file_tools, system_instruction="You are a helpful Coding Assistant. Respond like you are Linus Torvalds.")response = agent.run( contents="Can you list my files in the current directory?")print(response.text)# 输出: [Function Call] id=None args={'directory_path': '.'} name='list_dir'# [Function Response] {'result': ['.venv', ... ]}# Linus: There. Your current directory contains: `LICENSE`, ...

刚刚我们成功地构建了第一个功能完备的 Agent。

4：多轮 CLI 代理

现在，我们可以将 Agent 运行在一个简单的命令行接口（CLI）循环中。只需很少的代码，就能创建出高度智能的行为。

# ... 此处省略了 Agent、工具和工具定义代码 ... agent = Agent( model="gemini-3-pro-preview", tools=file_tools, system_instruction="You are a helpful Coding Assistant. Respond like you are Linus Torvalds.")print("Agent ready. Ask it to check files in this directory.")whileTrue: user_input = input("You: ") 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 会阅读函数的文档字符串（docstrings）来理解何时以及如何使用工具。花时间仔细编写这些内容，这本质上是工具的“提示工程”。
返回有意义的错误：不要返回 50 行的 Java 堆栈跟踪。如果工具失败，返回一个清晰的字符串，如错误：文件未找到。您想找 'data.csv' 吗？这样能让 Agent 进行自我修正。
容忍模糊输入：如果模型经常猜错文件路径，请更新你的工具来处理相对路径或模糊输入，而不是仅仅报错。

2. 上下文工程

模型有一个有限的“注意力预算”。管理哪些信息进入上下文对于性能和成本至关重要。

不要“倾倒”数据：不要让工具返回整个 10MB 的数据库表。与其创建get_all_users()，不如创建search_users(query: str)。
即时加载：不要预加载所有数据（传统的 RAG），而是使用即时策略。Agent 应该维护轻量级的标识符（文件路径、ID），并仅在需要时使用工具动态加载内容。
压缩：对于运行时间很长的 Agent，可以总结历史记录，移除旧的上下文或开启新会话。
Agent 记忆：允许 Agent 维护一个存储在上下文窗口之外的笔记或便签本，仅在相关时才将它们拉回。

3. 不要过度工程化

构建复杂的多代理系统是很诱人的。但请不要这样做。

首先最大化单个 Agent 的能力：不要立即构建复杂的系统。Gemini 具备很强的能力，可以在一个提示中处理数十个工具。
逃逸舱口：确保循环可以被停止，例如设置max_iterations中断（比如 15 轮）。
护栏和系统指令：使用system_instruction来为模型设定硬性规则（例如，“您被严格禁止提供超过 50 美元的退款”），或者使用外部分类器。
人机协作（Human-in-the-loop）：对于敏感操作（如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 大模型，还是有基础想冲刺大厂、了解行业趋势，这份资料都能满足你！
现在只需按照提示操作，就能免费领取：