<a id="agents-operations"></a>

# `agents` 操作

<!-- i18n: source=docs/reference/operations/agents.md blob=11cf9820829edf06a3d6f59c965320b48916ba68 model=claude-sonnet-5-5 -->
> 本页由机器从[英文原文](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/agents.md)翻译，内容以英文原文为准。
> Machine-translated from the [English page](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations/agents.md), which is authoritative.


每个 `agents.*` 操作接受和返回的确切字段。

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

每个 op 都是 HTTP 上的 `POST /v1/<op>`，同时也是 MCP 工具 `loom_<op>`。身份字段（`org`、`namespace`、`agent`、`user_id`、`session_id`）在传输层能够提供时，会由令牌和 MCP 会话自动填充；对于单用户服务器上不带令牌的 HTTP 调用，除 `code.*` 和 `tracker.*`（它们沿用各自平面的设置）之外的所有 op 都使用该安装的 org，而[部分 op](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)的命名空间和 agent 也会如此处理；参见[身份与命名空间](/zh-CN/concepts/identities-and-namespaces)。[操作索引](https://github.com/ClickHouse/loom/blob/main/docs/reference/operations.md)说明了 role、kind 以及 MCP 的 `all` 列表。未知的输入字段会照常处理，并列在 `ignored_args` 中。

<!-- prettier-ignore-start -->

<a id="agentsconnected"></a>

## `agents.connected`

某个时间窗口内活跃的 agent：每个 agent 的最后活跃时间、操作数和成本。

`POST /v1/agents.connected` · MCP `loom_agents_connected` · role `viewer` · read

| 输入字段 | 类型 | 默认值 | 含义 |
| --- | --- | --- | --- |
| `org` | `str` | 必填 | 租户（身份元组的第一个元素）。 |
| `namespace` | `str \| None` | `None` | 为空时，汇总整个 org 中调用方可见的所有命名空间。 |
| `window_hours` | `int` | `24` | 回溯多长时间。24 小时是检查“重启是否生效”的合适默认值；做趋势查看时可调大。 |
| `count_only` | `bool` | `False` | 侧边栏的徽标只需要一个数字（窗口内首次出现且执行过操作的 agent 数量），而不是每个 agent 的行。 |

| 输出字段 | 类型 | 含义 |
| --- | --- | --- |
| `rows` | `list[ConnectedAgent]` | 窗口内出现的每个 agent 一行，按最近活跃时间倒序；使用 `count_only` 时，或调用方无法读取该 org 中任何命名空间时为空。 |
| `window_hours` | `int` | 这些行所覆盖的回溯时长，单位为小时（与请求一致）。 |
| `new_count` | `int \| None` | 使用 `count_only` 时，为窗口内首次出现且至少执行过一次 op 的 agent 数量；否则为 None。 |

<!-- prettier-ignore-end -->
