метаданные Agent
Метаданные Agent находятся в предварительной версии и могут измениться, включая несовместимые изменения.
Cloud Agents могут получать из ВМ метаданные текущего запуска в формате «клавиша — значение»: ID Agent, его владельца, отправителя текущего шага, обслуживающую модель и извлечённые репозитории. Хуки и скрипты установки также могут читать эти значения.
Agents вызывают этот API с помощью инструментов терминала. Вам не нужно самостоятельно выполнять эти запросы.
Чтобы Agent прочитал метаданные, добавьте в свой промпт следующее:
To read agent metadata, follow the instructions athttps://cursor.com/docs/cloud-agent/metadataЭтот API доступен только локально в ВМ Agent. Это не теги metadata, принадлежащие вызывающей стороне, которые вы задаёте при создании Agent с помощью SDK или API облачных Agents. Эти API используют API-клавиши Cursor и управляют Agents извне ВМ.
Если кому-то за пределами ВМ нужно проверить личность Agent, поручите Agent вместо этого выпустить токен OIDC. Эти JWT подписаны и привязаны к аудитории. Метаданные не являются учётными данными. Они могут содержать информацию об отправителе текущего шага и обслуживающей модели — данные, которые токен содержать не должен.
ВМ Cloud Agent, управляемые Cursor, предоставляют метаданные через тот же сокет, что и токены OIDC. Self-hosted воркеры пока не предоставляют этот API.
Чтение значения
Agent читает клавиши через Unix-сокет по адресу CURSOR_AGENT_SOCKET. На управляемых Cursor ВМ по умолчанию используется /run/cursor/api.sock.
curl --unix-socket "${CURSOR_AGENT_SOCKET:-/run/cursor/api.sock}" \ http://cursor-agent/v1/meta-data/agent/idЗапросы передаются по HTTP через Unix-сокет. Имя хоста в 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Запрос
GET /v1/meta-data[/<path>] через Unix-сокет. Тело запроса и дополнительные заголовки не требуются. Завершающие слеши допустимы, поэтому указанный agent/ можно запросить как /v1/meta-data/agent/.
Отсутствующая клавиша возвращает 404.
Ответ
Успешные запросы чтения имеют формат text/plain; charset=utf-8. Ответ для клавиши содержит только значение в текстовом виде.
| Тип | Тело |
|---|---|
| Клавиша | Значение в виде строки. Для клавиш с несколькими значениями каждая запись выводится в отдельной строке. |
| Префикс | По одному дочернему элементу в строке, в отсортированном порядке. Вложенные префиксы оканчиваются на /. Список завершается переводом строки. |
Ответы об ошибках имеют формат JSON. См. Ограничения скорости и ошибки.
Когда появляются ключи
Скрипты установки могут читать тот же сокет. Ключ присутствует, только если у него есть значение: turn/ отсутствует до начала шага кодирования, а workspace/branch-name — до тех пор, пока запуск не зафиксирует ветку. Ключи владельца, команды и репозитория доступны с момента создания Agent.
Если сокет отсутствует сразу после запуска, повторите попытку подключения.
Клавиши
Отсутствующие клавиши не отображаются в списках, а при прямом запросе возвращается 404. Список включает только клавиши, существующие на данный момент.
agent/
| Клавиша | Когда доступен | Описание |
|---|---|---|
agent/id | Всегда | Идентификатор Cloud Agent (bcId). |
agent/name | Если известно | Имя, отображаемое на дашборде. |
agent/source | Если известно | Способ запуска агента, например WEBSITE, API, SLACK или AUTOMATIONS. |
agent/runtime | Всегда | managed на ВМ Cloud Agent, управляемых Cursor. |
owner/
| Клавиша | Когда доступен | Описание |
|---|---|---|
owner/user-id | Когда известен | Идентификатор пользователя Cursor, которому принадлежит Agent, в виде десятичной строки. Для allowlist предпочитайте его email. |
owner/user-email | Когда известен | Email владельца в нижнем регистре. Email может измениться. |
owner/service-account-id | Когда известен | Идентификатор сервисного аккаунта, если Agent принадлежит сервисному аккаунту. |
owner/team-id | Когда известен | Идентификатор команды-владельца в виде десятичной строки. |
turn/
turn/ существует только во время активного шага кодирования. Между шагами эти клавиши отсутствуют. Если turn/ отсутствует, активного шага нет.
Значения в turn/ всегда относятся к текущему шагу. Не кешируйте их между шагами.
| Клавиша | Когда доступен | Описание |
|---|---|---|
turn/id | Во время шага | ID этого шага кодирования. Он отличается от agent/id, который является идентификатором Cloud Agent (bcId). |
turn/user-id | Когда известен | ID пользователя Cursor, отправившего этот шаг, в виде десятичной строки. В последующем шаге команды он может отличаться от owner/user-id. |
turn/user-email | Когда известен | Email этого пользователя в нижнем регистре. |
turn/started-at | Во время шага | Время начала шага в секундах Unix. |
turn/model | Когда известна | Модель, обслуживающая этот шаг. Если вы выбрали Auto, здесь указана обслуживавшая модель, а не Auto. |
Токены OIDC не содержат сведений о том, кто отправил шаг и какая модель его обслуживает, поскольку токен может существовать дольше шага. Вместо этого читайте эти клавиши из метаданных.
workspace/
| Клавиша | Когда присутствует | Описание |
|---|---|---|
workspace/repo-url | Когда известно | Основной репозиторий в формате host/path, например github.com/acme/widgets. Имя хоста приводится к нижнему регистру; схема, учетные данные, порт, query и суффикс .git отсутствуют. Для мульти-репозиторного Agent указывается только основной репозиторий. |
workspace/repo-urls | Когда набор известен | Все репозитории в рабочем пространстве в том же формате, что и repo-url. Сначала основной репозиторий, затем остальные в отсортированном порядке — по одному URL в строке. Отсутствие означает, что набор неизвестен, а не то, что репозиторий только один. |
workspace/branch-name | Когда известно | Ветка основного репозитория. |
workspace/environment-id | Когда известно | ID инфраструктуры Cursor, использованной в этом запуске. |
workspace/automation-id | Для автоматизаций | ID автоматизации, если agent/source имеет значение automations. |
workspace/repo-url — основной репозиторий. Полный набор указан в workspace/repo-urls.
Кто может читать метаданные
Любой процесс, имеющий доступ к сокету, может прочитать все ключи: Agent, выполняемый им код и хуки. Считайте эти значения доступными всем в рамках запуска.
Метаданные не подписаны. Чтобы подтвердить свою личность перед AWS, GCP, Vault или собственным сервисом, поручите Agent выпустить токен OIDC и проверьте JWT. Не передавайте значения метаданных в качестве учётных данных.
Ограничения частоты запросов и ошибки
Каждая ВМ агента может выполнять 120 запросов метаданных в минуту, с кратковременными всплесками до 20 запросов. Сокет также принимает не более 8 одновременных подключений. Это ограничение общее с выпуском OIDC-токенов.
Повторяйте запросы 429, 503, 500, 502 и 504 с увеличивающейся задержкой. Считайте 403 критической ошибкой: этот агент не имеет права читать метаданные.
Ответы 404 и 405 содержат строку usage, повторяющую способ вы��ова API. Ошибки ограничения частоты и перегрузки содержат только код:
{ "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 не смог вернуть метаданные; повторите попытку |
| Другое | backend_error | Cursor отклонил запрос. 403 — фатальная ошибка; 503 — можно повторить попытку |
Примеры
Agent или хук может сравнить отправителя шага с владельцем. Уточняющий запрос от участника команды может проходить более строгую проверку:
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"fiAgent или хук может добавлять к логам идентификатор Agent и модель, обработавшую шаг:
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-urlsgithub.com/acme/widgetsgithub.com/acme/docsСвязанные страницы
- Токены OIDC для подписанных JWT и федерации с облаком
- Secrets & Network для секретов дашборда и контроля исходящего трафика
- Настройка облачного агента для скриптов установки, которые могут обращаться к этому сокету
- Хуки для запуска этого API на границах работы инструментов и диалогов
- Сервисные аккаунты, если агенты запускаются от имени сервисного аккаунта команды