100行代码构建AI智能体：从工具调用原理到本地自动化实战

1. 项目概述：从零理解AI智能体的本质

如果你能看懂大约100行Python代码，那么你就能理解什么是AI智能体。这不是一句夸张的宣传语，而是我在过去一年里，从零开始构建和部署多个生产级AI应用后，对“智能体”这个概念最直接的体会。很多刚接触这个领域的朋友，一听到“智能体”、“Agentic AI”、“工具调用”这些词，就觉得高深莫测，仿佛需要掌握一套全新的复杂框架。但事实是，其核心思想异常简单：让大语言模型（LLM）学会使用工具，并自主决策何时使用、如何使用，以完成一个多步骤的任务。

nanoAgent这个项目，就是这种思想最纯粹的体现。它没有复杂的依赖，没有臃肿的架构，仅仅用大约100行代码，就实现了一个能够与你的操作系统交互的智能体。它能执行bash命令、读取文件、写入文件，就像一个坐在你电脑里的、会编程的助手。这个项目的价值不在于其功能的强大，而在于它像一把手术刀，精准地剖开了“智能体”华丽的外壳，让你能一眼看到其最核心的循环逻辑：思考 -> 行动 -> 观察 -> 再思考。

对于开发者、运维工程师，或者任何希望自动化处理本地任务的用户来说，nanoAgent是一个绝佳的起点。它让你无需被LangChain、AutoGen等重型框架的抽象层所困扰，直接在最底层理解LLM如何与外部世界互动。接下来，我将带你彻底拆解这个微型智能体，从环境搭建、核心原理到实战扩展，让你不仅会用，更能理解其每一个设计决策背后的“为什么”。

2. 核心原理深度拆解：工具调用的“心脏”是如何跳动的？

在深入代码之前，我们必须先建立正确的认知模型。很多人误以为“工具调用”是大模型的新能力，其实不然。从GPT-3.5-Turbo开始，OpenAI就通过“函数调用”功能提供了这种能力。nanoAgent所依赖的，正是这个成熟且标准化的接口。

2.1 工具调用的本质：一场结构化的对话

你可以把工具调用想象成一场LLM和你预先定义好的“工具库”之间的结构化对话。传统对话是自由文本，而工具调用则引入了严格的“格式合同”。

1. 定义合同（Tools）：你告诉LLM：“我这里有几个工具，这是它们的名字、描述和参数格式。” 在nanoAgent中，就是execute_bash，read_file，write_file这三个工具的定义。
2. 提出请求（User Query）：用户给出一个任务，比如“列出当前目录下所有的Python文件并统计行数”。
3. 模型决策（LLM Reasoning）：LLM分析这个任务。它发现需要先“列出文件”，这对应execute_bash工具（执行ls *.py或find命令）。然后需要“统计行数”，这可能需要再次调用execute_bash（执行wc -l命令）。关键点在于，LLM此时并不真正执行命令，它只是在“思考”并“规划”。
4. 返回调用指令（Function Call）：LLM的输出不再是自然语言，而是一个或多个结构化的“工具调用请求”。这个请求严格遵循第一步定义的合同格式，包含工具名和具体的参数。
5. 本地执行（Local Execution）：你的程序（nanoAgent）接收到这个调用请求，在自己的运行环境中安全地执行对应的Python函数。比如，它真的去运行subprocess.run([“ls”, “*.py”])。
6. 反馈结果（Tool Result）：执行完成后，将结果（标准输出、错误信息、文件内容等）封装好，作为一次新的“对话消息”发送回LLM。
7. 循环往复（Loop）：LLM收到上一步工具的执行结果，结合之前的对话历史，再次分析：“哦，文件列表拿到了。现在我需要统计每个文件的行数。” 于是它可能发起下一个工具调用。这个过程循环进行，直到LLM认为任务已完成为止，此时它才会输出最终的自然语言答案给用户。

这个循环，就是nanoAgentagent.py中那个for循环所做的事情。它简单，但完整地勾勒出了所有智能体框架最核心的工作流。

2.2 nanoAgent的三大工具解析

为什么是这三个工具？因为它们构成了与本地系统交互的最小完备集。

• execute_bash：这是通往整个操作系统的“万能钥匙”。通过它，智能体可以运行任何已安装的命令行工具（git,grep,curl,python等），从而获得无限的能力扩展。这是智能体“行动”的主要手段。
• read_file：这是智能体的“眼睛”。它允许模型查看本地文件的内容，获取上下文信息。例如，用户说“帮我修改这个脚本”，智能体需要先读取脚本内容才能理解要改什么。
• write_file：这是智能体的“手”。它允许模型将生成或修改后的内容持久化到磁盘。这是完成创建、编辑文件类任务的必备能力。

这三个工具的组合，使得智能体具备了感知（读）、行动（执行）、创造（写）的基本能力，足以应对大量自动化场景。

注意：安全是首要考量。execute_bash是一把双刃剑。在nanoAgent的简单实现中，它直接执行命令，这在学习阶段可以接受，但在生产环境或处理不可信输入时是极度危险的。一个严肃的智能体必须包含严格的命令白名单、沙箱环境或用户确认机制。本文后续的“进阶实战”部分会探讨如何加固。

3. 从零开始：环境配置与首次运行实录

让我们暂时忘掉那些复杂的概念，亲手让这个智能体“活”起来。这个过程本身，就是理解其运作方式的最佳途径。

3.1 项目获取与依赖安装

首先，你需要一个Python环境（建议3.8以上）。通过Git克隆项目是最直接的方式：

git clone https://github.com/sanbuphy/nanoAgent.git cd nanoAgent

项目依赖极其精简，只有openai这个官方库。使用pip安装即可：

pip install -r requirements.txt # 或者直接安装 pip install openai

3.2 关键一步：配置API密钥与环境

智能体需要“大脑”，也就是一个大语言模型。nanoAgent默认使用OpenAI的API。你需要一个有效的OpenAI API密钥。

对于macOS/Linux用户，在终端中执行：

export OPENAI_API_KEY='sk-your-actual-key-here' # 可选：如果你使用其他兼容OpenAI API的服务（如Azure OpenAI, 国内的一些代理服务） export OPENAI_BASE_URL='https://api.your-service.com/v1' # 可选：指定模型，默认是 gpt-4o-mini，性价比很高 export OPENAI_MODEL='gpt-4o-mini'

对于Windows用户（PowerShell）：

$env:OPENAI_API_KEY='sk-your-actual-key-here' $env:OPENAI_BASE_URL='https://api.your-service.com/v1' $env:OPENAI_MODEL='gpt-4o-mini'

实操心得：环境变量的持久化上述命令设置的环境变量只在当前终端会话有效。关闭终端后就失效了。为了永久配置，我通常这样做：

• macOS/Linux：将export命令添加到~/.zshrc或~/.bashrc文件末尾。
• Windows：在“系统属性 -> 高级 -> 环境变量”中新建用户变量。 更安全的做法是使用.env文件配合python-dotenv库来管理密钥，避免密钥硬编码或泄露在历史命令中。nanoAgent为了极简没有引入这个依赖，但你在自己的项目中强烈建议使用。

3.3 首次对话：让智能体开始工作

配置完成后，你就可以像和助手对话一样使用它了。打开终端，进入项目目录，尝试以下命令：

# 示例1：让它探索当前环境 python agent.py "告诉我当前目录的路径，并列出所有文件和文件夹" # 示例2：一个简单的文件操作任务 python agent.py "创建一个名为test.py的文件，内容是一个打印'Hello from nanoAgent'的Python程序" # 示例3：组合任务 python agent.py "找出当前目录下所有的.md文件，并告诉我它们各自有多少行"

运行后，你会看到终端里开始滚动输出。这不是简单的脚本执行，而是智能体在“思考”的痕迹。它会显示每次调用工具的名称和参数，以及工具返回的结果。最后，它会给出一个总结性的回答。

第一次运行可能遇到的问题：

• 错误：ModuleNotFoundError: No module named 'openai'解决方法：确认已正确执行pip install -r requirements.txt。
• 错误：AuthenticationError解决方法：确认OPENAI_API_KEY环境变量已正确设置且密钥有效。可以通过echo $OPENAI_API_KEY（Linux/macOS）或echo %OPENAI_API_KEY%（Windows CMD）来检查。
• 响应缓慢或超时解决方法：检查网络连接。如果使用OPENAI_BASE_URL，请确认该端点可用且响应正常。初次调用由于模型加载可能稍慢，后续会快很多。

当你看到智能体成功地列出了文件、创建了脚本，你就已经完成了与一个真正AI智能体的第一次交互。这个过程看似简单，但其背后正是前述“思考-行动”循环在默默工作。

4. 代码逐行精讲：深入100行核心逻辑

理解了原理，体验了效果，现在让我们打开agent.py，像阅读一篇优美的散文一样，逐行分析这100行代码是如何编织出智能体的灵魂的。这是将知识内化的关键一步。

4.1 工具定义：告诉模型“你能做什么”

代码的开头部分，定义了智能体可以使用的工具列表tools。每个工具都是一个字典，遵循OpenAI的函数调用规范。

tools = [ { "type": "function", "function": { "name": "execute_bash", "description": "Execute a bash command and return its output.", "parameters": { "type": "object", "properties": { "command": {"type": "string", "description": "The bash command to execute."} }, "required": ["command"], "additionalProperties": False } } }, # ... 类似地定义 read_file 和 write_file ]

关键点解析：

• description字段至关重要：这是LLM理解工具用途的唯一依据。描述必须清晰、准确。例如，execute_bash的描述告诉模型，这个工具用于“执行bash命令并返回输出”。模型会根据这个描述来决定是否以及如何调用它。
• parameters定义了“输入合同”：它严格规定了调用这个工具时需要传入什么参数，以及参数的类型。additionalProperties: False意味着不允许传入定义之外的参数，这增加了安全性。
• 为什么是JSON Schema？因为OpenAI的API要求工具定义必须遵循JSON Schema格式。这是一种机器可读的、标准化的数据验证规范，确保模型输出的参数结构是 predictable（可预测的）。

4.2 函数实现：定义“具体怎么做”

工具定义只是“说明书”，还需要有对应的Python函数来执行实际工作。

def execute_bash(command: str) -> str: """执行bash命令并返回输出。""" try: result = subprocess.run(command, shell=True, capture_output=True, text=True) if result.returncode == 0: return result.stdout else: return f"Command failed with return code {result.returncode}:\n{result.stderr}" except Exception as e: return f"Error executing command: {e}" def read_file(filepath: str) -> str: # ... 读取文件内容 def write_file(filepath: str, content: str) -> str: # ... 写入文件内容

关键点与避坑指南：

• shell=True的风险：execute_bash中使用了shell=True，这允许使用管道|、重定向>等shell特性，很方便。但这也是最大的安全漏洞，因为它可能执行诸如rm -rf /或从网络下载恶意脚本的命令。在个人可信环境用于学习可以，但绝对不要将此代码直接暴露给不可信的用户输入。
• 错误处理：每个函数都包含了try...except块，并将错误信息作为字符串返回。这是智能体框架设计的最佳实践。不要把异常抛给主循环导致程序崩溃，而是将错误信息反馈给LLM。LLM可以理解错误信息，并据此调整后续策略。例如，如果read_file因文件不存在而失败，LLM可能会先调用execute_bash(“ls”)来查看目录结构。
• 返回值类型：所有工具函数都返回str类型。这是因为工具执行结果需要被拼接到对话历史中，传递给模型。保持纯文本格式是最通用和兼容的做法。

4.3 智能体主循环：驱动“思考-行动”引擎

这是整个项目的核心，一个简洁而强大的循环。

def run_agent(task: str, max_iterations: int = 10): client = OpenAI() # 自动从环境变量读取 API_KEY 和 BASE_URL model = os.getenv("OPENAI_MODEL", "gpt-4o-mini") messages = [{"role": "user", "content": task}] available_functions = { "execute_bash": execute_bash, "read_file": read_file, "write_file": write_file, } for i in range(max_iterations): # 1. 调用模型，传入对话历史和工具定义 response = client.chat.completions.create( model=model, messages=messages, tools=tools, tool_choice="auto", # 让模型自己决定是否、何时调用工具 ) message = response.choices[0].message # 2. 检查模型是否想调用工具 if not message.tool_calls: # 如果没有工具调用，说明任务完成或模型决定直接回答 return message.content # 3. 处理模型发起的每一个工具调用 for tool_call in message.tool_calls: function_name = tool_call.function.name function_to_call = available_functions.get(function_name) if not function_to_call: # 处理未知工具调用（稳健性处理） tool_result = f"Error: Unknown function {function_name}." else: try: # 解析模型传来的参数（JSON字符串） function_args = json.loads(tool_call.function.arguments) # 执行本地函数 function_response = function_to_call(**function_args) tool_result = str(function_response) except json.JSONDecodeError: # 处理参数解析错误 tool_result = f"Error: Invalid JSON arguments for {function_name}." except Exception as e: # 处理函数执行过程中的其他错误 tool_result = f"Error executing {function_name}: {e}" # 4. 将工具执行结果作为一条新消息追加到历史中 messages.append({ "role": "tool", "tool_call_id": tool_call.id, # 关键：关联本次调用 "content": tool_result, }) # 5. 将模型刚才提出的工具调用请求也加入历史，保持对话连贯性 messages.append(message) # 如果循环达到最大次数仍未结束，返回超时信息 return f"Agent stopped after reaching max iterations ({max_iterations})."

循环流程详解：

1. 初始化：准备好OpenAI客户端、对话历史（初始只有用户任务）和工具函数映射表。
2. 模型推理：将当前对话历史和工具定义发送给LLM。tool_choice=”auto”表示把决定权交给模型。
3. 决策判断：检查模型的回复中是否包含tool_calls。如果没有，说明模型认为可以直接给出最终答案，循环结束。
4. 工具执行：如果模型要求调用工具，则遍历每一个调用请求： a. 根据工具名找到对应的本地Python函数。 b. 将模型传来的参数（JSON字符串）解析成Python字典。 c. 调用本地函数，并捕获结果或错误。 d.关键步骤：将执行结果封装成一条role: “tool”的消息，并附上对应的tool_call_id，追加到对话历史。这个id是OpenAI API用来匹配调用和响应的唯一标识，必须正确传递。
5. 历史更新：将模型刚才发出的包含工具调用请求的消息(message)也追加到历史中。这样，下一轮循环时，模型就能看到“我上次提出了这些工具调用”，以及“这些调用的结果是这些”，从而进行下一步推理。
6. 循环继续：回到步骤2，开始下一轮“思考-行动”。max_iterations参数防止任务陷入无限循环。

这个不足50行的循环，就是当今所有复杂智能体框架的“原子核”。理解它，你就掌握了智能体最底层的运作机制。

5. 进阶实战：从玩具到工具的改造指南

nanoAgent是一个完美的教学原型，但直接用于生产环境存在风险。本部分，我将分享如何基于其核心思想，一步步将其加固、扩展，变成一个真正可靠、有用的自动化助手。

5.1 安全性加固：给“万能钥匙”加上锁

首要任务是解决execute_bash的安全问题。我们有几种策略：

策略一：命令白名单机制只允许执行预定义的安全命令。这是最严格的方式。

ALLOWED_COMMANDS = [‘ls’, ‘pwd’, ‘cat’, ‘grep’, ‘find’, ‘wc’, ‘head’, ‘tail’] ALLOWED_PREFIXES = [‘git status’, ‘git log’] # 允许特定前缀的命令 def safe_execute_bash(command: str) -> str: parts = command.strip().split() base_cmd = parts[0] if parts else “” # 检查是否在白名单中 if base_cmd not in ALLOWED_COMMANDS: # 或者检查是否以允许的前缀开头 if not any(command.startswith(prefix) for prefix in ALLOWED_PREFIXES): return f”Error: Command ‘{base_cmd}’ is not allowed for security reasons.” # 进一步参数过滤，防止注入，例如禁止 ‘;’, ‘&&’, ‘rm’, ‘> /dev/null’ 等危险字符或模式 dangerous_patterns = [‘;’, ‘&&’, ‘||’, ‘rm ‘, ‘mkfs’, ‘dd ‘, ‘> /dev/‘] for pattern in dangerous_patterns: if pattern in command: return f”Error: Command contains potentially dangerous pattern ‘{pattern}’.” # 安全执行 return execute_bash(command) # 调用原始函数

策略二：沙箱环境执行使用容器或轻量级虚拟化技术（如docker run --rm alpine）来隔离命令执行环境。

import docker # 需要安装 docker-py def docker_execute_bash(command: str) -> str: client = docker.from_env() try: # 在一个干净的、无特权的容器中执行命令 container = client.containers.run( “alpine:latest”, f”sh -c ‘{command}'”, remove=True, # 运行后自动删除容器 stdout=True, stderr=True ) return container.decode(‘utf-8’) except docker.errors.ContainerError as e: return f”Container error: {e.stderr.decode(‘utf-8’)}” except Exception as e: return f”Docker error: {e}”

策略三：交互式确认（适用于半自动化场景）对于高风险操作，让智能体先提出计划，由用户确认后再执行。

def interactive_agent(task: str): # … 初始化 … for i in range(max_iterations): # … 调用模型 … if message.tool_calls: for tool_call in message.tool_calls: if tool_call.function.name == “execute_bash”: args = json.loads(tool_call.function.arguments) cmd = args[“command”] # 判断是否为高风险命令 if is_high_risk(cmd): user_input = input(f”Agent wants to execute: {cmd}\nProceed? (y/N): “) if user_input.lower() != ‘y’: tool_result = “User denied execution.” else: tool_result = execute_bash(cmd) else: tool_result = execute_bash(cmd) # … 处理其他工具 … # … 更新消息历史 …

在实际项目中，我通常会结合使用白名单+模式过滤作为第一道防线，对于需要更高灵活性的场景，则提供沙箱环境。交互式确认则适合在关键的生产部署环节使用。

5.2 功能扩展：打造你的专属智能体工具箱

三个基础工具远远不够。我们可以轻松地为其添加新工具，从而扩展智能体的能力边界。

示例：添加一个“网络请求”工具让智能体能够获取网页内容或调用API。

import requests def fetch_url(url: str) -> str: “”“获取指定URL的内容。”“” try: headers = {‘User-Agent’: ‘nanoAgent/1.0’} response = requests.get(url, headers=headers, timeout=10) response.raise_for_status() # 如果状态码不是200，抛出异常 return response.text[:5000] # 限制返回长度，避免上下文爆炸 except requests.exceptions.RequestException as e: return f”Error fetching URL: {e}” # 将新工具添加到 tools 列表和 available_functions 字典中 tools.append({ “type”: “function”, “function”: { “name”: “fetch_url”, “description”: “Fetch the content of a given URL (e.g., a webpage or API endpoint).”, “parameters”: { “type”: “object”, “properties”: { “url”: {“type”: “string”, “description”: “The full URL to fetch.”} }, “required”: [“url”], “additionalProperties”: False } } }) available_functions[“fetch_url”] = fetch_url

现在，你的智能体就可以执行这样的任务了：python agent.py “去GitHub上看看nanoAgent项目最新的README里写了什么，然后总结一下。”模型会先调用fetch_url获取页面内容，再进行分析总结。

其他有用的工具创意：

• search_web: 封装一个搜索引擎的API（如SerperDev、Google Programmable Search），让智能体能获取实时信息。
• query_database: 连接到一个SQLite或PostgreSQL数据库，执行安全的查询。
• send_email: 通过SMTP发送邮件。
• get_weather: 调用天气API。
• calculate: 一个安全的数学表达式计算器（避免eval，使用ast.literal_eval或numexpr）。

扩展的核心原则：

1. 清晰的描述：工具函数的description字段要足够详细，让LLM能准确理解其用途和适用场景。
2. 稳健的实现：做好错误处理，永远返回字符串格式的结果。
3. 安全的输入：对输入参数进行验证和清理，防止注入攻击。

5.3 工程化与性能优化

当智能体变得复杂，我们需要考虑更多工程问题。

1. 上下文长度管理（Context Window Management）OpenAI的模型有上下文长度限制（如GPT-4o是128K）。每次工具调用和结果都会追加到对话历史中，长时间运行的任务可能耗尽上下文。

• 策略：实现一个“摘要”或“遗忘”机制。当历史消息超过一定长度（如8000 tokens）时，可以尝试让模型自己总结之前的对话关键点，然后用这个总结替换掉旧的历史，只保留最近几次交互的原始消息。

2. 异步执行（Asynchronous Execution）如果工具调用涉及网络IO（如fetch_url）或长时间运行的计算，同步执行会阻塞主循环。

• 策略：使用asyncio库重构主循环和工具函数。将client.chat.completions.create和工具调用改为异步操作，可以大幅提升处理多个并行任务或慢速工具的效率。

3. 持久化与状态管理（Persistence）当前的智能体是无状态的，每次运行都是全新的会话。

• 策略：将会话历史（messages列表）保存到数据库或文件。可以为每个会话分配一个唯一ID。这样用户可以说“继续我们刚才的对话”，智能体就能加载之前的状态继续工作。

4. 更复杂的任务规划与验证基础循环依赖于模型自身的规划能力。对于极其复杂、多分支的任务，模型可能“迷失”。

• 策略：引入更高级的规划机制，如“思维树”（Tree of Thoughts）或“ReAct”（Reasoning + Acting）模式的显式实现。在调用工具前，先让模型输出一个步骤规划，用户或系统可以对此进行验证或调整。

6. 常见问题与实战排错指南

在实际使用和改造nanoAgent的过程中，你一定会遇到各种问题。这里我整理了最常见的一些坑和解决方法，希望能帮你节省大量调试时间。

6.1 模型不调用工具，直接回答

现象：你给了一个明显需要操作文件系统的任务，比如“创建文件”，但模型直接回复“你可以使用touch命令创建文件”，而不是去调用write_file工具。

原因与排查：

1. 工具描述不清：检查tools列表中每个工具的description字段。描述必须清晰、无歧义，并明确说明工具的用途。例如，“Write content to a file”就比“Handle files”要好得多。
2. 系统提示词缺失：nanoAgent没有显式的系统提示词（role: “system”）。有时模型需要更明确的指令。你可以在messages列表的开头加入一条系统消息：

   messages = [ {“role”: “system”, “content”: “You are a helpful assistant that can perform actions on the user’s computer by using provided tools. When the user asks you to do something that requires using a tool (like reading a file, running a command, or writing a file), you MUST use the appropriate tool. Do not just describe how to do it.”}, {“role”: “user”, “content”: task} ]

3. 模型能力问题：尝试更换更强的模型，如从gpt-4o-mini切换到gpt-4o或gpt-4-turbo。更强大的模型在工具调用遵循指令方面通常表现更好。

6.2 工具调用参数错误或格式不对

现象：模型发起了工具调用，但参数解析失败（json.JSONDecodeError），或者参数名与函数定义不匹配。

原因与排查：

1. JSON Schema定义不匹配：仔细核对工具定义中的parameters与工具函数实际接受的参数。名称、类型必须完全一致。required字段列出了哪些参数是必须的。
2. 模型“幻觉”：有时模型会生成不符合Schema的JSON。nanoAgent的代码已经处理了JSONDecodeError，这是一个好的实践。你可以将错误信息返回给模型，它通常会纠正自己。
3. 使用更严格的模式：在client.chat.completions.create调用中，可以尝试设置tool_choice={“type”: “function”, “function”: {“name”: “specific_tool_name”}}来强制模型使用某个工具，但这会限制灵活性。更好的做法是依靠清晰的描述和系统提示。

6.3 智能体陷入无限循环或无效操作

现象：智能体在一个简单任务上反复调用工具，始终无法完成，直到达到max_iterations限制。

原因与排查：

1. 任务歧义或不可完成：例如，用户要求“删除不存在的文件”。模型调用execute_bash(“rm nonexistent.txt”)，返回“文件不存在”的错误。模型看到错误后，可能再次尝试同样的操作。需要在工具函数中返回更明确的错误信息，帮助模型理解失败原因。
2. 上下文混淆：在长对话中，模型可能忘记了最初的目标。确保任务指令清晰。对于复杂任务，可以尝试让模型在每一步输出一个简短的“当前目标”或“下一步计划”，这有助于它自我纠偏。
3. 降低max_iterations：对于简单任务，将max_iterations设为3-5就足够了。这可以防止资源浪费，并快速暴露逻辑问题。

6.4 性能与成本优化

现象：处理复杂任务速度慢，API调用费用高。

优化策略：

1. 选择性价比模型：gpt-4o-mini在成本、速度和能力上取得了很好的平衡，非常适合此类智能体应用。对于更复杂的推理，再考虑gpt-4o。
2. 精简上下文：定期清理对话历史中不必要的中间步骤。只保留最重要的工具调用和结果。前述的“摘要”机制对此有帮助。
3. 批量处理工具调用：如果模型在一次响应中发起了多个独立的工具调用（例如，同时读取多个文件），可以考虑使用asyncio并发执行它们，而不是串行，以缩短总耗时。
4. 设置超时和重试：为API调用和工具执行添加超时机制，并实现简单的重试逻辑（特别是对于网络相关的工具），提高整体鲁棒性。

6.5 与其他框架的对比与选型

你可能会问，有了LangChain、LlamaIndex、AutoGen这些成熟框架，为什么还要从nanoAgent开始？

• LangChain：功能极其丰富，抽象层次高，学习曲线陡峭。当你需要快速构建一个包含大量预制组件（文档加载器、向量存储、复杂链）的应用时，它是很好的选择。但它的抽象有时会掩盖底层原理。
• LlamaIndex：专注于数据索引和检索，是构建RAG（检索增强生成）应用的利器。如果你的智能体核心是查询私有知识库，它是首选。
• AutoGen：专注于多智能体协作，适合模拟多个角色对话、分工解决复杂问题的场景。
• nanoAgent (及类似理念的简单实现)：你的最佳学习工具和轻量级解决方案原型。它让你100%掌控流程，理解每一行代码在做什么。当你的需求只是“让LLM使用几个简单的本地工具”时，一个几百行的自定义脚本往往比引入一个重型框架更简洁、更可控、更易于调试。

我的建议是：从nanoAgent这样的极简实现入门，彻底理解核心循环。然后，当你的项目需求超出了这个简单循环能优雅处理的范围时（例如需要复杂的记忆管理、流式输出、多智能体协调），再自然地过渡到上述框架，此时你就能清晰地理解框架在为你解决什么问题。

通过这六个部分的拆解，我们从概念到代码，从使用到改造，完整地遍历了一个AI智能体的生命周期。nanoAgent这100行代码，就像一幅清晰的解剖图，让我们看到了智能体技术跳动的心脏。掌握它，你就拥有了在AI自动化浪潮中构建自己工具的最基础、也最强大的能力。