# 通过智能体使用 Humanbased


这篇指南让智能体读取一页已获授权的数据，并报告结果。请求使用 `from=beginning`，不会推进订阅共享的增量读取位置。

这篇指南面向你在平台外使用的智能体。活动工作流中的 Agent 节点另在 Builder 中配置。

## 确定接口与任务范围

| 方式 | 怎样使用 |
| --- | --- |
| HTTP API | 本文直接调用 `GET /v1/live/pull`，使用组织提供的 API Key |
| Humanbased CLI | 使用组织提供的受支持版本，通过 `hb --help --json` 查看该版本的命令 |
| MCP 客户端 | 使用组织提供的集成及其连接地址、工具契约和认证配置；本文的 HTTP 路径不需要 MCP |
| 浏览器 | 管理凭证，完成需要本人阅读、确认或接受的操作 |

执行前明确组织、环境、Subscription ID、最多读取多少条，以及允许在报告中披露什么。再指定一个组织批准的输出目录：它必须已经存在，智能体只在它下面写入。访问授权与向智能体服务商发送数据的许可分别确认。数据不允许发给外部服务时，在组织批准的环境中读取，只提供获准的摘要。

## 配置访问凭证

先按[创建和使用 API Key](/zh/api/api-auth)选择组织和订阅。通过智能体运行环境的密钥配置提供 `HB_API_KEY`，通过环境变量提供 `HB_SUBSCRIPTION_ID`。再用 `HB_AGENT_OUTPUT_PARENT` 提供获准输出目录的绝对路径。完整 Key 只留在密钥配置里，提示词、代码库、日志和报告中都不出现。

API Key、订阅与请求地址应属于同一环境。下面使用正式地址 `https://api.humanbased.ai`。订阅的数据读取权限与活动编辑权限分别授权；能够编辑活动的凭证不一定能读取其交付数据。

## 给智能体一份明确的指令

智能体需要一份能完整读取的参考。本文档的每个页面都同时以 Markdown 提供：在页面路径前加上 `/markdown`，并把结尾的 `/` 换成 `.md`。[接口参考](/zh/api/api-fields)对应的地址是：

```text
https://docs.humanbased.ai/markdown/zh/api/api-fields.md
```

把这个地址交给智能体，或交给它用页面上的 **下载 Markdown** 链接保存的文件，让它读 Markdown 而非 HTML 页面。同时记下站点页眉显示的文档版本和取得日期，日后可以认出智能体当时用的是哪一份。

然后提供下面的任务说明：

```text
以 Markdown 阅读 Humanbased 数据读取接口参考：
https://docs.humanbased.ai/markdown/zh/api/api-fields.md
参考副本：文档版本 <版本>，取得日期 <日期>。
使用这份 Markdown 文本，不使用 HTML 页面。读不到时，先索取文档再执行。

使用 https://api.humanbased.ai。
HB_API_KEY 和 HB_SUBSCRIPTION_ID 由运行环境提供。不得输出密钥。

只请求 GET /v1/live/pull 的一页数据：
subscription_id：已提供的订阅
from：beginning
limit：5

HB_AGENT_OUTPUT_PARENT 是获准的输出目录。
在它下面新建一个目录，把完整响应保存在里面，其他位置一律不写。
变量未设置或目录不存在时，停止并报告，不要另选位置。

不要继续分页、切换增量模式、创建密钥、修改订阅、接受协议或修改 Campaign。

报告 HTTP 状态、success、条目数、是否有下一页，以及保存文件的完整路径。
报告中不要包含原始记录内容。
访问被拒绝或响应不完整时，停止并报告错误，不尝试更换凭证或扩大范围。
```

任务说明限定你授权智能体做什么；服务端仍按凭证与资源检查实际权限。

## 执行读取

在获准的 bash 或 zsh 环境执行下面的请求。没有获准目录时它拒绝执行；目录存在时，它在其下新建一个仅当前用户可访问的目录，保存响应，并打印 HTTP 状态。

```sh
if [ -z "${HB_AGENT_OUTPUT_PARENT:-}" ] || [ ! -d "$HB_AGENT_OUTPUT_PARENT" ]; then
  printf 'Stop: HB_AGENT_OUTPUT_PARENT must name the approved, existing output directory.\n' >&2
else
  HB_AGENT_OUTPUT="$(mktemp -d "$HB_AGENT_OUTPUT_PARENT/hb-read.XXXXXX")" &&
    printf 'Response directory: %s\n' "$HB_AGENT_OUTPUT" &&
    curl --silent --show-error --get \
      'https://api.humanbased.ai/v1/live/pull' \
      --header "Authorization: Bearer $HB_API_KEY" \
      --data-urlencode "subscription_id=$HB_SUBSCRIPTION_ID" \
      --data-urlencode 'from=beginning' \
      --data-urlencode 'limit=5' \
      --output "$HB_AGENT_OUTPUT/page.json" \
      --write-out 'HTTP %{http_code}\n'
fi
```

智能体应检查保存的 JSON，确认 `success=true`，并比较 `data.count` 与 `data.items` 的实际条目数。用这些结果判断本次读取是否成功。

再核对响应落在哪里。报告的路径应位于获准目录之下，文件也确实在那里：

```sh
case "$HB_AGENT_OUTPUT" in
  "$HB_AGENT_OUTPUT_PARENT"/*) ls -l "$HB_AGENT_OUTPUT/page.json" ;;
  *) printf 'Outside the approved directory: %s\n' "$HB_AGENT_OUTPUT" >&2 ;;
esac
```

一份完成报告可以采用下面的格式。这里的数值仅说明报告结构，应替换为真实响应的结果：

```text
环境：production
操作：订阅从头读取，只读一页
HTTP 状态：200
API success：true
保存条目数：5
还有下一页：true
获准目录：<HB_AGENT_OUTPUT_PARENT 的值>
响应文件：<获准目录>/hb-read.Ab12Cd/page.json
覆盖范围：只读取了一页，没有继续分页
参考：api-fields.md，文档版本 <版本>，取得日期 <日期>
```

条目为空时，报告“没有可读记录”。条目非空时，按本页的真实数量报告，并注明还可以继续分页与否。

## 按结果继续

| 结果 | 含义 | 下一步 |
| --- | --- | --- |
| 获准目录未设置或不存在 | 没有可以写入的位置 | 停止并报告，由负责人提供目录 |
| 成功且非空 | 本页记录已返回 | 报告条目数、分页状态和保存文件的完整路径，然后停止 |
| 成功但为空 | 这次请求没有返回可读记录 | 请负责人检查交付、订阅范围、模式和筛选 |
| 401 或 403 | 凭证或访问检查未通过 | 停止，通过获准渠道处理凭证或权限 |
| 参数错误 | 请求不符合接口要求 | 在原授权范围内修正参数 |
| 从头读取中断 | 本地文件可能不完整 | 任务允许重试时，重发相同的从头读取请求，并只保留完整响应 |
| 返回结构无法识别 | 尚不能判断结果 | 保留脱敏诊断，停止并联系支持 |

增量请求即使使用 HTTP GET，也会推进整个订阅共享的读取位置，并可能计费。丢失增量响应后，再请求一次可能已进入下一页。此时应从已取得范围重读，并与本地保存的记录核对，找回缺失的条目。

## 使用 CLI 或增加写操作

组织已提供 CLI 时，先查看 `hb --help --json` 与 `hb capabilities --json`，再确认当前环境和凭证。执行每项操作时，服务器还会检查凭证对具体资源的权限。

版本中有 `campaign records pull` 时，它可以读取一个活动在某项订阅内已交付的记录。给智能体的边界与上面的 HTTP 示例相同：只读一页，Key 只交给这一条命令，输出写在获准目录之下。

```sh
mkdir -p "$HB_AGENT_OUTPUT/tmp"
TMPDIR="$HB_AGENT_OUTPUT/tmp" HB_API_KEY="$HB_API_KEY" hb campaign records pull <campaign-id> \
  --subscription "$HB_SUBSCRIPTION_ID" \
  --limit 5 --json > "$HB_AGENT_OUTPUT/records-page.json"
```

加上 `--json` 时，CLI 会先把记录写进一个只有当前用户可读的临时文件，命令结束时删除。设置 `TMPDIR` 后，这个文件也留在获准目录之下。不设置时，它会写到系统的临时目录。

不加 `--all` 时，命令只读一页并返回 `next_cursor`。导出所有页另有一套完成条件：允许智能体使用 `--all` 之前，先把[导出全部交付记录](/zh/api/cli#导出全部交付记录)交给它。

`hb --help --json` 没有列出这条命令时，改用上面的 HTTP 请求。安装前先向组织确认受支持的 CLI 版本和取得方式。

在允许智能体写入之前，明确目标资源、预期影响、需要本人确认的步骤、请求键以及结果查询方式。网络超时不证明写入失败。发生结果不明的发布或其他写操作时，先查原请求记录，再决定如何恢复。

需要帮助时，向 [hello@humanbased.ai](mailto:hello@humanbased.ai) 提供环境、请求时间、HTTP 状态和脱敏错误。