工具与 CodeMode

工具让 Agent 执行动作：查询订单、读取文件，或调用一个服务。Tool 描述动作的名称、参数和结果。你可以把它直接传给 Agent，也可以在 Bub 应用中注册。

本页说明共同的工具接口和 SDK 接入方式。安装步骤与完整的模型循环示例见构建自己的 Agent。

定义工具

Tool.from_callable() 从类型注解生成参数定义，从 docstring 读取描述。它支持同步和异步函数，返回的工具由你传给 Agent。

from bub.core import Agent
from bub.core.tools import Tool


def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b


add_tool = Tool.from_callable(add, name="math.add")
agent = Agent(tools=[add_tool])

运行时保留 math.add 这个名称；提供给模型时，点会换成下划线，因此模型看到的是 math_add。也可以通过 description= 显式提供描述。

普通 Agent 会把传入的工具提供给模型，仅排除 exposure="command"。延迟加载、allowed_tools 状态和 state["code_mode"] 开关属于 BubAgent 的应用策略。在自己的 Agent 中按步骤选择工具，可以覆写 prepare_tools()。

返回调用方需要的数据

工具可以返回字典、列表、带类型的值或字符串。模型直接调用工具时，可以用 renderer 将结构化结果转成文本：

from typing import TypedDict


class Order(TypedDict):
    id: str
    status: str


def lookup_order(order_id: str) -> Order:
    """Look up an order by id."""
    return {"id": order_id, "status": "shipped"}


order_tool = Tool.from_callable(
    lookup_order,
    renderer=lambda order: f"Order {order['id']}: {order['status']}",
)

Tool.render(result) 使用这个 renderer。默认情况下，字符串直接保留，Pydantic 模型与可序列化的值转为 JSON，其他值使用 str()。面向模型的执行器在 ToolCallFinished 之前渲染结果，因此处理器看到的是将交给模型的内容。CodeMode 使用的执行器会保留结构化结果。

在模型循环中，工具执行错误会作为工具结果交回模型，让模型决定如何回答或重试。直接通过命令调用时，错误会传播给调用方。事件处理器有自己的异常规则。

访问当前会话

传入 context=True，工具就会通过关键字参数 context 接收 ToolContext。其中包含当前 Tape、本轮状态、run ID 和事件总线。

from bub.core.tools import ToolContext


async def remember(note: str, *, context: ToolContext) -> str:
    """Record a note for this conversation."""
    await context.tape.append_event("note", {"text": note})
    return "Recorded."


remember_tool = Tool.from_callable(remember, context=True)

这会在 Tape 中写入一条业务事件。默认上下文选择器读取会话消息与工具交互；要把这条事件交给模型，需要提供自己的选择逻辑。哪些已保存的信息应交给模型，由会话历史与上下文中的选择规则决定。

组合工具与 CodeMode

CodeMode 让模型编写 Python 来调用工具。它提供 run_code 工具，以及描述代码中可用工具的提示词片段。使用普通 Agent 时，需要显式加入这两部分：

from bub.core.codemode import CodeMode

code_mode = CodeMode([add_tool, order_tool])
agent = Agent(
    tools=[code_mode.run_code],
    system_prompt=[
        "Use the available tools to answer the user's question.",
        code_mode.prompt,
    ],
)

按 SDK 指南中的方式管理模型并运行 Agent。模型可以向 run_code 传入这样的代码：

order = await tools.lookup_order(order_id="A123")
print(order["status"])

在 run_code 中，工具名称使用下划线，调用使用关键字参数，结果保留结构化形式。代码支持顶层 await。工具调用经过 ToolCallStarted 和 ToolCallFinished，其中 context.code_mode=True。

CodeMode 使用你传入的工具，并排除 exposure="command"。BubAgent 通过应用代码模式设置对 auto、direct、code 工具分组。

选项	行为
tools	工具集合，或根据本轮状态返回工具集合的函数。返回 None 可以禁止本轮执行代码。
environment	代码运行的位置。默认是在当前目录运行的 LocalEnvironment()，也可以是根据状态选择环境的函数。
models	代码调用 Republic 时使用的默认 provider:model，或返回模型标识与客户端选项的解析函数。不设置时，代码需要给出模型标识，Republic 从环境读取凭据。
stub_dir	保存生成的 Python 工具定义的目录。默认直接把定义放入系统提示词；写入文件时，Agent 需要有读取该文件的能力。
media_tools	默认 True。增加用于返回媒体的 attach_image、attach_audio、attach_video。

代码可以通过 Republic 桥接接口调用聊天、嵌入和决策模型。请求经过宿主进程的模型解析器，由宿主处理这些调用的供应商凭据。

run_code 返回打印的输出和附带媒体，默认超时为 120 秒，可以通过 timeout_seconds 调整。使用 LocalEnvironment 时，每次调用都会启动一个拥有宿主用户权限的 Python 进程，在完成或取消时停止它及其子进程。如果需要不同的执行边界，请选择其他环境。

选择执行环境

bub.environment 中的 Environment 接口提供进程执行、文件访问和 Python 执行能力。CodeMode(environment=...) 使用你传入的环境。在 Bub 应用中，provide_environment hook负责为会话选择环境。

操作	职责
spawn(command, *, cwd, env)	返回进程，提供输出流、输入、等待和进程树信号控制。
read_text、write_text、read_bytes	访问环境内的文件。
workspace、resolve_path	定义工作目录并解析相对路径。
run_code(code, *, tools, call_tool, write)	执行 Python，通过 call_tool 调用工具，通过 write 输出 stdout，并在取消时停止执行。
close()	释放环境持有的资源。

环境执行生成的代码，通过回调交给宿主执行你的 Python 工具。应用不再使用自定义环境时，需要关闭它。

不经过模型调用工具

设置 command_prefix 后，就可以接收文本命令。下面使用前面定义的 add_tool，不需要模型凭据：

import asyncio


async def calculate() -> None:
    agent = Agent(tools=[add_tool], command_prefix=",")
    async with agent.run(",math.add a=2 b=3", tape="calculator") as stream:
        async for event in stream:
            if event.kind == "text":
                print(event.data["delta"])


asyncio.run(calculate())

它会打印 5。命令直接调用传入的工具，发出工具事件和 CommandFinished，不进入模型循环。前缀不能为空，也不能包含空白字符。参数可以先按位置传入，再使用 key=value。如果命令不是工具名称，而 Agent 提供了 bash 工具，就会交给它执行。

Bub 应用提供 ,skill、,code_mode 等命令。