《Cursor文档》-智能体元数据

预览¶

智能体元数据目前处于预览阶段，可能会发生变更，包括破坏性
变更。

云端代理可在 VM 内读取当前运行的键值元数据，包括智能体 ID、所有者、此轮的提交者、所用模型以及已检出的仓库。钩子和安装脚本也可以读取这些值。

智能体通过终端工具调用此 API。您无需自行发起这些请求。

要让智能体读取元数据，请在提示词中加入以下内容：

To read agent metadata, follow the instructions at
https://cursor.com/docs/cloud-agent/metadata

此 API 仅在智能体 VM 本地可用。它不是您通过 SDK 或 Cloud Agents API 创建智能体时设置的、归调用方所有的 metadata 标签。这些 API 使用 Cursor API 密钥从 VM 外部管理 agents。

当 VM 外部需要验证智能体身份时，应让智能体改为签发 OIDC 身份令牌。这些 JWT 已签名且绑定受众。元数据不是凭证，其中可能包含当前轮次的提交者和所用模型，而令牌不应携带这些信息。

由 Cursor 管理的云端代理虚拟机会通过与 OIDC 身份令牌相同的套接字提供元数据。自托管 workers 尚不提供此 API。

读取值¶

智能体通过 CURSOR_AGENT_SOCKET 指定的 Unix 套接字读取键。在由 Cursor 管理的 VM 上，默认值为 /run/cursor/api.sock。

curl --unix-socket "${CURSOR_AGENT_SOCKET:-/run/cursor/api.sock}" \
  http://cursor-agent/v1/meta-data/agent/id

请求通过 Unix 套接字使用 HTTP。URL 中的主机名会被忽略。

列出前缀，查看有哪些键：

curl --unix-socket "${CURSOR_AGENT_SOCKET:-/run/cursor/api.sock}" \
  http://cursor-agent/v1/meta-data/

agent/
owner/
turn/
workspace/

然后请求一个键：

curl --unix-socket "${CURSOR_AGENT_SOCKET:-/run/cursor/api.sock}" \
  http://cursor-agent/v1/meta-data/owner/user-id

请求¶

通过 Unix 套接字发送 GET /v1/meta-data[/<path>]。无需请求体或额外请求头。允许使用尾部斜杠，因此列出的 agent/ 可请求为 /v1/meta-data/agent/。

缺失的键返回 404。

响应¶

成功读取的内容类型为 text/plain; charset=utf-8。读取键时，响应仅包含其文本形式的值。

错误响应为 JSON。请参阅限流和错误。

键何时出现¶

安装脚本可读取同一个套接字。键仅在有值时才会出现：编码轮次开始前不会有 turn/；运行记录分支前不会有 workspace/branch-name。所有者、团队和代码仓库键从智能体创建起便可用。

如果启动后立即找不到套接字，请重试连接。

键¶

列表中会省略缺失的键；如果直接请求，则返回 404。列表仅包含当前实际存在的键。

agent/¶

owner/¶

turn/¶

仅当编码轮次处于活动状态时，turn/ 才存在。轮次之间，这些键会消失。如果缺少 turn/，则没有活动轮次。

turn/ 下的值始终反映当前轮次。请勿跨轮次缓存这些值。

OIDC 身份令牌不包含轮次提交者或提供服务的模型，因为令牌的有效期可能长于轮次。请改为从元数据中读取这些键。

workspace/¶

workspace/repo-url 表示主代码仓库。完整集合请读取 workspace/repo-urls。

谁可以读取元数据¶

任何能访问套接字的进程都可以读取所有键：智能体、它运行的代码和钩子。请将这些值视为对整个运行均可见。

元数据未经签名。要向 AWS、GCP、Vault 或你自己的服务证明身份，请让智能体签发 OIDC 身份令牌 并验证 JWT。请勿将元数据值作为凭据转发。

限流和错误¶

每个智能体 VM 每分钟最多可发起 120 个元数据请求，突发请求最多 20 个。套接字最多可同时接受 8 个连接。该上限与 OIDC 令牌签发共用。

对 429、503、500、502 和 504 采用退避策略重试。将 403 视为致命错误：该智能体无权读取元数据。

404 和 405 响应包含一个说明 API 调用方式的 usage string。限流和饱和错误仅返回错误代码：

{ "error": "not_found", "usage": "GET /v1/meta-data[/<path>] ..." }

{ "error": "rate_limited" }

示例¶

智能体或钩子可以比较本轮提交者与所有者。队友的后续操作可以采用更严格的处理路径：

SOCKET="${CURSOR_AGENT_SOCKET:-/run/cursor/api.sock}"

owner="$(curl -fsS --unix-socket "$SOCKET" \
  http://cursor-agent/v1/meta-data/owner/user-id)"
turn_user="$(curl -fsS --unix-socket "$SOCKET" \
  http://cursor-agent/v1/meta-data/turn/user-id || true)"

if [ -n "$turn_user" ] && [ "$turn_user" != "$owner" ]; then
  echo "follow-up from user $turn_user; owner is $owner"
fi

智能体或钩子可以使用智能体 ID 和处理本轮的模型为日志添加标签：

SOCKET="${CURSOR_AGENT_SOCKET:-/run/cursor/api.sock}"

agent_id="$(curl -fsS --unix-socket "$SOCKET" \
  http://cursor-agent/v1/meta-data/agent/id)"
model="$(curl -fsS --unix-socket "$SOCKET" \
  http://cursor-agent/v1/meta-data/turn/model || true)"

echo "cloud_agent_id=$agent_id model=${model:-unknown}"

列出工作区中的每个代码仓库。repo-urls 中每行一个 URL：

curl -fsS --unix-socket "${CURSOR_AGENT_SOCKET:-/run/cursor/api.sock}" \
  http://cursor-agent/v1/meta-data/workspace/repo-urls

github.com/acme/widgets
github.com/acme/docs

相关页面¶

• OIDC 身份令牌：了解已签名 JWT 和云联合
• 机密信息与网络：了解仪表盘机密信息和出站控制
• 云端代理设置：了解可读取此套接字的安装脚本
• 钩子：了解如何在工具和对话边界运行此 API
• 服务账户：了解智能体以团队服务账户身份运行的情况