【收藏】AI智能体不再神秘：用Python和LLM循环构建你的第一个智能体-平芜编程栈

本文详细介绍了AI智能体的核心原理及构建方法。AI智能体本质上是一个在循环中运行的大语言模型，配备了可调用的工具，能够动态决定控制流。文章通过四步构建流程：从基础文本生成到工具集成，再到实现闭环迭代，最终实现多轮交互CLI智能体。使用Gemini模型和Python SDK，不到100行代码就能创建具备真实行动能力的AI助手。文章还分享了智能体工程的最佳实践，帮助开发者构建可靠、透明、可控的智能体系统。

一、智能体到底是什么？

传统软件与AI智能体的根本区别在于：传统软件的工作流程是指令式的，遵循预定义路径（步骤 A → B → C）；而智能体则不同，它利用LLM动态决定程序的控制流，以达成用户目标。

一个典型的智能体通常包含以下核心组件：

模型（大脑）：推理引擎，负责处理模糊性问题、规划执行步骤，并判断何时需要外部工具辅助。本文使用的是Gemini模型。
工具（手脚与眼睛）：智能体可执行的函数，用于与外部世界/环境交互（例如网页搜索、读取文件、调用API等）。
上下文/记忆（工作区）：智能体在任意时刻可访问的信息集合，高效管理这些信息的过程被称为“上下文工程”。
循环（生命周期）：一个while循环，让模型能够完成“观察→思考→行动→再观察”的迭代过程，直到任务完成。

几乎所有智能体的“循环”都遵循以下迭代流程：

定义工具：用结构化JSON格式向模型描述可用工具。
调用LLM：将用户提示和工具定义一并发送给模型。
模型决策：模型分析请求后，若需要使用工具，会返回包含工具名称和参数的结构化工具调用指令；若无需工具，则直接生成文本响应。
执行工具（客户端职责）：客户端/应用代码拦截工具调用指令，执行实际的代码或API调用，并捕获执行结果。
响应与迭代：将工具执行结果反馈给模型，模型利用新信息决定下一步操作，要么调用另一个工具，要么生成最终响应。

二、构建智能体：四步进阶

在开始构建前，需完成两项准备工作：

安装Gemini Python SDK：执行命令 pip install google-genai。
设置环境变量：获取GEMINI_API_KEY（可在Google AI Studio中申请），并配置为系统环境变量。

我们将从基础文本生成逐步升级，最终实现功能完备的CLI 智能体，全程使用Gemini 3 Pro和Python SDK。

步骤1：基础文本生成与抽象封装

首先，创建一个简单的 Agent 类，用于与 Gemini 3 进行基本交互，并维护对话历史。

from googleimportgenai from google.genaiimporttypes 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)returnresponse agent=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}")# Output: Berlin, Munich, Cologneresponse2=agent.run(contents="Tell me something about the second city.")print(f"Model: {response2.text}")# Output: Munich is the capital of Bavaria and is known for its Oktoberfest.

此时的智能体只是一个普通聊天机器人，仅能维持对话状态，没有“手脚”（工具），无法与外部环境交互，因此还不是真正的智能体。

步骤2：赋予工具使用能力

要让聊天机器人升级为智能体，需要实现工具使用或函数调用。如果 LLM 认为某个工具可以帮助解决用户的问题，它将返回一个结构化的请求来调用该函数，而不是仅仅返回文本。

以文件操作为例，定义三个工具：read_file、write_file 和 list_dir。每个工具需提供两部分：

工具定义（Schema）：JSON 格式的名称、描述和参数说明；
工具实现（Function）：实际执行的 Python 函数。

最佳实践：在 description 中清晰说明工具的用途和使用场景。模型高度依赖这些信息来决定何时调用哪个工具。

importosimportjson read_file_definition={"name":"read_file","description":"Reads a file and returns its contents.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to the file to read.",}},"required":["file_path"],},}list_dir_definition={"name":"list_dir","description":"Lists the contents of a directory.","parameters":{"type":"object","properties":{"directory_path":{"type":"string","description":"Path to the directory to list.",}},"required":["directory_path"],},}write_file_definition={"name":"write_file","description":"Writes a file with the given contents.","parameters":{"type":"object","properties":{"file_path":{"type":"string","description":"Path to the file to write.",},"contents":{"type":"string","description":"Contents to write to the file.",},},"required":["file_path","contents"],},}def read_file(file_path: str)->dict: with open(file_path,"r")as f:returnf.read()def write_file(file_path: str, contents: str)->bool:"""Writes afilewith the given contents.""" with open(file_path,"w")as f: f.write(contents)returnTrue def list_dir(directory_path: str)->list[str]:"""Lists the contents of a directory.""" full_path=os.path.expanduser(directory_path)returnos.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 googleimportgenai from google.genaiimporttypes 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"]fortoolinself.tools.values()])],)response=self.client.models.generate_content(model=self.model,contents=self.contents,config=config)self.contents.append(response.candidates[0].content)returnresponse agent=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)# Output: [FunctionCall(name='list_dir', arguments={'directory_path': '.'})]

此时模型已能正确识别需求并调用对应工具，但还未执行工具逻辑并将结果反馈给模型，这需要完成“循环”闭环。

步骤3：实现闭环，真正的智能体诞生

智能体的核心价值不在于单次工具调用，而在于能迭代执行“工具调用→结果反馈→新决策”的循环，直到完成任务。需要为智能体添加工具执行逻辑、结果反馈机制，并通过系统指令引导模型行为。

Agent类负责处理核心循环：拦截 FunctionCall，在客户端执行工具，并将 FunctionResponse 返回给模型。此外，还给模型添加了SystemInstruction，以指导模型应如何行动。

注意：Gemini 3使用Thought签名在API调用间维护推理上下文，需将收到的签名原封不动地反馈给模型。

# ... Code for the tools and tool definitions from Step 2 should be here ...from googleimportgenai from google.genaiimporttypes class Agent: def __init__(self, model: str,tools: list[dict], system_instruction: str="You are a helpful assistant."): 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]]):ifisinstance(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"]fortoolinself.tools.values()])],)response=self.client.models.generate_content(model=self.model,contents=self.contents,config=config)self.contents.append(response.candidates[0].content)ifresponse.function_calls: functions_response_parts=[]fortool_callinresponse.function_calls: print(f"[Function Call] {tool_call}")iftool_call.nameinself.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}})returnself.run(functions_response_parts)returnresponse agent=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)# Output: [Function Call] id=None args={'directory_path': '.'} name='list_dir'# [Function Response] {'result': ['.venv', ... ]}# There. Your current directory contains: `LICENSE`,

恭喜！你已成功构建了第一个能自主迭代、使用工具的智能体。

步骤4：多轮交互CLI 智能体

现在可以快速实现一个支持多轮对话的命令行工具，让用户能持续与智能体交互。

# ... Code for the Agent, tools and tool definitions from Step 3 should be here ...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: ")ifuser_input.lower()in['exit','quit']:breakresponse=agent.run(user_input)print(f"Linus: {response.text}\n")

现在，可以持续与智能体对话，让它帮你查看文件、修改代码、分析日志等。

三、智能体工程最佳实践

构建循环很简单，但要让智能体可靠、透明、可控却需要技巧。以下是基于行业顶尖实践的核心原则：

工具定义与用户体验

工具是模型与环境交互的接口，设计质量直接决定智能体的能力：

命名清晰：使用直观名称如search_customer_database，而非模糊的cust_db_v2_query；
描述精准：工具描述是给模型看的文档，务必详尽；
错误友好：避免返回冗长信息，应返回简洁明确的错误信息，方便智能体自我修正；
兼容模糊输入：若模型常输错文件路径，可优化工具支持相对路径、模糊匹配，而非直接报错。

上下文工程

模型的注意力预算有限，合理管理上下文是提升性能、降低成本的关键：

数据精简：不要一次性返回大量数据（如整个数据库表）；
按需加载：无需预加载所有数据（传统RAG模式），智能体应仅维护轻量标识符，需要时通过工具动态加载内容。
压缩优化：对于长时间运行的智能体，可总结对话历史、删除无用上下文或开启新会话，避免上下文窗口溢出。
智能记忆：允许智能体维护外部数据（如本地文件、数据库），存储关键信息，仅在需要时拉回上下文。

避免过度设计

不要盲目追求复杂架构，优先保证稳定性和实用性：

先优化单智能体：Gemini 3能高效处理数十个工具，无需过早引入多智能体架构；
设置安全边界：为循环添加最大迭代次数，避免无限循环。
加入人工干预点：对于敏感操作，在工具执行前暂停循环，要求用户确认。
重视可调试性：记录所有工具调用、参数和结果，通过分析模型推理过程定位问题、优化智能体。

四、总结

构建智能体已不再是一项难以企及的复杂技术，而是一项切实可行的工程任务。正如本文所示，不到 100 行代码，就能拥有一个具备真实行动能力的 AI 助手。

在掌握核心原理后，无需进行重复性的基础开发工作。当前行业内已涌现多款成熟的开源框架（如 LangChain、LlamaIndex、AutoGen 等），能够助力开发者快速构建功能更复杂、运行更稳健的智能体系统。但无论技术架构如何迭代，其核心原则始终在于清晰的工具设计、高效的上下文管理与简洁的循环逻辑。

如何学习大模型 AI ？

由于新岗位的生产效率，要优于被取代岗位的生产效率，所以实际上整个社会的生产效率是提升的。

但是具体到个人，只能说是：

“最先掌握AI的人，将会比较晚掌握AI的人有竞争优势”。

这句话，放在计算机、互联网、移动互联网的开局时期，都是一样的道理。

我在一线互联网企业工作十余年里，指导过不少同行后辈。帮助很多人得到了学习和成长。

我意识到有很多经验和知识值得分享给大家，也可以通过我们的能力和经验解答大家在人工智能学习中的很多困惑，所以在工作繁忙的情况下还是坚持各种整理和分享。但苦于知识传播途径有限，很多互联网行业朋友无法获得正确的资料得到学习提升，故此将并将重要的AI大模型资料包括AI大模型入门学习思维导图、精品AI大模型学习书籍手册、视频教程、实战学习等录播视频免费分享出来。

这份完整版的大模型 AI 学习资料已经上传CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】

为什么要学习大模型？

我国在A大模型领域面临人才短缺,数量与质量均落后于发达国家。2023年，人才缺口已超百万，凸显培养不足。随着AI技术飞速发展，预计到2025年,这一缺口将急剧扩大至400万,严重制约我国AI产业的创新步伐。加强人才培养,优化教育体系,国际合作并进是破解困局、推动AI发展的关键。

大模型入门到实战全套学习大礼包

1、大模型系统化学习路线

作为学习AI大模型技术的新手，方向至关重要。正确的学习路线可以为你节省时间，少走弯路；方向不对，努力白费。这里我给大家准备了一份最科学最系统的学习成长路线图和学习规划，带你从零基础入门到精通！

2、大模型学习书籍&文档

学习AI大模型离不开书籍文档，我精选了一系列大模型技术的书籍和学习文档（电子版），它们由领域内的顶尖专家撰写，内容全面、深入、详尽，为你学习大模型提供坚实的理论基础。

3、AI大模型最新行业报告

2025最新行业报告，针对不同行业的现状、趋势、问题、机会等进行系统地调研和评估，以了解哪些行业更适合引入大模型的技术和应用，以及在哪些方面可以发挥大模型的优势。

4、大模型项目实战&配套源码

学以致用，在项目实战中检验和巩固你所学到的知识，同时为你找工作就业和职业发展打下坚实的基础。

5、大模型大厂面试真题

面试不仅是技术的较量，更需要充分的准备。在你已经掌握了大模型技术之后，就需要开始准备面试，我精心整理了一份大模型面试题库，涵盖当前面试中可能遇到的各种技术问题，让你在面试中游刃有余。

适用人群

第一阶段（10天）：初阶应用

该阶段让大家对大模型 AI有一个最前沿的认识，对大模型 AI 的理解超过 95% 的人，可以在相关讨论时发表高级、不跟风、又接地气的见解，别人只会和 AI 聊天，而你能调教 AI，并能用代码将大模型和业务衔接。

大模型 AI 能干什么？
大模型是怎样获得「智能」的？
用好 AI 的核心心法
大模型应用业务架构
大模型应用技术架构
代码示例：向 GPT-3.5 灌入新知识
提示工程的意义和核心思想
Prompt 典型构成
指令调优方法论
思维链和思维树
Prompt 攻击和防范
…

第二阶段（30天）：高阶应用

该阶段我们正式进入大模型 AI 进阶实战学习，学会构造私有知识库，扩展 AI 的能力。快速开发一个完整的基于 agent 对话机器人。掌握功能最强的大模型开发框架，抓住最新的技术进展，适合 Python 和 JavaScript 程序员。

为什么要做 RAG
搭建一个简单的 ChatPDF
检索的基础概念
什么是向量表示（Embeddings）
向量数据库与向量检索
基于向量检索的 RAG
搭建 RAG 系统的扩展知识
混合检索与 RAG-Fusion 简介
向量模型本地部署
…

第三阶段（30天）：模型训练

恭喜你，如果学到这里，你基本可以找到一份大模型 AI相关的工作，自己也能训练 GPT 了！通过微调，训练自己的垂直大模型，能独立训练开源多模态大模型，掌握更多技术方案。

到此为止，大概2个月的时间。你已经成为了一名“AI小子”。那么你还想往下探索吗？

为什么要做 RAG
什么是模型
什么是模型训练
求解器 & 损失函数简介
小实验2：手写一个简单的神经网络并训练它
什么是训练/预训练/微调/轻量化微调
Transformer结构简介
轻量化微调
实验数据集的构建
…

第四阶段（20天）：商业闭环

对全球大模型从性能、吞吐量、成本等方面有一定的认知，可以在云端和本地等多种环境下部署大模型，找到适合自己的项目/创业方向，做一名被 AI 武装的产品经理。

硬件选型
带你了解全球大模型
使用国产大模型服务
搭建 OpenAI 代理
热身：基于阿里云 PAI 部署 Stable Diffusion
在本地计算机运行大模型
大模型的私有化部署
基于 vLLM 部署大模型
案例：如何优雅地在阿里云私有部署开源大模型
部署一套开源 LLM 项目
内容安全
互联网信息服务算法备案
…

学习是一个过程，只要学习就会有挑战。天道酬勤，你越努力，就会成为越优秀的自己。

如果你能在15天内完成所有的任务，那你堪称天才。然而，如果你能完成 60-70% 的内容，你就已经开始具备成为一名大模型 AI 的正确特征了。