エージェント メタデータ
エージェント メタデータはプレビュー段階であり、破壊的変更を含め、変更される可能性があります。
Cloud Agents は、現在の実行に関するキーと値のメタデータを VM 内から読み取れます。エージェント ID、所有者、このターンの送信者、使用中のモデル、チェックアウトされているリポジトリなどです。フックとインストール スクリプトでも、これらの値を読み取れます。
エージェントはターミナル ツールを使用してこの API を呼び出します。これらのリクエストを自分で実行する必要はありません。
エージェントにメタデータを読み取らせるには、プロンプトに次を含めます：
To read agent metadata, follow the instructions athttps://cursor.com/docs/cloud-agent/metadataこの API はエージェント VM 内でのみ使用できます。SDK または Cloud Agents API でエージェントを作成するときに設定する、呼び出し元が所有する metadata タグではありません。これらの API は Cursor API キーを使用して VM 外部からエージェントを管理します。
VM 外部からエージェントの ID を確認する必要がある場合は、代わりにエージェントに OIDC トークン を発行させてください。これらの JWT には署名が付与され、オーディエンスに紐付けられます。メタデータは認証情報ではありません。現在のターンの送信者や使用中のモデルを含めることができますが、トークンに含めるべき情報ではありません。
Cursor 管理の Cloud Agent の VM は、OIDC トークンと同じソケットでメタデータを提供します。セルフホスト型ワーカーは、まだこの 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 が返されます。
レスポンス
読み取りに成功した場合の Content-Type は text/plain; charset=utf-8 です。キーのレスポンスは、値のみをテキストとして返します。
| 種類 | 本文 |
|---|---|
| キー | 文字列としての値。複数の値を持つキーでは、エントリを 1 行に 1 つずつ表示します。 |
| プレフィックス | 子要素を 1 行に 1 つずつソートして表示します。ネストされたプレフィックスは / で終わります。一覧の末尾には改行が付きます。 |
エラーレスポンスは JSON です。レート制限とエラーを参照してください。
キーが表示されるタイミング
インストールスクリプトは、同じソケットを読み取れます。キーは値がある場合にのみ存在します。コーディングターンが開始されるまでturn/は存在せず、実行時にブランチが記録されるまでworkspace/branch-nameは存在しません。オーナー、チーム、リポジトリのキーは、エージェントの作成時から利用できます。
起動直後にソケットが見つからない場合は、接続を再試行してください。
キー
存在しないキーは一覧に表示されず、直接リクエストすると 404 が返されます。一覧には、現時点で存在するキーのみが含まれます。
agent/
| キー | 存在する場合 | 説明 |
|---|---|---|
agent/id | 常に | Cloud Agent ID (bcId) 。 |
agent/name | 判明している場合 | ダッシュボードに表示される名前。 |
agent/source | 判明している場合 | WEBSITE、API、SLACK、AUTOMATIONS など、エージェントの起動方法。 |
agent/runtime | 常に | Cursor 管理の Cloud Agent VM では managed。 |
owner/
| キー | 存在する場合 | 説明 |
|---|---|---|
owner/user-id | 判明している場合 | エージェントの所有者の Cursor ユーザー ID (10 進数文字列) 。許可リストにはメールアドレスよりこちらを優先してください。 |
owner/user-email | 判明している場合 | 小文字化された所有者のメールアドレス。メールアドレスは変更される可能性があります。 |
owner/service-account-id | 判明している場合 | サービスアカウントがエージェントを所有している場合のサービスアカウント ID。 |
owner/team-id | 判明している場合 | 所有チームの ID (10 進数文字列) 。 |
turn/
turn/ はコーディングターンがアクティブな間だけ存在します。ターン間にはこれらのキーはありません。turn/ がない場合、アクティブなターンはありません。
turn/ 配下の値は常に現在のターンを反映します。ターンをまたいでキャッシュしないでください。
| キー | 存在するタイミング | 説明 |
|---|---|---|
turn/id | ターン中 | このコーディングターンの ID。Cloud Agent ID (bcId) である agent/id とは異なります。 |
turn/user-id | 判明している場合 | このターンを送信したユーザーの Cursor ユーザー ID。10 進数文字列です。チームのフォローアップでは、owner/user-id と異なる場合があります。 |
turn/user-email | 判明している場合 | そのユーザーのメールアドレス (小文字) 。 |
turn/started-at | ターン中 | ターンの開始時刻。Unix 秒です。 |
turn/model | 判明している場合 | このターンを処理するモデル。Auto を選択した場合、Auto ではなく実際に処理したモデルです。 |
OIDC トークンには、ターンを送信したユーザーや処理中のモデルは含まれません。トークンはターンより長く有効な場合があるためです。代わりに、これらのキーはメタデータから読み取ってください。
workspace/
| キー | 存在する場合 | 説明 |
|---|---|---|
workspace/repo-url | 判明している場合 | github.com/acme/widgets のような host/path 形式の主要リポジトリ。ホスト名は小文字で、スキーム、認証情報、ポート、クエリ、.git サフィックスは含みません。マルチリポジトリ対応エージェントの場合、これは主要リポジトリのみを指します。 |
workspace/repo-urls | リポジトリの集合が判明している場合 | ワークスペース内のすべてのリポジトリ。形式は repo-url と同じです。主要リポジトリを先頭にし、残りはソートして、URL を1行に1つずつ記載します。存在しない場合は、リポジトリが1つしかないのではなく、集合が不明であることを意味します。 |
workspace/branch-name | 判明している場合 | 主要リポジトリのブランチ。 |
workspace/environment-id | 判明している場合 | この実行で使用した Cursor 環境の ID。 |
workspace/automation-id | 自動化の場合 | agent/source が自動化の場合の自動化 ID。 |
workspace/repo-url は主要リポジトリです。すべてのリポジトリについては、workspace/repo-urls を参照してください。
メタデータを読み取れる対象
ソケットにアクセスできるプロセスは、エージェント、実行するコード、フックを含むすべてのキーを読み取れます。これらの値は、実行全体に公開されるものとして扱ってください。
メタデータには署名がありません。AWS、GCP、Vault、または独自のサービスに対してIDを証明するには、エージェントにOIDC トークンを発行させ、JWTを検証してください。メタデータ値を認証情報として転送しないでください。
レート制限とエラー
各エージェント VM は、メタデータリクエストを 1 分あたり 120 回まで実行できます (バースト時は最大 20 回) 。socket は同時に最大 8 接続を受け付けます。この上限は OIDC トークンの mint と共有されます。
429、503、500、502、504 は backoff を使用して retry してください。403 は致命的なエラーとして扱ってください。このエージェントにはメタデータの読み取りが許可されていません。
404 および 405 のレスポンスには、API の呼び出し方法をあらためて示す usage string が含まれます。レート制限および飽和エラーはコード内でのみ示されます。
{ "error": "not_found", "usage": "GET /v1/meta-data[/<path>] ..." }{ "error": "rate_limited" }| HTTP | error | 発生条件 |
|---|---|---|
| 404 | not_found | 不明なキー、またはキーがない |
| 405 | method_not_allowed | GET 以外のメソッド |
| 429 | rate_limited | エージェントごとのリクエスト予算を超過。Retry-After に従ってください |
| 503 | saturated | 接続数が多すぎます。Retry-After に従ってください |
| 500 | host_error | 内部エラー。再試行してください |
| 502 / 504 | backend_unreachable | Cursor がメタデータを返せませんでした。再試行してください |
| Other | backend_error | Cursor がリクエストを拒否しました。403 は致命的、503 は再試行可能です |
例
エージェントまたはフックでターンの送信者と所有者を比較できます。チームメイトのフォローアップには、より厳格なパスを適用できます。
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 には、1 行に 1 つの URL を指定します。
curl -fsS --unix-socket "${CURSOR_AGENT_SOCKET:-/run/cursor/api.sock}" \ http://cursor-agent/v1/meta-data/workspace/repo-urlsgithub.com/acme/widgetsgithub.com/acme/docs関連ページ
- 署名付き JWT とクラウドフェデレーションについては、OIDC トークン
- ダッシュボードのシークレットとエグレス制御については、Secrets & Network
- このソケットを読み取るインストールスクリプトについては、Cloud agent setup
- ツールと会話の境界でこの API を実行するには、Hooks
- エージェントをチームのサービスアカウントとして実行する場合は、サービスアカウント
