在Google Colab上构建纳米机器人式AI代理，实现工具调用与会话记忆

背景与目标

随着大语言模型（LLM）在个人助理、研发协作等场景的落地，如何快速搭建一个具备 工具调用、会话记忆 与 可扩展技能 的 AI 代理成为开发者关注的热点。本文以 Google Colab 为运行环境，复现并精简了 HKUDS/nanobot 项目中的核心架构，实现了一个 provider‑agnostic 的纳米机器人式代理，既可对接 OpenAI‑compatible 接口，也可使用完全离线的 Mock 提供者，方便教学与原型验证。

核心组件概览

Provider 抽象层：
- Provider 为统一接口，OpenAICompatibleProvider 支持 OpenAI、OpenRouter、Together 等兼容服务；MockProvider 通过规则模拟工具调用，零成本运行。
Tool Registry 与自动化 Schema：
- 使用 @tool 装饰器将普通 Python 函数转为符合 OpenAI Function Calling 规范的工具，自动生成 JSON 参数 schema，降低扩展门槛。
Token‑Budgeted Memory：
- Memory 按 token 预算（默认 3000）管理会话历史，超过预算时自动裁剪最旧回合，保持上下文连贯性。
Agent Hook 与 Skill 机制：
- AgentHook 可在迭代前后、工具执行前后插入自定义逻辑，Skill 将一组工具与说明绑定，按需加载到系统提示中。
MCP（Minimal Compute Provider）服务器：
- MCPServer 提供外部工具的统一注册与调用接口，示例中实现了一个天气预报 stub，演示了跨服务工具接入的完整流程。

实现细节

1. Provider 实现

class OpenAICompatibleProvider(Provider):
    def __init__(self, api_key, model, base_url=None):
        self.client = AsyncOpenAI(api_key=api_key, base_url=base_url)
        self.model = model
    async def complete(self, messages, tools):
        # 省略细节，返回统一的 LLMResponse 对象

MockProvider 通过正则匹配用户意图（数学、时间、记忆）直接返回 ToolCall，实现 无网络、可离线演示。

2. 工具注册示例

@tool
def calculator(expression: str) -> str:
    """计算算术表达式并返回结果。"""
    expr = expression.replace('^', '**')
    value = eval(expr, {"__builtins__": {}}, allowed)
    return f"{expression} = {value}"

@tool
def get_current_time(timezone: str = "UTC") -> str:
    """返回指定 IANA 时区的当前时间。"""
    now = datetime.now(ZoneInfo(timezone))
    return f"Current time in {timezone}: {now.isoformat()}"

上述装饰器会自动生成 OpenAI 所需的 function schema，随后在 ToolRegistry 中统一管理。

3. 会话记忆与 Token 预算

memory = Memory(token_budget=3000)
memory.append(session_key, {"role": "user", "content": user_msg})
memory.compact(session_key)  # 超出预算时裁剪

记忆结构保证 工具调用‑结果 成对出现，防止因为裁剪导致上下文不一致。

4. 生命周期 Hook 示例

class AuditHook(AgentHook):
    async def before_execute_tools(self, ctx):
        for tc in ctx.tool_calls:
            print(f"[audit] {tc.name}({tc.arguments})")

通过 AuditHook 可以实时观察模型发起的工具调用，便于调试与行为审计。

5. MCP 服务器接入

server = MCPServer("weather")
server.register(
    name="forecast",
    description="获取城市天气预报（示例实现）",
    parameters={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    handler=lambda city: f"Forecast for {city}: 27°C, partly cloudy (stub)"
)
bot.connect_mcp(server)

mcp_tools(server) 会把每个 MCP 工具转为本地 Tool，实现统一调用。

演示流程

基础聊天：无需工具，模型直接回复。
工具调用：如数学计算、时区查询、Python 代码执行，模型先返回 tool_calls，随后 Agent 将结果写回对话并继续推理。
多轮记忆：不同 session_key 拥有独立历史，示例中展示了两位用户的姓名与爱好记忆互不干扰。
Skill 加载：通过 register_skill 与 load_skill 动态注入 web_search 等工具，实现“检索‑摘要”工作流。
Hook 与内容后处理：TimingHook 统计每轮耗时，CensorHook 在最终输出前过滤敏感词。

结论与展望

本文提供的 Nanobot‑style Agent 代码完整、注释详尽，适合作为学习 LLM‑Agent 体系结构的入门教材。开发者可在此基础上：

替换 MockProvider 为实际商用模型（如 GPT‑4o‑mini、Claude‑3.5）。
集成真实的 Web 搜索、数据库查询或企业内部 API，构建企业级个人助理。
扩展 Memory 为持久化向量库，实现长期知识管理。
结合 RAG（检索增强生成）或多模态模型，进一步提升实际业务价值。

提示：在生产环境中务必对工具执行进行安全沙箱化，防止代码注入与信息泄露。

通过本教程，您不仅可以在浏览器免费算力（Colab）上快速跑通一个完整的 AI 代理，还能掌握从 抽象 Provider、工具注册、记忆管理 到 生命周期 Hook 的全链路实现思路，为后续构建更复杂的智能系统奠定坚实基础。

在Google Colab上构建纳米机器人式AI代理，实现工具调用与会话记忆