从零构建轻量级AI代理框架：核心原理、工具系统与生产实践-平芜编程栈

1. 项目概述：当“瘦身”的AI代理遇见开源协作

最近在GitHub上闲逛，发现了一个挺有意思的项目：nvtien547/lean-agentic。光看这个名字，就透着一股“极简”和“务实”的味道。lean这个词，在软件开发领域，尤其是敏捷和DevOps圈子里，几乎等同于“高效”、“无浪费”、“价值驱动”。而agentic，显然是“Agent”（智能代理）的形容词形式。所以，这个项目大概率是关于如何构建一个“精益的”、“轻量级的”AI智能代理框架或工具集。

作为一名长期在AI应用层摸爬滚打的从业者，我对这类项目特别敏感。因为现在市面上关于AI Agent的讨论和框架太多了，从LangChain、AutoGen这类功能庞大的“全家桶”，到各种宣称能解决特定问题的“微框架”，让人眼花缭乱。但很多框架为了追求功能的全面性，引入了大量依赖，学习曲线陡峭，部署复杂，对于想快速验证一个想法、或者构建一个轻量级自动化流程的开发者来说，显得有些“杀鸡用牛刀”。lean-agentic的出现，很可能就是瞄准了这个痛点：它不追求大而全，而是追求小而美、易上手、易集成。

这个项目由开发者nvtien547创建并开源。从命名习惯看，这像是一个个人或小团队的成果。这类项目往往更聚焦于解决实际开发中遇到的具体问题，代码风格和设计哲学会更贴近一线开发者的直觉。对于想要深入理解AI Agent核心运作机制，或者希望在自己的项目中快速嵌入一个可定制、可控制的智能体模块的工程师来说，研究这样的项目价值巨大。它剥离了那些繁复的抽象层，让我们能更直接地触及智能体决策、工具调用、记忆管理等核心逻辑的“骨骼”。

接下来，我将基于对开源AI Agent生态的观察和项目命名、结构的合理推测，为你深度拆解一个典型的“精益AI代理”项目可能涵盖的核心设计思路、关键技术选型、实操搭建步骤以及那些在官方文档里不会写的“踩坑”经验。我们的目标不是复刻某一个特定文件，而是理解这类项目的通用范式，并能够将其思想应用到自己的工作中。

2. 核心设计哲学与架构拆解

2.1 何为“精益”（Lean）？在AI Agent语境下的再定义

在制造业和软件工程中，“精益”的核心是消除一切不创造价值的浪费。将其映射到AI Agent框架的设计上，意味着我们需要审视框架的每一个组件：

依赖的浪费：是否引入了不必要的第三方库？一个简单的HTTP请求，是用庞大的requests还是Python标准库的urllib？序列化是用pydantic还是dataclasses甚至简单的字典？lean-agentic的选择倾向一定是：在满足功能、确保可维护性的前提下，依赖最少化。
抽象的浪费：是否为了“设计模式”而过度抽象？一个清晰的、线性的工作流，是否真的需要被包装成复杂的“Chain”、“Pipeline”或“Orchestrator”？精益框架可能更倾向于使用简单的函数组合、状态机或清晰定义的类方法来组织逻辑，让执行路径一目了然。
配置的浪费：是否需要编写冗长的YAML或JSON配置文件来定义简单的行为？或许，用Python代码本身作为配置（Configuration as Code）是更“精益”的选择，因为它能直接利用语言的表达能力和静态检查。
通信的浪费：在多智能体场景中，通信开销是否过大？是采用重量级的消息队列，还是简单的内存事件总线、甚至直接的函数调用？精益框架会在智能体协作的复杂度和通信效率之间寻找最佳平衡点。

基于此，一个精益AI代理框架的架构目标可以概括为：用最少的代码和依赖，清晰暴露AI代理的核心循环（Perceive-Think-Act），并提供恰到好处的扩展点。

2.2 推测性架构蓝图

虽然无法看到nvtien547/lean-agentic的具体代码，但我们可以勾勒出一个符合其精神的典型架构。这个架构通常包含以下核心层：

代理核心层：这是大脑。包含Agent基类，定义了run、step等核心方法。它持有：
- LLM客户端：与大型语言模型（如OpenAI GPT、 Anthropic Claude、本地部署的Llama等）交互的轻量级封装。这里的关键是“轻量级”，可能只处理最基本的HTTP请求、错误重试和响应解析，而不是封装所有高级参数。
- 记忆系统：负责存储和检索对话历史、工具执行结果等。精益框架可能不会实现复杂的向量数据库记忆，而是提供基于列表的短期记忆和可插拔的长期记忆接口（比如连接到一个外部的Redis或SQLite）。
- 推理循环：控制“感知-思考-行动”的循环。代码会非常直白，可能就是一个while循环，在循环内调用LLM、解析输出、执行工具、更新状态。
工具层：这是手脚。Tool基类定义了工具的统一接口（name,description,run方法）。框架会提供一个内置的常用工具集（如网络搜索、文件读写、计算器），但更重要的是让用户能够以极简的方式定义自己的工具——通常只需要装饰一个函数。
编排与执行层：如何运行智能体？可能是简单的同步执行，也可能是基于asyncio的异步执行以支持并发。对于多智能体，可能提供一个简单的Coordinator或GroupChat类，管理智能体间的消息路由。
输入/输出适配层：如何与外部世界交互？框架可能不预设Web服务器或GUI，而是提供清晰的InputAdapter和OutputAdapter抽象，让开发者可以轻松将其接入命令行、FastAPI服务器、Slack机器人等。

这个架构的“精益”之处在于，每一层都职责单一，层与层之间通过简单的接口（如Python的Protocol或ABC）耦合，没有复杂的中间件，整个框架的启动时间可能只需要几毫秒。

3. 关键技术选型与实现细节

3.1 LLM集成：保持灵活与轻便

在精益框架中，LLM集成的设计原则是“提供默认，但不捆绑”。

# 一个推测的精益框架LLM客户端可能长这样 class LeanLLMClient: def __init__(self, model: str, api_key: str = None, base_url: str = None): self.model = model self.api_key = api_key self.base_url = base_url or “https://api.openai.com/v1” # 默认OpenAI，但可替换 async def generate(self, messages: List[Dict], **kwargs) -> str: """发起一个简单的聊天补全请求""" headers = {“Authorization”: f“Bearer {self.api_key}”} payload = { “model”: self.model, “messages”: messages, **kwargs # 透明传递温度、max_tokens等参数 } async with aiohttp.ClientSession() as session: async with session.post(f“{self.base_url}/chat/completions”, json=payload, headers=headers) as resp: resp.raise_for_status() data = await resp.json() return data[“choices”][0][“message”][“content”]

为什么这么设计？

避免供应商锁定：通过允许自定义base_url，这个客户端可以轻松对接OpenAI兼容的API（如Azure OpenAI, Together AI, 或本地部署的vLLM服务），而无需修改框架核心代码。
依赖最小化：使用aiohttp或httpx进行异步HTTP请求，而不是引入整个官方的、可能更重的SDK。
透明性：**kwargs允许高级用户直接传递任何模型支持的参数，框架不做过多拦截和转换。

注意：在实际生产中，你需要在这里添加重试逻辑（针对速率限制和临时错误）、超时控制、以及更完善的错误处理。但框架的初始版本可能故意保持简单，让用户根据自身需求去扩展。

3.2 工具系统：极简的赋能方式

工具是Agent能力的延伸。精益框架的工具系统，追求的是定义工具的“零样板代码”。

# 方式一：使用装饰器（非常Pythonic，符合精益思想） from lean_agentic import tool @tool(name=“get_weather”, description=“获取指定城市的当前天气”) async def get_weather(city: str) -> str: # 这里实现实际的天气API调用 return f“{city}的天气是晴朗，25摄氏度。” # 方式二：继承基类（更面向对象，适合复杂工具） from lean_agentic import Tool class CalculatorTool(Tool): name = “calculator” description = “执行数学计算” async def run(self, expression: str) -> str: try: # 警告：使用eval有安全风险，此处仅为示例。生产环境应使用安全评估库如`asteval`。 result = eval(expression) return str(result) except Exception as e: return f“计算错误：{e}”

关键设计点：

自动化的描述生成：装饰器或基类会自动提取函数的__doc__或参数注解来生成给LLM看的工具描述，减少手动维护。
类型提示的利用：框架可以利用Python的类型提示（city: str）来帮助LLM理解参数格式，甚至自动进行基础的参数验证和类型转换。
统一的错误处理：Tool基类的run方法应该有标准的异常捕获和返回格式，确保即使工具执行失败，Agent也能得到一个结构化的错误信息，而不是崩溃。

3.3 记忆管理：在简单与强大间权衡

记忆是Agent的“经验”。对于精益框架，记忆系统可能是分层和可插拔的。

短期记忆：通常是当前会话的对话历史。一个简单的实现就是用一个Python列表（List[Dict]）来存储role和content。为了控制上下文长度，会实现一个“滑动窗口”或基于Token数的修剪策略。
长期记忆：框架可能不内置复杂的向量存储，而是定义一个MemoryBackend抽象接口。

from abc import ABC, abstractmethod from typing import List, Dict, Any class MemoryBackend(ABC): @abstractmethod async def store(self, key: str, value: Any): ... @abstractmethod async def retrieve(self, key: str) -> Any: ... @abstractmethod async def search(self, query: str, limit: int=5) -> List[Dict]: ... # 内置一个基于内存字典的简单后端 class DictMemoryBackend(MemoryBackend): def __init__(self): self._storage = {} async def store(self, key: str, value: Any): self._storage[key] = value async def retrieve(self, key: str) -> Any: return self._storage.get(key) async def search(self, query: str, limit: int=5) -> List[Dict]: # 简单实现：无法进行语义搜索。这迫使有需要的用户自行实现或集成外部后端。 return []

这样设计的好处：框架提供了记忆的概念和接口，但将具体实现的复杂性交给了用户。用户可以根据需要，轻松实现一个连接到SQLite、Redis、甚至是Pinecone/Weaviate等向量数据库的后端。

4. 从零搭建一个精益Agent：实操演练

让我们抛开对nvtien547/lean-agentic具体代码的猜测，基于上述设计哲学，实际动手搭建一个具备核心功能的“精益Agent”。我们将构建一个能查询天气和进行简单计算的命令行Agent。

4.1 环境准备与项目初始化

首先，创建一个干净的项目目录。我们坚持“最小依赖”原则。

mkdir lean-agent-demo && cd lean-agent-demo python -m venv venv source venv/bin/activate # Linux/Mac # venv\Scripts\activate # Windows # 核心依赖：异步HTTP，可选的环境变量管理，以及类型提示支持 pip install aiohttp pydantic-settings

创建项目结构：

lean-agent-demo/ ├── pyproject.toml # 项目配置和依赖声明 ├── src/ │ └── lean_agent/ │ ├── __init__.py │ ├── agent.py # Agent核心类 │ ├── llm.py # LLM客户端 │ ├── memory.py # 记忆系统 │ ├── tools.py # 工具基类和内置工具 │ └── cli.py # 命令行入口 └── .env.example # 环境变量示例

在pyproject.toml中，使用现代Python打包标准声明依赖和项目信息。

4.2 实现核心组件

1. LLM客户端 (src/lean_agent/llm.py)我们实现一个支持OpenAI和OpenAI兼容API的客户端。

import aiohttp from typing import List, Dict, Any, Optional from pydantic import BaseModel, Field class LLMConfig(BaseModel): model: str = Field(default=“gpt-3.5-turbo”) api_key: str base_url: str = Field(default=“https://api.openai.com/v1”) timeout: int = Field(default=30) class LeanLLMClient: def __init__(self, config: LLMConfig): self.config = config self._session: Optional[aiohttp.ClientSession] = None async def aget_session(self) -> aiohttp.ClientSession: if self._session is None or self._session.closed: self._session = aiohttp.ClientSession() return self._session async def generate(self, messages: List[Dict], **kwargs) -> str: """发起聊天补全请求，并处理基础错误。""" payload = { “model”: self.config.model, “messages”: messages, “temperature”: kwargs.get(“temperature”, 0.7), “max_tokens”: kwargs.get(“max_tokens”, 1000), } headers = { “Authorization”: f“Bearer {self.config.api_key}”, “Content-Type”: “application/json” } session = await self.aget_session() try: async with session.post( f“{self.config.base_url}/chat/completions”, json=payload, headers=headers, timeout=self.config.timeout ) as response: response.raise_for_status() data = await response.json() return data[“choices”][0][“message”][“content”].strip() except aiohttp.ClientError as e: # 在实际框架中，这里应实现更精细的重试逻辑（如指数退避） raise ConnectionError(f“调用LLM API失败: {e}”) from e async def close(self): if self._session and not self._session.closed: await self._session.close()

2. 工具系统 (src/lean_agent/tools.py)实现一个基于装饰器的工具注册系统。

import inspect from typing import Callable, Dict, Any, get_type_hints from functools import wraps class Tool: def __init__(self, func: Callable, name: str, description: str): self.func = func self.name = name self.description = description self.signature = inspect.signature(func) self.type_hints = get_type_hints(func) async def run(self, **kwargs) -> str: """执行工具，并确保返回字符串。""" try: result = await self.func(**kwargs) if inspect.iscoroutinefunction(self.func) else self.func(**kwargs) return str(result) except Exception as e: return f“执行工具 ‘{self.name}’ 时出错: {e}” def tool(name: str = None, description: str = None): """将函数装饰为Agent可用的工具。""" def decorator(func: Callable): tool_name = name or func.__name__ tool_desc = description or func.__doc__ or tool_name return Tool(func, tool_name, tool_desc) return decorator # --- 示例内置工具 --- @tool(name=“get_time”, description=“获取当前系统时间”) def get_current_time() -> str: from datetime import datetime return datetime.now().isoformat() @tool(description=“将两个数字相加”) async def add_numbers(a: float, b: float) -> str: return str(a + b)

3. 记忆与Agent核心 (src/lean_agent/memory.py,src/lean_agent/agent.py)记忆系统我们先用一个简单的对话历史列表。

# src/lean_agent/memory.py from typing import List, Dict class ConversationMemory: def __init__(self, max_turns: int = 20): self.messages: List[Dict] = [] self.max_turns = max_turns def add(self, role: str, content: str): self.messages.append({“role”: role, “content”: content}) # 简单的截断策略：保留最近N轮对话 if len(self.messages) > self.max_turns * 2: # 每轮包含user和assistant self.messages = self.messages[-self.max_turns * 2:] def get_context(self) -> List[Dict]: return self.messages.copy()

# src/lean_agent/agent.py import json import re from typing import List, Optional from .llm import LeanLLMClient from .memory import ConversationMemory from .tools import Tool class LeanAgent: def __init__(self, llm_client: LeanLLMClient, tools: List[Tool], system_prompt: str = None): self.llm = llm_client self.tools = {tool.name: tool for tool in tools} self.memory = ConversationMemory() self.system_prompt = system_prompt or “你是一个有帮助的AI助手。你可以使用工具来帮助用户。” def _build_tools_prompt(self) -> str: if not self.tools: return “” tools_desc = “\n”.join([f“- {name}: {tool.description}” for name, tool in self.tools.items()]) return f“\n\n你可以使用以下工具：\n{tools_desc}\n当需要使用工具时，请严格按照以下JSON格式回复：\n{{‘action’: ‘tool_name’, ‘args’: {{‘arg1’: ‘value1’, …}}}}” async def process_step(self, user_input: str) -> str: # 1. 将用户输入存入记忆 self.memory.add(“user”, user_input) # 2. 构建完整的提示词 context = self.memory.get_context() system_msg = {“role”: “system”, “content”: self.system_prompt + self._build_tools_prompt()} messages = [system_msg] + context # 3. 调用LLM获取响应 llm_response = await self.llm.generate(messages) # 4. 解析响应，检查是否是工具调用 tool_call = self._parse_tool_call(llm_response) if tool_call: tool_name = tool_call[“action”] tool_args = tool_call.get(“args”, {}) if tool_name in self.tools: # 执行工具 tool_result = await self.tools[tool_name].run(**tool_args) # 将工具执行结果作为新的上下文信息再次调用LLM self.memory.add(“assistant”, f“[调用工具 {tool_name}]”) self.memory.add(“user”, f“工具执行结果: {tool_result}”) # 递归处理，让LLM基于工具结果生成最终回复 return await self.process_step(“请根据工具结果回答用户最初的问题。”) else: llm_response = f“错误：未知工具 ‘{tool_name}’。请重新回答。” # 5. 将助手的最终回复存入记忆并返回 self.memory.add(“assistant”, llm_response) return llm_response def _parse_tool_call(self, text: str) -> Optional[Dict]: """尝试从文本中解析JSON格式的工具调用。这是一个非常基础的实现。""" # 寻找可能包含JSON的代码块或行 json_match = re.search(r‘\{“action”:.*?\}’, text, re.DOTALL) if json_match: try: return json.loads(json_match.group()) except json.JSONDecodeError: pass return None

4.3 组装并运行：创建命令行交互

最后，我们创建一个简单的命令行界面来驱动这个Agent。

# src/lean_agent/cli.py import asyncio import sys from typing import List from pydantic_settings import BaseSettings from .llm import LeanLLMClient, LLMConfig from .agent import LeanAgent from .tools import tool, get_current_time, add_numbers class Settings(BaseSettings): openai_api_key: str openai_base_url: str = “https://api.openai.com/v1” model: str = “gpt-3.5-turbo” class Config: env_file = “.env” @tool(description=“结束会话”) def exit_chat() -> str: print(“\n再见！”) sys.exit(0) async def main(): settings = Settings() config = LLMConfig( model=settings.model, api_key=settings.openai_api_key, base_url=settings.openai_base_url ) llm_client = LeanLLMClient(config) # 注册工具 tools = [get_current_time, add_numbers, exit_chat] agent = LeanAgent( llm_client=llm_client, tools=tools, system_prompt=“你是一个精益AI助手。请直接、高效地回答用户问题，并在需要时使用工具。” ) print(“精益AI代理已启动。输入‘退出’或使用exit_chat工具来结束对话。\n”) try: while True: try: user_input = input(“\n用户: “).strip() except (EOFError, KeyboardInterrupt): break if not user_input: continue response = await agent.process_step(user_input) print(f“助手: {response}”) finally: await llm_client.close() if __name__ == “__main__”: asyncio.run(main())

创建一个.env文件存放你的API密钥：

OPENAI_API_KEY=sk-your-api-key-here # OPENAI_BASE_URL=https://your.openai.compatible.api/v1 # 如需使用兼容API可取消注释

现在，运行python -m src.lean_agent.cli，你就可以和一个具备工具调用能力的精简版AI Agent对话了。它可以告诉你时间，做加法，并且所有代码都在几百行内，依赖清晰。

5. 深入实践：性能调优与生产化考量

一个可用的原型和一個健壮的生产级组件之间有巨大差距。基于我们构建的精益框架，我们来探讨几个关键的进阶话题。

5.1 提升工具调用的可靠性

我们上面实现的_parse_tool_call函数非常脆弱，它依赖LLM输出严格的JSON，并且正则表达式很容易出错。在生产环境中，我们需要更鲁棒的方法。

方案一：函数调用（Function Calling）如果使用的LLM API（如OpenAI GPT-3.5/4）支持原生的函数调用功能，我们应该优先使用它。这需要修改LLM客户端和Agent核心。

# 在LLM客户端的generate方法中，支持tools参数 async def generate(self, messages: List[Dict], tools: List[Dict] = None, **kwargs) -> Dict: """返回包含可能存在的工具调用的完整响应字典。""" payload = {“model”: self.config.model, “messages”: messages, **kwargs} if tools: payload[“tools”] = tools payload[“tool_choice”] = “auto” # 让模型决定是否调用工具 # ... 发送请求 ... response_data = await resp.json() # 不再直接返回content，而是返回整个choice return response_data[“choices”][0] # 在Agent的process_step中 llm_response = await self.llm.generate(messages, tools=self._format_tools_for_api()) if llm_response.get(“finish_reason”) == “tool_calls”: tool_calls = llm_response[“message”].get(“tool_calls”, []) for call in tool_calls: tool_name = call[“function”][“name”] tool_args = json.loads(call[“function”][“arguments”]) # ... 执行工具 ...

方案二：输出引导与结构化输出对于不支持函数调用的模型，我们可以通过更精细的提示工程和输出解析来提升稳定性。例如，使用Pydantic模型来定义期望的输出格式，然后使用像instructor或outlines这样的库来引导LLM输出结构化内容。虽然这会增加依赖，但显著提升了可靠性。

5.2 实现异步并发与流式响应

我们的基础Agent是同步顺序执行的。对于需要同时调用多个独立工具，或者希望实现打字机效果的流式响应，需要引入并发。

异步工具执行：

async def process_step(self, user_input: str): # ... 前面的逻辑 ... tool_call = self._parse_tool_call(llm_response) if tool_call: if isinstance(tool_call, list): # 支持并行工具调用 tasks = [self._execute_single_tool(call) for call in tool_call] results = await asyncio.gather(*tasks, return_exceptions=True) # 合并结果 combined_result = “\n”.join([r if not isinstance(r, Exception) else f“错误: {r}” for r in results]) self.memory.add(“user”, f“并行工具执行结果: {combined_result}”) else: # 单个工具执行逻辑... pass return await self.process_step(“请总结工具结果并回答。”)

流式响应：对于LLM的文本生成，我们可以使用API的流式接口，逐步获取Token并实时输出，提升用户体验。这需要在LeanLLMClient中实现一个async generate_stream方法，并使用async for循环来消费数据流。

5.3 记忆的优化与持久化

简单的对话列表记忆很快会耗尽上下文窗口。我们需要：

总结性记忆：当对话历史过长时，可以调用LLM对之前的对话进行总结，将总结作为一条新的系统消息，然后清空或截断旧的历史。这能保留关键信息，同时节省Token。
向量记忆检索：实现我们之前定义的MemoryBackend接口，连接到一个向量数据库。当用户提问时，除了最近的对话历史，还可以从向量库中检索相关的历史片段（记忆）作为上下文。这实现了真正意义上的“长期记忆”。
记忆持久化：将记忆后端（无论是简单的Dict还是向量库）与文件系统或数据库连接，实现会话的保存和加载。这可以通过在Agent类中增加save_session和load_session方法来实现。

5.4 可观测性与调试

一个运行在后台的Agent如果出了问题，调试起来很困难。必须内置可观测性。

结构化日志：使用structlog或logging模块，为每个关键步骤（收到输入、调用LLM、解析工具、执行工具、返回输出）记录结构化的日志，包含会话ID、时间戳、耗时、输入输出摘要等。
中间状态导出：提供一个get_internal_state方法，或者允许注册回调函数，在每一步执行后输出当前的内存状态、工具调用历史等，方便在开发界面中可视化。
超时与熔断：为LLM调用和每个工具执行设置超时。如果某个工具连续失败，可以暂时将其“熔断”，避免整个Agent被拖垮。

6. 常见陷阱与实战经验分享

在开发和部署这类精益Agent系统的过程中，我踩过不少坑，这里分享几个最具代表性的。

6.1 提示工程中的“幻觉”与“循环”

问题：Agent陷入无限循环，比如反复调用同一个工具，或者LLM在是否需要调用工具上反复“横跳”。根因：系统提示词（System Prompt）指令不清晰，或者记忆管理混乱，导致模型上下文出现矛盾。解决方案：

明确指令：在系统提示中清晰界定工具调用的边界。例如：“你必须且仅当用户问题明确需要外部数据或计算时才使用工具。如果信息已存在于当前对话历史中，请直接回答。一次只使用一个工具，除非我明确要求并行执行。”
在上下文中标记状态：每次工具调用和结果返回后，在对话历史中用明显的标记（如[调用工具X]、[工具结果: ...]）标出，帮助LLM理解当前状态。
设置最大步数：在Agent循环中设置一个硬性计数器（如max_steps=10），超过后强制终止并返回错误，防止死循环。

6.2 工具执行的安全性与沙箱化

问题：CalculatorTool示例中使用了危险的eval()，如果LLM被诱导生成__import__(‘os’).system(‘rm -rf /’)这样的参数，后果不堪设想。解决方案：

永远不要信任LLM的输入：所有工具参数在传递给实际执行代码前，必须进行严格的验证、清洗和类型转换。
使用安全替代品：对于计算，使用ast.literal_eval或专门的库如asteval（它提供了一个安全的求值环境）。对于系统操作，严格限制可用命令的白名单。
沙箱环境：对于执行不可信代码的工具（如运行用户提供的Python代码片段），必须在独立的Docker容器或安全沙箱（如gVisor,Firecracker）中运行，并限制资源（CPU、内存、网络）。

6.3 成本控制与速率限制

问题：Agent在自动循环中可能产生大量LLM API调用，导致意外的高额账单或触发速率限制。解决方案：

预算与熔断：实现一个简单的令牌桶或计数器，跟踪每个会话或全局的LLM调用次数和Token消耗。接近预算时发出警告或停止服务。
指数退避重试：在LLM客户端中，对于速率限制错误（HTTP 429），实现带有随机抖动的指数退避重试逻辑，而不是简单失败或立即重试。
缓存层：对于频繁出现的、结果确定的查询（如“今天的日期”），可以在工具层或LLM调用层添加缓存（使用functools.lru_cache或Redis），直接返回缓存结果，节省成本和延迟。

6.4 处理LLM输出的不确定性

问题：LLM的输出格式可能不符合预期，即使使用了函数调用，也可能返回格式错误或内容胡言乱语。解决方案：

多层解析与降级：解析逻辑应该像洋葱一样分层。首先尝试最严格的解析（如JSON Schema验证），如果失败，则尝试更宽松的正则表达式提取，如果还失败，则尝试用另一个LLM调用来修复格式（这有递归风险），最后降级为将错误信息返回给用户并请求澄清。
验证与重试：在工具执行前，验证参数是否在合理范围内（如城市名称是否非空字符串）。如果LLM返回了明显无效的参数，可以自动重新生成提示，要求它纠正。例如：“你提供的参数‘city’值为空，请根据对话历史重新生成有效的工具调用。”

构建一个“精益”的AI代理框架，其精髓不在于功能的多寡，而在于设计的清晰度、代码的透明度和对核心问题（推理、工具使用、记忆）的专注解决。nvtien547/lean-agentic这类项目之所以有价值，是因为它们像一份简洁的蓝图，揭示了AI Agent最本质的运作原理，让开发者能够以此为基础，构建出真正贴合自己业务需求的、可控且高效的智能体系统。在这个过程中，你收获的将不仅仅是一个工具，更是对智能体架构的深刻理解。