Cursor Agent metadata: как пользоваться - Artem Denisov | Gen AI, vibecode, no-code automation & Design

Cursor Agent metadata — это preview API внутри Cursor-managed Cloud Agent VM: агент, hooks и install-скрипты читают key-value о текущем run (agent id, owner, кто отправил turn, какая model служит, какие repos checkout). Канон: Agent metadata. Preview: breaking changes возможны.

Обзор продукта — Cloud Agents; identity наружу — OIDC tokens; API снаружи VM — Cloud Agents API. Pillar: n8n / автоматизация.

Чем это не является

Это не caller-owned metadata tags из SDK / Cloud Agents API (те управляются API key снаружи VM). Это не credential: не пересылайте значения metadata как доказательство identity. Для AWS/GCP/Vault минтите OIDC. Self-hosted workers этот API пока не отдают.

Префикс	Когда есть	Примеры ключей
agent/	с создания агента	id (bcId), name, source (WEBSITE/API/SLACK/AUTOMATIONS), runtime=managed
owner/	когда известен	user-id, user-email, service-account-id, team-id
turn/	только во время coding turn	id, user-id, user-email, started-at, model
workspace/	когда известен	repo-url, repo-urls, branch-name, environment-id, automation-id

Сверка: cursor.com/docs/cloud-agent/metadata (проверка 2026-09-20). Preview API.

Как читать значение

HTTP GET по Unix socket. Hostname в URL игнорируется. Default socket: /run/cursor/api.sock (CURSOR_AGENT_SOCKET).

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

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

Успех — text/plain. Listing префикса — по одному child на строку. Missing key → 404. Чтобы агент сам читал metadata, в prompt достаточно отослать на docs URL выше.

Практика: follow-up ≠ owner

На team follow-up turn/user-id может отличаться от owner/user-id. Hook может сравнить их и ужесточить путь. Не кэшируйте turn/* между turns — префикс пропадает, когда turn не активен. Для allowlists docs советует owner/user-id, а не email (email может смениться).

Лимиты и ошибки

120 metadata-запросов/мин на VM, burst до 20.
Максимум 8 одновременных соединений на socket (shared с OIDC mint).
Retry: 429, 503, 500, 502, 504 (честь Retry-After где есть).
403 — fatal: этому агенту metadata читать нельзя.

Маршрут на один вечер

Запустите managed Cloud Agent (не self-hosted worker).
В prompt попросите прочитать agent/id и workspace/repo-url по docs.
Добавьте hook/install-скрипт: сравнить owner vs turn submitter.
Для cloud roles наружу — отдельно настройте OIDC, не metadata.
Зафиксируйте лимиты 120/мин в мониторинге hooks.

Типичные ошибки

Путать VM metadata с metadata tags create-agent API.
Форвардить metadata как credential вместо OIDC JWT.
Ждать API на Self-Hosted workers — его ещё нет.
Кэшировать turn/model между turns.
Считать preview стабильным контрактом без retry/backoff.

FAQ: Cursor Agent metadata

Что такое Cursor Agent metadata?

Agent metadata — preview API внутри Cursor-managed Cloud Agent VM: агент, hooks и install-скрипты читают key-value про текущий run (id агента, owner, submitter turn, model, repos) через Unix socket. Канон: cursor.com/docs/cloud-agent/metadata.

Чем metadata отличается от OIDC tokens?

Metadata не credential и не подписана. Для доказательства identity наружу агент минтит OIDC JWT (signed, audience-bound). В metadata есть submitter turn и serving model, которых в токене нет, потому что JWT может пережить turn.

Где лежит socket и как читать ключ?

Переменная CURSOR_AGENT_SOCKET, на managed VM default /run/cursor/api.sock. GET /v1/meta-data/ через curl —unix-socket. Успешный ответ — text/plain. Missing key → 404.

Какие префиксы ключей есть?

Четыре: agent/ (id, name, source, runtime), owner/ (user-id, email, service-account-id, team-id), turn/ (только во время coding turn), workspace/ (repo-url, repo-urls, branch-name, environment-id, automation-id).

Работает ли metadata на Self-Hosted workers?

Нет. Docs: Self-hosted workers do not serve this API yet. Socket общий с OIDC minting на Cursor-managed VM.

Какие лимиты у metadata API?

До 120 запросов в минуту на VM, burst до 20, максимум 8 одновременных соединений (shared с OIDC). Retry 429/503/500/502/504; 403 — fatal.

Вывод

Agent metadata — локальный preview-снимок run внутри managed VM: удобно для hooks, логов и сравнения owner/follow-up. Для identity наружу — OIDC. Соседние ноды: Secrets, Settings, Private Connectivity.

Артём Денисов — эксперт Нетологии и автор курса Яндекс Практикума по промпт-инжинирингу. Сверяет Agent metadata с cursor.com/docs/cloud-agent/metadata.

Хотите нейросети под свои задачи, а не «для всех»?

Когда базовых гайдов уже мало, помогает разбор под вашу работу. Наставничество, курсы и подписка Артём Денисов — все форматы на странице обучения. Тех-pillar — n8n для начинающих.