bu-agent-sdk

由 browseruse 团队开源的 bu-agent-sdk，可能是目前最轻量、最透明的智能体（Agent）开发框架。它的核心哲学只有一句话：

“一个智能体就是一个 for 循环。”

没有复杂的抽象层，没有黑盒调度器，没有状态机魔法——只有工具调用 + LLM 决策 + 显式完成的朴素循环。这个框架正是驱动 BU.app 背后的引擎，现已完全开源。

为什么需要它？

当前许多智能体框架过度工程化：层层封装、隐式状态、难以调试。而 bu-agent-sdk 的设计者认为：

“所有价值都在经过强化学习的模型中，而不是你那上万行的抽象层里。”

真正的智能体失败，往往不是因为模型弱，而是因为行为空间不完整——限制太多，自由太少。因此，该框架选择最小化干预，让 LLM 尽可能自由地调用工具，并通过显式完成机制和上下文管理来保障可靠性。

快速上手

安装

uv add bu-agent-sdk
# 或
uv sync  # 若已写入 pyproject.toml

最小示例

import asyncio
from bu_agent_sdk import Agent, tool, TaskComplete
from bu_agent_sdk.llm import ChatAnthropic

@tool("两数相加")
async def add(a: int, b: int) -> int:
    return a + b

@tool("标记任务完成")
async def done(message: str) -> str:
    raise TaskComplete(message)  # 显式结束

agent = Agent(
    llm=ChatAnthropic(model="claude-sonnet-4-20250514"),
    tools=[add, done],
)

async def main():
    result = await agent.query("2 + 3 等于多少？")
    print(result)

asyncio.run(main())

核心特性

1. 强制显式完成（Require Done Tool）

传统“无工具调用即停止”策略常导致智能体过早退出。
bu-agent-sdk 要求必须调用 done() 工具才能结束任务，确保意图完整执行。

agent = Agent(..., require_done_tool=True)

2. 瞬时消息（Ephemeral Messages）

大型工具输出（如浏览器 DOM、截图）会迅速撑爆上下文。
通过 ephemeral=N 仅保留最近 N 条消息，自动清理历史。

@tool("获取浏览器状态", ephemeral=3)
async def get_state() -> str:
    return massive_dom_and_screenshot

3. 统一 LLM 接口，支持多提供商

• Anthropic（Claude）
• OpenAI（GPT）
• Google（Gemini）

每个实现仅约 300 行代码，接口一致，便于切换与调试。

from bu_agent_sdk.llm import ChatAnthropic, ChatOpenAI, ChatGoogle

4. 自动上下文压缩

当上下文使用接近阈值（如 80%），自动触发摘要压缩，防止截断。

from bu_agent_sdk.agent import CompactionConfig

agent = Agent(..., compaction=CompactionConfig(threshold_ratio=0.80))

5. 依赖注入（FastAPI 风格）

类型安全的依赖注入，便于集成数据库、配置等外部资源。

def get_db(): return Database()

@tool("查询用户")
async def get_user(id: int, db: Annotated[Database, Depends(get_db)]) -> str:
    return await db.find(id)

6. 流式事件监听

实时追踪智能体执行过程，适用于 UI 反馈或日志记录。

async for event in agent.query_stream("做点什么"):
    match event:
        case ToolCallEvent(tool=name): print(f"调用 {name}")
        case FinalResponseEvent(content=text): print(f"完成: {text}")

适用场景

• 构建轻量级自动化代理（如网页操作、数据提取）
• 快速原型验证智能体行为
• 教学演示：理解智能体本质逻辑
• 替代复杂框架，追求可审计性与可控性