> ## Documentation Index
> Fetch the complete documentation index at: https://java.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 工具

## 作用

harness 层默认为 agent 提供一套“足够走完一个闭环”的内置工具：读写文件、检索记忆与会话、委派子 agent、可选走 shell。不需手动注册，`HarnessAgent.build()` 与 `SubagentsHook` 会一起装好。

## 注册路径

```mermaid theme={null}
graph LR
    Build[HarnessAgent.build] --> R1[FilesystemTool]
    Build --> R2[MemorySearchTool]
    Build --> R3[MemoryGetTool]
    Build --> R4[SessionSearchTool]
    Build -. backend 是 sandbox .-> R5[ShellExecuteTool]
    Hook[SubagentsHook.tools<br/>非 leaf 且有 model] --> H1[AgentSpawnTool]
    Hook --> H2[TaskTool]
```

* **直接 register**：`FilesystemTool` / `MemorySearchTool` / `MemoryGetTool` / `SessionSearchTool` 必装；`ShellExecuteTool` 仅在 `backend instanceof AbstractSandboxFilesystem` 时装。
* **间接 register**：`AgentSpawnTool` 与 `TaskTool` 是 `SubagentsHook.tools()` 返回的，仅在非 leaf 且配了 `model` 时出现；在 session mode 下 `agent_*` 会被 `sessions_*` 替换。

## 文件系统·`FilesystemTool`

包装 `AbstractFilesystem`；路径是后端本地路径。

| 工具           | 作用             | 参数                                                                |
| ------------ | -------------- | ----------------------------------------------------------------- |
| `read_file`  | 读文件内容          | `path`, `offset`（0-indexed）, `limit`（0 = 读全）                      |
| `write_file` | 创建新文件          | `path`, `content`（已存在会报错）                                         |
| `edit_file`  | 精确字符串替换        | `path`, `old_string`（默认唯一）, `new_string`, `replace_all`（默认 false） |
| `grep_files` | 指定路径中搜字符串（非正则） | `pattern`, `path`, `glob`（如 `*.java`）, `limit`（默认 100，最大 1000）    |
| `glob_files` | 按 glob 查文件     | `pattern`（如 `**/*.md`）, `path`, `limit`（默认 200，最大 1000）           |
| `list_files` | 列目录            | `path`                                                            |

## 记忆·`MemorySearchTool` / `MemoryGetTool`

| 工具              | 作用                                                 | 参数                                             |
| --------------- | -------------------------------------------------- | ---------------------------------------------- |
| `memory_search` | FTS5 全文检索，最多返 30 条；MemoryIndex 不可用时 fallback 到关键字扫 | `query`                                        |
| `memory_get`    | 读记忆文件中指定行范围，输出带行号                                  | `path`（工作区相对）, `startLine`, `endLine`（1-based） |

> 参数名是驼峰（`startLine` / `endLine`），与 filesystem 的 snake\_case 不一致。

## 会话·`SessionSearchTool`

| 工具                | 作用                                | 参数                                          |
| ----------------- | --------------------------------- | ------------------------------------------- |
| `session_search`  | 在会话 JSONL 中扫关键词                   | `query`, `agentId`（可选）, `maxResults`（默认 10） |
| `session_list`    | 列某个 agent 的会话，优先读 `sessions.json` | `agentId`                                   |
| `session_history` | 返某个会话最近 N 条消息                     | `agentId`, `sessionId`, `lastN`（默认 20）      |

> 参数名都是驼峰，且 `session_search` 返回结果是扫全部 `agents/<agentId>/sessions/*.jsonl` 后的“首次命中 10 条”，**不是**按相关性排序。

## 子 Agent·`AgentSpawnTool`

| 工具            | 作用                | 参数                                                                                             |
| ------------- | ----------------- | ---------------------------------------------------------------------------------------------- |
| `agent_spawn` | 创建临时子 agent、可选走任务 | `agent_id`（必填）, `task`（可选，留空仅建 session）, `label`（可选别名）, `timeout_seconds`（默认 30，`0`=后台，上限 600） |
| `agent_send`  | 向已存在子 agent 补一条   | `agent_key` 或 `label`（二选一）, `message`, `timeout_seconds`                                       |
| `agent_list`  | 列当前子 agent        | 无                                                                                              |

```
agent_spawn agent_id="research-analyst"
            task="调研主题 X"
            timeout_seconds=60

# 异步
agent_spawn agent_id="research-analyst" task="全库安全审计" timeout_seconds=0
# → agent_key + task_id
```

Session mode 下，这三个名会变为 `sessions_spawn` / `sessions_send` / `sessions_list`。

## 后台任务·`TaskTool`

| 工具            | 作用         | 参数                                                             |
| ------------- | ---------- | -------------------------------------------------------------- |
| `task_output` | 拿后台任务结果    | `task_id`, `block`（默认 true）, `timeout` 默认 30000ms，上限 600000ms  |
| `task_cancel` | 取消任务；终态不生效 | `task_id`                                                      |
| `task_list`   | 列任务        | `status_filter`：running / completed / failed / cancelled / all |

## Shell·`ShellExecuteTool`（条件性装）

仅在后端是 `AbstractSandboxFilesystem`（包含 `LocalFilesystemWithShell`）时才被注册。如果你用的是纯 `LocalFilesystem` 或 `RemoteFilesystem`，子工具不出现。

| 工具        | 作用                                   | 参数                                                                               |
| --------- | ------------------------------------ | -------------------------------------------------------------------------------- |
| `execute` | 走后端 `execute()`，返 stdout + exit code | `command`, `working_directory`（可选，实际拼接为 `cd <dir> && <cmd>`）, `timeout`（秒，默认 30） |

> **注意**：@Tool 未显式设 `name`，默认取方法名，所以 LLM 看到的工具名是 `execute`。如果后续统一为 `shell_execute` 是个小重构，参见 [roadmap](/v1/zh/docs/harness/overview)。

```
execute command="find . -name '*.java' | wc -l"
execute command="mvn test" timeout=300
execute command="git status" working_directory="app"   # 拼为 cd app && git status
```

## 相关文档

* [文件系统](/v1/zh/docs/harness/filesystem) — 后端实现与沙箱接口
* [记忆](/v1/zh/docs/harness/memory) — `memory_search` / `memory_get` 背后的 FTS5 与双层记忆
* [会话](/v1/zh/docs/harness/session) — `session_*` 系列背后的 `WorkspaceSession` / `SessionTree` 双轨
* [子 Agent](/v1/zh/docs/harness/subagent) — `agent_spawn` / `agent_send` / `task_*` 的调度与生命周期