《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
• 服務賬戶：瞭解智能體以團隊服務賬戶身份運行的情況