【免费下载链接】software-agent-sdkA 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/ 目录组成基类职责源码位置ActionAction定义工具的输入参数LLM 提供什么schema.pyObservationObservation定义工具的返回结果LLM 看到什么schema.pyExecutorToolExecutor工具的实际执行逻辑tool.pyToolDefinitionToolDefinition把上面三者装配成一个完整工具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(descriptionRegex to search for) path: str Field(default., descriptionDirectory to search) include: str | None Field(defaultNone, descriptionOptional glob (e.g. *.py)) class GrepObservation(Observation): matches: list[str] Field(default_factorylist) files: list[str] Field(default_factorylist) count: int 0一个实用技巧为 Observation 重写to_llm_content属性把原始数据整理成 LLM 友好的精简文本比如只返回前 10 条匹配既省 token 又提高可读性。三、第二步实现 ToolExecutor核心逻辑ToolExecutor定义了__call__(action, conversation) - Observation接口见 tool.py。它接收 Action执行真实工作返回 Observationclass GrepExecutor(ToolExecutor[GrepAction, GrepObservation]): def __call__(self, action: GrepAction, conversationNone) - GrepObservation: cmd fgrep -rHnE {pat} {root_q} | head -100 result self.terminal(TerminalAction(commandcmd)) # 解析输出组装成 GrepObservation 返回 return GrepObservation(matchesmatches, filesfiles, countlen(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_executorNone) - Sequence[ToolDefinition]: if terminal_executor is None: terminal_executor TerminalExecutor( working_dirconv_state.workspace.working_dir ) return [ cls( description_GREP_DESCRIPTION, # 给 LLM 看的工具说明 action_typeGrepAction, observation_typeGrepObservation, executorGrepExecutor(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(nameFileEditorTool.name), Tool(nameBashAndGrepToolSet.name), # 你的自定义工具 ] agent Agent(llmllm, toolstools) conversation Conversation(agentagent, workspacecwd) conversation.send_message(用 grep 工具找出所有包含 class 的 Python 文件) conversation.run()一个进阶技巧多个工具可以共享同一个 Executor例如上例中 terminal 和 grep 共享一个终端会话只需把它们打包成一个 ToolDefinition 在create()中一并返回即可。六、进阶在远程 Agent Server 中使用自定义工具如果你的 Agent 跑在远程沙箱Agent Server里自定义工具必须打包进服务端环境。官方示例 06_custom_tool/ 演示了完整方案把工具代码放进custom_tools/目录如 log_data.py一个把结构化数据写入 JSON 文件的LogDataTool在 Dockerfile 中拷贝该目录并设置OH_EXTRA_PYTHON_PATH环境变量创建会话时SDK 会自动收集客户端注册表的工具模块名发送给服务端触发动态注册工具随即可用。详细步骤见该示例的 README.md里面附了一份「从零写一个自定义工具」的完整模板代码。七、小结与参考资料回顾一下为 Software Agent SDK 编写自定义工具的 4 步法 ✅定义Action输入与Observation输出写好description实现ToolExecutor完成核心执行逻辑编写ToolDefinition.create()装配工具并调用register_tool()注册用Tool(name...)挂到 Agent 上启动 Conversation 即可。 继续深入可阅读自定义工具完整示例examples/01_standalone_sdk/02_custom_tools.py内置工具实现参考可直接抄作业openhands-tools/openhands/tools/工具注册机制源码openhands-sdk/openhands/sdk/tool/registry.py远程服务端自定义工具examples/02_remote_agent_server/06_custom_tool/仓库总览与快速上手README.md赞分享【免费下载链接】software-agent-sdkA clean, modular SDK for building AI agents with OpenHands V1.项目地址https://gitcode.com/gh_mirrors/so/software-agent-sdk点击查看免费下载相关推荐如何为Espruino编写自定义JavaScript库从入门到精通的完整指南如何为Espruino编写自定义JavaScript库从入门到精通的完整指南 Espruino是一款轻量级JavaScript解释器专为嵌入式设备设计让开编译器/解释器物联网claude-agent-sdk-python 自定义 Agent 完整指南从 Markdown 文件到 AgentDefinition 编程式定义claude agent sdk python 自定义 Agent 完整指南从 Markdown 文件到 AgentDefinition 编程式定义 本指南以人工智能AI Agent工具调用MCP Clients大模型如何为Superpowers编写自定义技能从创意到发布的完整流程如何为Superpowers编写自定义技能从创意到发布的完整流程 Superpowers技能库为Claude Code提供了强大的扩展能力让AI能够掌握各种AI 技能AI 插件开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
