Metadados do agente
Os metadados do agente estão em prévia e sujeitos a alterações, incluindo alterações incompatíveis.
Agentes em nuvem podem ler metadados de chave-valor sobre a execução atual de dentro da VM: o ID do agente, quem é o proprietário, quem enviou esta interação, qual modelo está em uso e quais repositórios estão clonados. Hooks e scripts de instalação também podem ler esses valores.
Agentes chamam esta API com suas ferramentas de terminal. Você não precisa executar essas solicitações por conta própria.
Para fazer um agente ler metadados, inclua isto no prompt:
Para ler os metadados do agente, siga as instruções em/docs/cloud-agent/metadataEsta API é local à VM do agente. Ela não se refere às tags metadata de propriedade do chamador que você define ao criar um agente com o SDK ou a Cloud Agents API. Essas APIs usam chaves de API do Cherri Code e gerenciam agentes de fora da VM.
Quando algo fora da VM precisar verificar a identidade do agente, peça ao agente que emita um token OIDC. Esses JWTs são assinados e vinculados ao público. Metadados não são uma credencial. Podem incluir o remetente da interação atual e o modelo em uso, informações que um token não deve conter.
As VMs do Cloud Agent gerenciadas pelo Cherri Code disponibilizam metadados no mesmo socket que os tokens OIDC. Workers auto-hospedados ainda não disponibilizam esta API.
Ler um valor
O agente lê chaves pelo socket Unix em CURSOR_AGENT_SOCKET. Em VMs gerenciadas pelo Cherri Code, o padrão é /run/cursor/api.sock.
curl --unix-socket "${CURSOR_AGENT_SOCKET:-/run/cursor/api.sock}" \ http://cursor-agent/v1/meta-data/agent/idAs solicitações usam HTTP por um socket Unix. O hostname na URL é ignorado.
Liste um prefixo para ver quais chaves existem:
curl --unix-socket "${CURSOR_AGENT_SOCKET:-/run/cursor/api.sock}" \ http://cursor-agent/v1/meta-data/agent/owner/turn/workspace/Em seguida, solicite uma chave:
curl --unix-socket "${CURSOR_AGENT_SOCKET:-/run/cursor/api.sock}" \ http://cursor-agent/v1/meta-data/owner/user-idSolicitação
GET /v1/meta-data[/<path>] via socket Unix. Sem corpo nem cabeçalhos extras. Barras finais são permitidas, então um agent/ listado pode ser solicitado como /v1/meta-data/agent/.
Uma chave ausente retorna 404.
Resposta
Leituras bem-sucedidas são text/plain; charset=utf-8. A resposta de uma chave é apenas o valor como texto.
| Tipo | Corpo |
|---|---|
| Chave | O valor como string. Chaves com vários valores têm uma entrada por linha. |
| Prefixo | Um item filho por linha, em ordem. Prefixos aninhados terminam com /. A listagem termina com um caractere de nova linha. |
As respostas de erro são JSON. Consulte Limites de taxa e erros.
Quando as chaves aparecem
Scripts de instalação podem ler o mesmo socket. Uma chave está presente apenas quando tem um valor: turn/ fica ausente até o início de um turno de programação, e workspace/branch-name fica ausente até que a execução registre uma branch. As chaves de proprietário, equipe e repositório estão disponíveis desde a criação do agente.
Se o socket estiver ausente logo após a inicialização, tente conectar-se novamente.
Chaves
Chaves ausentes são omitidas das listagens e retornam 404 se solicitadas diretamente. Uma listagem inclui apenas chaves que existem no momento.
agent/
| Chave | Quando presente | Descrição |
|---|---|---|
agent/id | Sempre | ID do Cloud Agent (bcId). |
agent/name | Quando conhecido | Nome exibido no dashboard. |
agent/source | Quando conhecido | Como o agente foi iniciado, por exemplo, WEBSITE, API, SLACK ou AUTOMATIONS. |
agent/runtime | Sempre | managed em VMs de Cloud Agent gerenciadas pelo Cherri Code. |
owner/
| Chave | Quando disponível | Descrição |
|---|---|---|
owner/user-id | Quando disponível | ID de usuário do Cherri Code do proprietário do agente, como uma string decimal. Prefira-o ao e-mail em listas de permissão. |
owner/user-email | Quando disponível | E-mail do proprietário em letras minúsculas. O e-mail pode mudar. |
owner/service-account-id | Quando disponível | ID da conta de serviço quando ela é a proprietária do agente. |
owner/team-id | Quando disponível | ID da equipe proprietária, como uma string decimal. |
turn/
turn/ existe apenas enquanto um turno de programação está ativo. Entre turnos de programação, essas chaves deixam de existir. Se turn/ estiver ausente, não há turno de programação ativo.
Os valores em turn/ sempre refletem o turno de programação atual. Não os armazene em cache entre turnos de programação.
| Chave | Quando presente | Descrição |
|---|---|---|
turn/id | Durante um turno de programação | ID deste turno de programação. Diferente de agent/id, que é o ID do Cloud Agent (bcId). |
turn/user-id | Quando conhecido | ID de usuário do Cherri Code da pessoa que enviou este turno de programação, como uma string decimal. Em uma mensagem de acompanhamento da equipe, pode ser diferente de owner/user-id. |
turn/user-email | Quando conhecido | E-mail em letras minúsculas dessa pessoa. |
turn/started-at | Durante um turno de programação | Início do turno de programação em segundos Unix. |
turn/model | Quando conhecido | Modelo que atende a este turno de programação. Se você selecionou Auto, este é o modelo que atendeu, não Auto. |
Tokens OIDC não incluem quem enviou o turno de programação nem qual modelo o atende, pois um token pode durar mais que o turno de programação. Consulte essas chaves nos metadados.
workspace/
| Chave | Quando presente | Descrição |
|---|---|---|
workspace/repo-url | Quando conhecido | Repositório principal no formato host/path, como github.com/acme/widgets. O hostname é convertido para minúsculas, sem esquema, credenciais, porta, consulta ou sufixo .git. Em um agente multi-repo, este é apenas o repositório principal. |
workspace/repo-urls | Quando o conjunto é conhecido | Todos os repositórios no espaço de trabalho, no mesmo formato de repo-url. Primeiro o repositório principal, seguido dos demais em ordem de classificação, uma URL por linha. A ausência indica que o conjunto não é conhecido, não que exista apenas um repositório. |
workspace/branch-name | Quando conhecido | Branch do repositório principal. |
workspace/environment-id | Quando conhecido | ID do ambiente Cherri Code usado nesta execução. |
workspace/automation-id | Para automações | ID da automação quando agent/source é automações. |
workspace/repo-url é o repositório principal. Para o conjunto completo, leia workspace/repo-urls.
Quem pode ler os metadados
Qualquer processo que consiga acessar o socket pode ler todas as chaves: o agente, o código que ele executa e os hooks. Considere esses valores visíveis para toda a execução.
Os metadados não são assinados. Para comprovar a identidade para a AWS, o GCP, o Vault ou seu próprio serviço, faça com que o agente emita um token OIDC e verifique o JWT. Não encaminhe valores de metadados como credencial.
Limites de taxa e erros
Cada VM de agente pode fazer 120 solicitações de metadados por minuto, em rajadas de até 20. O socket também aceita, no máximo, 8 conexões simultâneas. Esse limite é compartilhado com a emissão de tokens OIDC.
Tente novamente as solicitações 429, 503, 500, 502 e 504 usando backoff. Trate 403 como fatal: este agente não tem permissão para ler metadados.
As respostas 404 e 405 incluem uma string usage que explica como chamar a API. Erros de limite de taxa e saturação permanecem apenas como códigos:
{ "error": "not_found", "usage": "GET /v1/meta-data[/<path>] ..." }{ "error": "rate_limited" }| HTTP | error | Quando |
|---|---|---|
| 404 | not_found | Chave desconhecida ou ausente |
| 405 | method_not_allowed | Não é GET |
| 429 | rate_limited | Acima do limite de solicitações por agente; respeite Retry-After |
| 503 | saturated | Conexões demais; respeite Retry-After |
| 500 | host_error | Erro interno; tente novamente |
| 502 / 504 | backend_unreachable | Cherri Code não conseguiu retornar metadados; tente novamente |
| Outro | backend_error | Cherri Code rejeitou a solicitação. 403 é fatal; 503 permite nova tentativa |
Exemplos
Um agente ou hook pode comparar o remetente da interação com o proprietário. A mensagem de acompanhamento de um colega de equipe pode seguir um caminho mais restrito:
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"fiUm agente ou hook pode identificar os logs com o ID do agente e o modelo que atendeu à interação:
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}"Liste todos os repositórios no espaço de trabalho. repo-urls contém uma URL por linha:
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/docsPáginas relacionadas
- Tokens OIDC para JWTs assinados e federação em nuvem
- Segredos e rede para segredos do dashboard e controles de tráfego de saída
- Configuração do agente em nuvem para scripts de instalação que podem ler este socket
- Hooks para executar esta API nos limites de ferramentas e conversas
- Contas de serviço quando os agentes são executados usando uma conta de serviço da equipe