简单来说，AI Agent 就是一个能够自主感知环境、制定计划、采取行动来完成特定目标的系统。

从架构的角度来看，又可以分为感知模块（包括状态上下文和意图上下文，而意图上下文是一个更难一些的问题），推理模块（LLM 主控部分），记忆模块，行动模块。

今天我们要聊的是贯穿于各个模块中的工具，工具不仅仅是行动模块，在感知，记忆中都有可能用到工具。

1. OpenManus 的工具管理和调度

看了 OpenManus 的代码，整个工程中 Tool 的占比还是比较大的，这也不是一个大而全的框架。

直接看代码

1.1 BaseTool 基础类

class BaseTool(ABC):
    name: str
    description: str  
    parameters: Dict[str, Any]
    
    @abstractmethod
    async def execute(self, tool_input: Dict[str, Any]) -> ToolResult

name 用于标识，description 给 LLM 看，parameters 定义输入规范，execute 执行具体逻辑。这几个字段，已经涵盖了工具管理的核心要素。

1.2 ToolCollection 管理器

工具集合的管理通过 ToolCollection 类实现，核心是一个字典：

class ToolCollection:
    def __init__(self):
        self.tool_map: Dict[str, BaseTool] = {}

整个实现有以下三个小点：

O(1) 的查找性能。用工具名作为 key，直接查找，没有遍历，没有复杂的匹配逻辑。
统一的执行接口。所有工具调用都通过 execute 方法，传入工具名和参数，返回统一的 ToolResult。这种一致性让上层调用变得极其简单。
统一的错误处理。工具不存在、执行失败都会返回 ToolFailure，不会抛异常打断流程。这种设计让系统更健壮。

def add_tool(self, tool: BaseTool) -> None:
    if tool.name in self.tool_map:
        logger.warning(f"Tool {tool.name} already exists, overwriting")
    self.tool_map[tool.name] = tool

在添加工具时可以覆盖已有工具。

1.3 Think-Act 循环

OpenManus 实现了标准的 ReAct（Reasoning and Acting）模式，但做了很多细节优化：

async def step(self) -> None:
    await self.think()  # 思考：决定用什么工具
    await self.act()    # 行动：执行工具调用

这个实现是在 ReActAgent 中定义的，think 阶段让 LLM 分析当前状态并选择工具，act 阶段执行工具并收集结果。两个阶段分离，让整个流程可控、可调试。

1.4 工具选择

工具选择是整个系统的核心：

async def think(self) -> None:
    response = await self.llm.ask_tool(
        messages=self.memory.get_messages(),
        system_prompts=self.system_prompts,
        available_tools=self.available_tools.get_tool_schemas(),
        tool_choices=self.tool_choices
    )

它把几个关键信息都传给 LLM：

历史对话（messages）：让 LLM 了解上下文
系统提示（system_prompts）：定义 Agent 的行为规范
可用工具（available_tools）：告诉 LLM 有哪些工具可用
选择模式（tool_choices）：控制是否必须选择工具

这种设计让工具选择既灵活又可控。

1.5 批量执行和结果处理

OpenManus 支持一次选择多个工具并行执行：

async def act(self) -> None:
    if self.tool_calls:
        for tool_call in self.tool_calls:
            observation = await self.execute_tool(tool_call)
            self.memory.add_message(ToolMessage(observation, tool_call.id))

每个工具的执行结果都会记录到 memory 中，供下一轮思考使用。

1.6 特殊工具处理

OpenManus 预留了特殊工具的处理机制：

def handle_special_tool(self, tool_call: ToolCall) -> str:
    if tool_call.name == "Terminate":
        self.should_stop = True
        return "Task completed successfully."
    return f"Unknown special tool: {tool_call.name}"

Terminate 工具用于优雅终止，这种设计避免了硬编码的退出逻辑。你可以轻松添加其他特殊工具，比如 Pause（暂停）、Checkpoint（保存状态）等。

2. Gemini CLI 的工具管理和调度

Gemini CLI 把所有工具都扔给大模型，让它自己选。

// 就这么简单，所有工具一股脑给 LLM
async setTools(): Promise<void> {
  const toolRegistry = this.config.getToolRegistry();
  const toolDeclarations = toolRegistry.getFunctionDeclarations();
  const tools: Tool[] = [{ functionDeclarations: toolDeclarations }];
  this.getChat().setTools(tools);
}

现在的大模型已经足够聪明，能够根据上下文选择合适的工具。与其花大力气设计复杂的工具选择策略，不如相信 AI 的判断力。但会有可能存在工具「爆炸」的情况，这个后面我们再聊。

2.1 三层工具发现机制

Gemini CLI 在工具发现方面设计了三层机制：

1. 内置核心工具

这些是精心挑选的常用工具，覆盖了大部分日常开发需求：

文件操作：ls、read-file、write-file、edit
代码搜索：grep、ripgrep、glob
系统交互：shell
网络请求：web-fetch、web-search
记忆管理：memory

每个工具都经过精心设计，接口清晰，功能专一。比如 edit 工具，不仅能编辑文件，还支持预览修改。

2. 命令行工具发现

这是个很巧妙的设计。我们可以通过配置一个发现命令，让系统自动发现和注册新工具：

// 执行发现命令，解析返回的工具声明
async discoverAndRegisterToolsFromCommand(): Promise<void> {
  const command = this.config.getConfigOptions().toolDiscoveryCommand;
  if (!command) return;
  
  const result = await exec(command);
  const functions = JSON.parse(result.stdout);
  
  for (const func of functions) {
    this.registerTool(new DiscoveredTool(func));
  }
}

这意味着我们可以轻松扩展工具集，只要我们的工具能输出符合格式的 JSON 声明即可。

3. MCP 服务器集成

MCP（Model Context Protocol）是个通用的协议，Gemini CLI 对它的支持相当完善：

// 支持多种传输协议
- stdio：标准输入输出
- SSE：服务器推送事件
- HTTP：REST API
- WebSocket：双向通信

通过 MCP，我们可以接入各种专业工具服务器，比如数据库查询、API 调用、专业领域工具等。每个 MCP 服务器的工具都是隔离的，避免了命名冲突。

2.2 工具调度器

Gemini CLI 的工具调度器采用了清晰的状态机模型：

// 工具执行状态流转
validating → scheduled → awaiting_approval → executing → success/error/cancelled

在执行前先验证参数，避免无效调用：

export type ValidatingToolCall = {
  status: 'validating';
  request: ToolCallRequestInfo;
  tool: AnyDeclarativeTool;
  invocation: AnyToolInvocation;
};

根据工具风险等级，提供不同的确认策略：

// 三种确认模式
ApprovalMode.DEFAULT    // 标准确认
ApprovalMode.AUTO_EDIT  // 自动编辑确认
ApprovalMode.YOLO       // 无确认模式（勇者模式）

YOLO 模式的命名有点意思，”You Only Live Once” 人生苦短，活出精彩

独立的工具调用可以并行执行，提高效率：

// 并行处理多个工具调用
for (const fnCall of functionCalls) {
  // 不等待，直接调度下一个
  this.handlePendingFunctionCall(fnCall);
}

工具执行过程中的输出会实时展示，用户体验很好：

// 实时更新输出流
onUpdate?: (output: string) => void;

2.3 错误处理机制

1. 错误类型分类

系统定义了完整的错误类型枚举 ToolErrorType，包括：

通用错误：

INVALID_TOOL_PARAMS – 工具参数无效
UNKNOWN – 未知错误
UNHANDLED_EXCEPTION – 未处理的异常
TOOL_NOT_REGISTERED – 工具未注册
EXECUTION_FAILED – 执行失败

文件系统错误：

FILE_NOT_FOUND – 文件未找到
FILE_WRITE_FAILURE – 文件写入失败
PERMISSION_DENIED – 权限拒绝
PATH_NOT_IN_WORKSPACE – 路径不在工作空间内

Shell 特定错误：

SHELL_EXECUTE_ERROR – Shell 执行错误

2. 工具调用状态管理

系统定义了完整的工具调用状态类型：

export type ToolCall =
  | ValidatingToolCall      // 验证中
  | ScheduledToolCall       // 已调度
  | ErroredToolCall         // 错误
  | SuccessfulToolCall      // 成功
  | ExecutingToolCall       // 执行中
  | CancelledToolCall       // 已取消
  | WaitingToolCall;        // 等待批准

3. 错误处理流程

验证阶段错误处理

在 _schedule 方法中，系统会：

工具注册检查：验证工具是否已注册
参数验证：使用 tool.build(args) 验证参数
异常捕获：捕获验证过程中的所有异常

try {
  const invocationOrError = this.buildInvocation(toolInstance, args);
  if (invocationOrError instanceof Error) {
    return {
      status: 'error',
      request: reqInfo,
      response: createErrorResponse(
        reqInfo,
        invocationOrError,
        ToolErrorType.INVALID_TOOL_PARAMS,
      ),
      durationMs: 0,
    };
  }
} catch (error) {
  // 处理验证异常
}

执行阶段错误处理

在 attemptExecutionOfScheduledCalls 方法中，系统会：

执行异常捕获：使用 Promise .catch() 捕获执行异常
错误响应生成：调用 createErrorResponse 生成标准化错误响应
状态更新：将工具调用状态设置为 ‘error’

promise
  .then(async (toolResult: ToolResult) => {
    // 处理成功结果
  })
  .catch((error: Error) => {
    this.setStatusInternal(
      callId,
      'error',
      createErrorResponse(reqInfo, error, ToolErrorType.UNHANDLED_EXCEPTION),
    );
  });

4. 错误响应格式

createErrorResponse 函数生成标准化的错误响应：

const createErrorResponse = (
  request: ToolCallRequestInfo,
  error: Error,
  errorType: ToolErrorType | undefined,
): ToolCallResponseInfo => ({
  callId: request.callId,
  error,
  responseParts: [{
    functionResponse: {
      id: request.callId,
      name: request.name,
      response: { error: error.message },
    },
  }],
  resultDisplay: error.message,
  errorType,
  contentLength: error.message.length,
});

2.4 超时策略

1. AbortSignal 机制

系统使用 AbortSignal 实现超时和取消控制：

调度层面的取消

在 schedule 方法中：

schedule(
  request: ToolCallRequestInfo | ToolCallRequestInfo[],
  signal: AbortSignal,
): Promise<void> {
  if (this.isRunning() || this.isScheduling) {
    return new Promise((resolve, reject) => {
      const abortHandler = () => {
        // 从队列中移除请求
        const index = this.requestQueue.findIndex(
          (item) => item.request === request,
        );
        if (index > -1) {
          this.requestQueue.splice(index, 1);
          reject(new Error('Tool call cancelled while in queue.'));
        }
      };
      
      signal.addEventListener('abort', abortHandler, { once: true });
      // ...
    });
  }
}

执行层面的取消

在工具执行过程中：

执行前检查：

if (signal.aborted) {
  this.setStatusInternal(
    reqInfo.callId,
    'cancelled',
    'Tool call cancelled by user.',
  );
  continue;
}

执行后检查：

.then(async (toolResult: ToolResult) => {
  if (signal.aborted) {
    this.setStatusInternal(
      callId,
      'cancelled',
      'User cancelled tool execution.',
    );
    return;
  }
  // 处理成功结果
})

2. Shell 工具特殊处理

Shell 工具有特殊的超时和取消机制：

进程 ID 跟踪

if (invocation instanceof ShellToolInvocation) {
  const setPidCallback = (pid: number) => {
    this.toolCalls = this.toolCalls.map((tc) =>
      tc.request.callId === callId && tc.status === 'executing'
        ? { ...tc, pid }
        : tc,
    );
    this.notifyToolCallsUpdate();
  };
  promise = invocation.execute(
    signal,
    liveOutputCallback,
    shellExecutionConfig,
    setPidCallback,
  );
}

Shell 执行配置

系统通过 ShellExecutionConfig 配置 Shell 执行环境：

export interface ShellExecutionConfig {
  terminalWidth?: number;
  terminalHeight?: number;
  pager?: string;
  showColor?: boolean;
  defaultFg?: string;
  defaultBg?: string;
}

3. 输出截断机制

为防止输出过大导致内存问题，系统实现了输出截断：

if (
  typeof content === 'string' &&
  toolName === ShellTool.Name &&
  this.config.getEnableToolOutputTruncation() &&
  this.config.getTruncateToolOutputThreshold() > 0 &&
  this.config.getTruncateToolOutputLines() > 0
) {
  const truncatedResult = await truncateAndSaveToFile(
    content,
    callId,
    this.config.storage.getProjectTempDir(),
    threshold,
    lines,
  );
  content = truncatedResult.content;
  outputFile = truncatedResult.outputFile;
}

如果我们要构建自己的 Agent 系统，Gemini CLI 有这些值得学习的地方：

工具发现机制：三层发现机制很灵活，既有内置工具保底，又能动态扩展。
状态机调度：清晰的状态流转，便于调试和监控。
环境感知：根据运行环境自动调整行为，提升用户体验。
MCP 协议支持：接入标准协议，获得生态系统支持。
声明式工具定义：工具定义和实现分离，接口清晰。

2.5 潜在的问题

Gemini 这种设计也有一些潜在问题：

上下文膨胀：所有工具都提供给 LLM，可能导致 token 消耗增加。
工具选择不可控：完全依赖 LLM 选择，缺少人为干预手段。
调试困难：当工具很多时，难以追踪 LLM 为什么选择某个工具。

3. Shopify Sidekick 的工具管理策略

文章地址：https://shopify.engineering/building-production-ready-agentic-systems

Shopify 团队在其文章中告诉我们一个他们踩的坑：工具数量的增长不是线性问题，而是指数级复杂度问题。

他们把这个过程分成了三个阶段：

0-20 个工具：蜜月期。每个工具职责清晰，调试简单，系统行为可预测。这个阶段你会觉得”Agent 开发也不过如此嘛”。

20-50 个工具：混乱期。工具边界开始模糊，组合使用时产生意想不到的结果。这时候你开始怀疑人生：”为什么调用查询工具的同时会触发邮件发送？”

50+ 个工具：崩溃期。同一个任务有多种实现路径，系统变得无法理解。调试像在迷宫里找出口，修一个 bug 引入三个新 bug。

当工具数量超过 30 个后，整个系统变得难以维护。Shopify 把这个问题叫做”Death by a Thousand Instructions”（千条指令之死），系统提示词变成了一个充满特殊情况、相互冲突的指导和边缘案例处理的怪物。

3.1 Just-in-Time Instructions

面对工具管理的混乱，Shopify 团队找到了一个巧妙的解决方案：Just-in-Time (JIT) Instructions。

这个思路其实很简单，可能的实现如下：

# 传统方式：所有指令都塞在系统提示词里
system_prompt = """
你是一个AI助手...
当用户查询客户时，使用customer_query工具...
当用户需要发邮件时，先检查权限...
如果是VIP客户，要特别注意...
处理订单时要考虑库存...
（还有500行各种规则）
"""

# JIT方式：按需提供指令
def get_tool_instructions(tool_name, context):
    if tool_name == "customer_query":
        if context.is_filtering:
            return "使用customer_tags进行标签筛选，使用customer_status进行状态筛选..."
        else:
            return "直接查询客户基本信息..."
    # 只在需要时提供相关指令

这种设计的好处：

上下文精准：LLM 只看到当前需要的指令，不会被无关信息干扰。
缓存友好：核心系统提示词保持稳定，可以利用 LLM 的提示词缓存，提高响应速度。
灵活迭代：可以根据不同场景、用户群体、A/B 测试动态调整指令，不需要改动核心系统。
可维护性：每个工具的指令独立管理，修改一个工具的行为不会影响其他工具。

4. 小结

OpenManus 体现了优雅设计，Gemini CLI 展示简化尝试，而 Shopify Sidekick 展示了实战中的智慧。

当我们要构建生产级的 Agent 系统：

不要低估工具管理的复杂性
不要高估 LLM 的工具选择能力
不要忽视生产环境的残酷性

Agent 系统不是一次性工程，而是需要不断进化的。我们需要不断学习、调整、优化，才能构建出真正可靠的 AI Agent。

当我们的 Agent 要服务真实用户时，严谨的工程实践比炫酷的技术更重要。这可能不够酷，但这是通往生产环境的必经之路。

以上。

潘锦的空间

SaaS SaaS架构团队管理技术管理技术架构 PHP 内核扩展项目管理

AI Agent 核心管理逻辑：工具的管理和调度

1. OpenManus 的工具管理和调度

1.1 BaseTool 基础类

1.2 ToolCollection 管理器

1.3 Think-Act 循环

1.4 工具选择

1.5 批量执行和结果处理

1.6 特殊工具处理

2. Gemini CLI 的工具管理和调度

2.1 三层工具发现机制

1. 内置核心工具

2. 命令行工具发现

3. MCP 服务器集成

2.2 工具调度器

2.3 错误处理机制

1. 错误类型分类

2. 工具调用状态管理

3. 错误处理流程

验证阶段错误处理

执行阶段错误处理

4. 错误响应格式

2.4 超时策略

1. AbortSignal 机制

调度层面的取消

执行层面的取消

2. Shell 工具特殊处理

进程 ID 跟踪

Shell 执行配置

3. 输出截断机制

2.5 潜在的问题

3. Shopify Sidekick 的工具管理策略

3.1 Just-in-Time Instructions

4. 小结

发表评论取消回复

1. OpenManus 的工具管理和调度

1.1 BaseTool 基础类

1.2 ToolCollection 管理器

1.3 Think-Act 循环

1.4 工具选择

1.5 批量执行和结果处理

1.6 特殊工具处理

2. Gemini CLI 的工具管理和调度

2.1 三层工具发现机制

1. 内置核心工具

2. 命令行工具发现

3. MCP 服务器集成

2.2 工具调度器

2.3 错误处理机制

1. 错误类型分类

2. 工具调用状态管理

3. 错误处理流程

验证阶段错误处理

执行阶段错误处理

4. 错误响应格式

2.4 超时策略

1. AbortSignal 机制

调度层面的取消

执行层面的取消

2. Shell 工具特殊处理

进程 ID 跟踪

Shell 执行配置

3. 输出截断机制

2.5 潜在的问题

3. Shopify Sidekick 的工具管理策略

3.1 Just-in-Time Instructions

4. 小结

发表评论 取消回复

发表评论取消回复