我的经验是，能跑起来的最小闭环最重要，别一上来就追求“完美架构”或者花太多时间做数据小偷。

Bub 的分层很简单：

• Agent：主循环，负责 LLM 交互、工具调用、上下文管理。
• Tool：每个工具一个类，参数用 Pydantic 校验。
• ToolRegistry：注册所有工具，方便扩展。
• CLI：Typer + Rich，命令行入口，支持展开中间状态。

Agent 的本质其实就是一个 while 循环。每次循环，Agent 会根据当前上下文判断是否需要调用工具，如果需要就调用，然后把工具的返回结果写回上下文。

class Agent:
    def chat(self, message: str) -> str:
        self.conversation_history.append(Message(role="user", content=message))
        while True:
            # Construct context: historical messages + tool list
            ...
            response = litellm.completion(...)
            assistant_message = str(response.choices[0].message.content)
            self.conversation_history.append(Message(role="assistant", content=assistant_message))
            tool_calls = self.tool_executor.extract_tool_calls(assistant_message)
            if tool_calls:
                for tool_call in tool_calls:
                    result = self.tool_executor.execute_tool(tool_call.name, **tool_call.parameters)
                    observation = f"Observation: {result.format_result()}"
                    self.conversation_history.append(Message(role="user", content=observation))
                continue
            else:
                return assistant_message

踩过的坑

• 没有捕获，LLM 输出格式一变就死循环
• 工具参数没校验，LLM 乱传参数直接崩
• Observation 反馈太长或缺乏有效信息，LLM 理解困难
  
  

工具是 LLM 和外部世界的桥梁，定义得好，模型才能真正“动手”。我的做法是：

• 工具参数全部用 Pydantic 校验，类型不对直接拒绝。
• 命令行工具有黑名单（比如 rm
  、del
  ），遇到危险命令直接报错。
• 工具执行结果结构化返回，别让 LLM 猜。
• 操作命令行工具时，stdout 和 stderr 都很重要，不能只给 exit code.
• 工具之间要有明确边界，避免混淆。

class RunCommandTool(Tool):
    DANGEROUS_COMMANDS = {"rm", "del"}
    def _validate_command(self, base_cmd: str) -> Optional[str]:
        if base_cmd in self.DANGEROUS_COMMANDS:
            return f"Dangerous command blocked: {base_cmd}"
    def execute(self, context: Context) -> ToolResult:
        # Validate command, execute and return results