如何为OpenHands Software Agent SDK编写自定义工具：从定义到注册的完整教程-育师

【免费下载链接】software-agent-sdk

A clean, modular SDK for building AI agents with OpenHands V1.

项目地址：https://gitcode.com/gh_mirrors/so/software-agent-sdk

OpenHands Software Agent SDK 是一个用于构建 AI 智能体的模块化 SDK，而「自定义工具」正是它最有扩展性的能力之一。本教程带你走通完整流程：如何为 OpenHands Software Agent SDK 定义一个自定义工具——从输入（Action）、输出（Observation）、执行器（ToolExecutor）到最终用register_tool()注册并挂载给 Agent。只需 4 步，你就能让 AI 智能体获得调用你专属 API、查询数据库或执行领域逻辑的能力 🚀

一、先看全貌：一个自定义工具由 4 部分组成

在 Software Agent SDK 中，每一个工具都是「契约 + 实现」的组合，核心代码位于 openhands-sdk/openhands/sdk/tool/ 目录：

组成	基类	职责	源码位置
Action	`Action`	定义工具的输入参数（LLM 提供什么）	schema.py
Observation	`Observation`	定义工具的返回结果（LLM 看到什么）	schema.py
Executor	`ToolExecutor`	工具的实际执行逻辑	tool.py
ToolDefinition	`ToolDefinition`	把上面三者装配成一个完整工具	tool.py

注册中心在 registry.py 中，register_tool()负责把工具类按名字登记到全局目录，供Tool(name=...)按名解析。

二、第一步：定义 Action 与 Observation（工具的输入输出）

Action和Observation都是 Pydantic 模型，字段上可以直接写Field(description=...)——这些描述会原样进入 LLM 的工具提示词，写得越清楚，LLM 调用越准确💡。

以官方示例 02_custom_tools.py 中的 grep 工具为例：

class GrepAction(Action): pattern: str = Field(description="Regex to search for") path: str = Field(default=".", description="Directory to search") include: str | None = Field(default=None, description="Optional glob (e.g. '*.py')") class GrepObservation(Observation): matches: list[str] = Field(default_factory=list) files: list[str] = Field(default_factory=list) count: int = 0

一个实用技巧：为 Observation 重写to_llm_content属性，把原始数据整理成 LLM 友好的精简文本（比如只返回前 10 条匹配），既省 token 又提高可读性。

三、第二步：实现 ToolExecutor（核心逻辑）

ToolExecutor定义了__call__(action, conversation) -> Observation接口（见 tool.py）。它接收 Action，执行真实工作，返回 Observation：

class GrepExecutor(ToolExecutor[GrepAction, GrepObservation]): def __call__(self, action: GrepAction, conversation=None) -> GrepObservation: cmd = f"grep -rHnE {pat} {root_q} | head -100" result = self.terminal(TerminalAction(command=cmd)) # 解析输出，组装成 GrepObservation 返回 return GrepObservation(matches=matches, files=files, count=len(matches))

如果工具需要持有资源（如终端连接、数据库句柄），可以在__init__中初始化，并覆写close()做清理。

四、第三步：编写 ToolDefinition 并注册

ToolDefinition必须实现一个类方法create(cls, conv_state, **params)，它负责创建 Executor 并返回工具实例列表。conv_state里可以拿到当前工作目录（conv_state.workspace.working_dir）等上下文：

class GrepTool(ToolDefinition[GrepAction, GrepObservation]): @classmethod def create(cls, conv_state, terminal_executor=None) -> Sequence[ToolDefinition]: if terminal_executor is None: terminal_executor = TerminalExecutor( working_dir=conv_state.workspace.working_dir ) return [ cls( description=_GREP_DESCRIPTION, # 给 LLM 看的工具说明 action_type=GrepAction, observation_type=GrepObservation, executor=GrepExecutor(terminal_executor), ) ] # 注册：注册后即可通过名字使用 register_tool("GrepTool", GrepTool)

两个细节值得注意：

工具名name会由类名自动生成（GrepTool→grep），也可以在注册时显式指定；
description是 LLM 唯一看到的"说明书"，建议说明何时该用这个工具、参数如何配合，完整写法可参考 02_custom_tools.py 和内置 glob 工具 definition.py。

五、第四步：把工具交给 Agent 运行

注册完成后，只需用Tool(name=...)引用即可（见 registry.py 的解析逻辑）：

tools = [ Tool(name=FileEditorTool.name), Tool(name=BashAndGrepToolSet.name), # 你的自定义工具 ] agent = Agent(llm=llm, tools=tools) conversation = Conversation(agent=agent, workspace=cwd) conversation.send_message("用 grep 工具找出所有包含 'class' 的 Python 文件") conversation.run()

一个进阶技巧：多个工具可以共享同一个 Executor（例如上例中 terminal 和 grep 共享一个终端会话），只需把它们打包成一个 ToolDefinition 在create()中一并返回即可。