OpenHuman Tools Agent 系统提示词与运行时机制解析：内置工具专家如何完成通用执行任务

OpenHuman Tools Agent 系统提示词与运行时机制解析：内置工具专家如何完成通用执行任务

【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman

Tools Agent（tools_agent）是 OpenHuman 多智能体编排体系中的内置通用执行专家，它只依赖 OpenHuman 自身的 system-category 内置工具（shell 命令、文件读写、HTTP 请求、Web 搜索、内存查询等）完成零散的临时任务，并明确与持有 Composio 托管 OAuth 集成的integrations_agent、负责代码仓库修改的code_executor划清职责边界。本文以该智能体的系统提示词文档 prompt.md 为主线，结合其运行时配置 agent.toml、提示词构建器 prompt.rs 与委派工具实现 archetype_delegation.rs，逐层拆解它的角色定义、运行规则、工具面与委派链路，帮助读者理解 OpenHuman 智能体注册表与子智能体执行器的设计哲学。

一、角色定位：只碰内置工具的通用执行专家

tools_agent在注册表元数据中的官方定位（when_to_use）是：

Generalist for heavyweight ad-hoc execution that does NOT touch a code repository: host shell, HTTP, web search, file reads. It cannot edit files or use git, so repo-scoped work goes to the code worker and managed Composio integrations go to the integrations agent.

即：承担不触碰代码仓库的重型临时执行任务——宿主 shell、HTTP、Web 搜索、文件读取。它既不能编辑文件，也不能使用 git，因此仓库范围内的工作路由给 code worker（code_executor），受管 Composio 集成工作路由给integrations_agent。

系统提示词开篇用一句话完成了角色声明（prompt.md）：

You are theTools Agent. You complete ad-hoc tasks using only OpenHuman's built-in tool surface: shell commands, file I/O, HTTP requests, web search, memory lookups, and the rest of the system-category tools in your tool list.

这里有两个关键限定词值得展开：

• ad-hoc tasks（临时任务）：Tools Agent 不是常驻对话智能体，它由编排器（orchestrator）按需委派生成，任务是单次性的、目标明确的执行请求，完成后即返回摘要。
• built-in tool surface（内置工具面）：它只能看见 OpenHuman 系统自带的工具类别，这与prompt.rs模块级注释完全一致——"Composio-free specialist that only ever sees OpenHuman's built-in (system-category) tools — shell, file I/O, HTTP, web search, memory"（见 prompt.rs）。

二、职责边界：什么能做、什么必须上报

prompt.md用 "## Scope" 一节把能力边界写得非常刚性：

• 不允许：访问 Composio / 托管 OAuth 集成。凡是需要在外部 SaaS 账号（Gmail、Notion、GitHub、Slack 等）上执行动作的任务，必须停下来上报——由编排器改派携带正确工具包的integrations_agent。
• 被允许：运行命令、在工作区内读写文件、抓取网页、检索用户记忆、查询结构化数据、串联简单转换。

这一边界并非只在提示词层面靠模型自觉遵守，而是在运行时由工具列表构造环节强制执行的。agent.toml中工具配置的注释揭示了底层机制（agent.toml）：

[tools] # Wildcard — the agent inherits the orchestrator's full built-in tool # surface. Composio meta-tools and dynamic `<TOOLKIT>_*` action tools are # stripped at runtime (see `filter_non_composio_indices` in the subagent # runner), so the LLM never sees integration-specific tools here; those belong # to `integrations_agent`. Specialist-owned trading tools are also # stripped via `disallowed_tools` above so they route through their dedicated # agents exclusively. wildcard = {}

也就是说，Tools Agent 采用通配符（wildcard）继承策略：它继承编排器的完整内置工具面，但子智能体执行器（subagent runner）在运行时通过filter_non_composio_indices将 Composio 元工具与动态<TOOLKIT>_*action 工具剥离。模型在提示词层面"看不到"集成专用工具，这一设计从工具发现源头堵死了越权路径。

从源码结构可以推断，这一过滤发生在 subagent_runner 的工具准备环节：runner.rs中动态注册 Composio 每动作工具的代码路径（见 runner.rs 中fetch_toolkit_actions与ComposioActionTool::new的调用点）针对不同 agent 做了条件化，而tool_prep.rs则负责工具列表的最终装配。

三、运行时配置解读：agent.toml 逐项拆解

agent.toml 是 Tools Agent 在注册表中的完整定义，几个关键字段直接影响其行为：

将omit_identity = true与编排器（orchestrator）的omit_identity = false对比，可以清晰看出职责分层：编排器是面向用户的"人设"层，需要加载工作区 SOUL.md / ROLE.md 维持产品人格；而 Tools Agent 是纯执行器，刻意去掉身份段以省 token、避免角色干扰。同理omit_memory_context = true说明执行任务默认不携带记忆上下文，需要记忆时通过内存查询工具按需取用——这与编排器"按需检索记忆"的设计（orchestrator 中agent_memory改为按需委派、而非每轮预取）一脉相承。

四、系统提示词如何构建：prompt.rs 的拼接流水线

Tools Agent 的系统提示词不是硬编码字符串，而是由 prompt.rs 中的build()函数在运行时动态组装。整个流程分四段拼接：

1. 架构提示词：include_str!("prompt.md")在编译期把 prompt.md 嵌入二进制，作为角色基座（ARCHETYPE常量）。
2. 用户文件上下文：render_user_files(ctx)渲染与任务相关的用户文件清单。
3. 工具列表：render_tools(ctx)渲染当前可见的工具清单与调用格式。
4. 工作区上下文：render_workspace(ctx)渲染工作区目录结构等信息。

build()的实现（见 prompt.rs）从PromptContext中读取这些片段，仅在非空时才追加，避免产生无意义的空段。这种"基座 + 动态上下文"的设计让同一份 prompt.md 可以复用于不同会话，而上下文（工具列表、工作区、用户文件）随运行时状态变化。

配套的单元测试 prompt_tests.rs 验证了build()的两个基本契约：返回体非空、且包含 "Tools Agent" 标识——确保架构提示词确实被嵌入最终系统提示。

五、运行规则逐条解析：提示词中的 5 条操作铁律

prompt.md的 "## Operating rules" 一节给出了 Tools Agent 的行为守则，这是执行质量的保障，值得逐条理解其设计意图：

1. Plan briefly, then act. Prefer one well-chosen tool call over exploratory flailing.（先简短规划再行动，宁选一次精心选择的工具调用，也不要试探性乱试。）——直接抑制 LLM 常见的"试错式"调用浪费，与max_iterations = 10的预算约束配套。
2. Read before you write.（写之前先读。）——凡任务涉及既有数据，先检查工作区或远端状态，避免盲写覆盖。
3. Keep tool output tight.（保持工具输出精简。）——不要把大段文件内容原样回传调用方，要么摘要，要么写入工作区文件后返回路径。这与编排器侧对超大工具结果的处理策略（summarizer_payload_threshold_tokens机制，见 orchestrator 配置注释）构成双向约束。
4. Surface blockers early.（尽早暴露阻塞项。）——如果必需工具不在自己的工具列表里，要在最终回复中明说，而不是假装推进。这是对"Scope"边界规则的可执行化补充。
5. When the task is done, reply with a concise summary.（任务完成后，给出简洁摘要并附相关路径/标识符，不要逐字复述工具输出。）——保证委派结果能作为证据回流到编排器的结构化交接中。

六、委派链路：编排器如何把任务交给 Tools Agent

Tools Agent 本身没有"主动出击"的能力，它由编排器通过委派工具拉起。在 orchestrator/agent.toml 的[subagents] allowlist中，tools_agent被显式列出（见"tools_agent"条目）。编排器构建时，collect_orchestrator_tools帮助函数会为 allowlist 中的每个裸 agent ID 合成一个ArchetypeDelegationTool，其工具名为delegate_{id}——因此对 Tools Agent 而言就是delegate_tools_agent（见 archetype_delegation.rs 的注释）。

委派工具的实现有几个关键设计点：

• 委派信封（envelope）：parameters_schema定义了prompt（必填）、objective、evidence（仅限真实观察到的 facts/paths/URLs/ids/tool outputs，这是反捏造契约）、constraints、must_not_assume、expected_output、citation_requirement、model（可固定子智能体模型）、blocking（默认 false 表示异步 worker，true 表示同步等待且结果门控本轮回复）等字段（见 archetype_delegation.rs）。
• 无超时截断：timeout_policy返回ToolTimeout::Unbounded，理由是委派工具的本质是把任务交给一个有界子智能体（受其自身max_iterations、取消令牌、内部每个工具的超时约束），若沿用默认 120 秒单工具超时，任何超过两分钟的子智能体运行都会被中途硬杀——历史上delegate_tools_agent就出现过大量 120.000s 截断（Sentry TAURI-RUST-K29）。
• 执行权限：permission_level为Execute、category为System。

由此，一次完整的执行链路是：用户请求 → 编排器判断任务画像（重型、非代码仓库、仅需内置工具）→ 调用delegate_tools_agent→ 子智能体执行器构造 Tools Agent 上下文（拼接 prompt.md + 工具清单 + 工作区）→ 子智能体运行至max_iterations内完成 → 结果以结构化证据回流编排器。

七、横向分工：与相邻智能体的边界

Tools Agent 的存在价值很大程度体现在"不做什么"上。结合注册表目录（registry/agents）可以画出清晰的职责矩阵：

这种"通用执行 + 专用工具托管"的分层，配合运行时工具过滤（filter_non_composio_indices），保证了通用执行器保持轻量工具面，而高风险、领域专用的工具（配置写入、任务板、加密钱包、集成动作）始终由携带专属策略的专用智能体独占。

八、小结

从一份不足 30 行的系统提示词出发，可以窥见 OpenHuman 智能体注册表设计的完整闭环：prompt.md定义角色心智（只碰内置工具、边界刚性的 Scope、5 条操作铁律）；agent.toml 以声明式元数据固化运行参数（temperature、max_iterations、sandbox_mode、model hint、wildcard 工具面）；prompt.rs 负责把基座与动态上下文拼接成最终系统提示；编排器侧的 ArchetypeDelegationTool 则打通了委派链路并提供了无超时截断、证据回传等工程保障。理解 Tools Agent，也就理解了 OpenHuman 如何用"职责边界 + 运行时过滤 + 结构化委派"三件套，让通用执行任务在多智能体体系中有序、可控、可审计地落地。

【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman