# API de agentes

Use metadados estáveis e sem segredos para a identidade do agente, mantendo as credenciais nos cabeçalhos de solicitações autenticadas.

- Canonical: https://docs.xmemo.dev/pt-br/docs/api/agents
- Locale: pt-BR
- Content-Locale: pt-BR
- Canonical-Content-Digest: 5b588b532d65a893c7f7df2da740d550ecb57a24c6da41b80aeae86d66ef715a
- Edition-Digest: 34097444ec49a7f1c3cd431d087362c04fdca4169568bbd3bbbd02dde35bf86c
- Source-Revision: sha256:4252897f178cee111afad2225e66b09df98104bfd6637c828a3b0287c28958ae

## Limite entre registro e autenticação do agente

POST /v1/agents/temporary-register cria um Agent temporário não reivindicado e um Temporary Memory Space isolado, no máximo uma vez por IP de cliente por dia UTC. O caminho antigo /v1/agents/register retorna 410. A criação formal de Agent utiliza endpoints autenticados do plano de controle. A identidade e os metadados de instalação do agente não são credenciais e não ampliam a autorização de memória.

- Registro temporário: POST /v1/agents/temporary-register (anônimo permitido; credenciais apresentadas inválidas são rejeitadas).
- Fluxo de agente temporário: GET /v1/agents/status; GET /v1/agents/bind/status; POST /v1/agents/bind/confirm-current-user; POST /v1/agents/bind/deny-current-user.
- Fluxo de agente formal: POST /v1/agents/rotate.

## Esquema de solicitação de registro

POST /v1/agents/temporary-register aceita AgentSelfRegistrationRequest. Os campos obrigatórios são entry_type, client_name, installation_fingerprint (1..512 caracteres) e requested_scopes (um subconjunto não vazio de read:temporary_memory e write:temporary_memory). Outros escopos são rejeitados. Metadados opcionais de projeto e instalação não podem conceder permissões.

```http
POST /v1/agents/temporary-register
Content-Type: application/json

{
  "entry_type": "mcp",
  "client_name": "codex",
  "installation_fingerprint": "<stable-installation-fingerprint>",
  "requested_scopes": ["read:temporary_memory"],
  "client_version": "<client-version>",
  "runtime": "windows"
}
```

## Esquema de resposta do registro

Um registro bem-sucedido retorna AgentSelfRegistrationResponse com agent_id (string), claim_code (string), bind_url (string), status (string), connection_method (string) e trust_level (integer) obrigatórios. temporary_token é uma string opcional ou null. Armazene um token temporário somente no armazenamento de credenciais do cliente; ele não é um valor de identidade do agente.

```json
{
  "agent_id": "<agent-id>",
  "temporary_token": "<temporary-token-or-null>",
  "claim_code": "<claim-code>",
  "bind_url": "https://xmemo.dev/agents/bind?code=<claim-code>",
  "status": "pending",
  "connection_method": "streamable_http",
  "trust_level": 0
}
```

## Esquemas de status, vínculo e rotação

O OpenAPI declara uma resposta de objeto JSON sem tipo e nenhum corpo de solicitação para GET /v1/agents/status, GET /v1/agents/bind/status, POST /v1/agents/bind/deny-current-user e POST /v1/agents/rotate. POST /v1/agents/bind/confirm-current-user também não tem tipo de corpo no OpenAPI; a implementação atual da rota lê confirmation_token de um objeto JSON ou de um parâmetro de consulta. As respostas de status e vínculo do agente temporário são objetos do runtime cujas propriedades não estão declaradas na especificação versionada. A rotação é restrita pela rota a um token formal associado a um agente.

```http
GET /v1/agents/status
X-API-Key: <temporary-agent-token>

POST /v1/agents/bind/confirm-current-user?confirmation_token=<confirmation-token>
X-API-Key: <temporary-agent-token>

POST /v1/agents/rotate
X-API-Key: <formal-agent-token>
```

## Atribuição do agente nas chamadas de memória

O campo source registra qual agente produziu uma memória e é armazenado como provenance; ele não afeta a autorização. Em chamadas MCP por HTTP streamable, os cabeçalhos de identidade descrevem o cliente e a instalação local estável. A API REST usa a chave autenticada, além de campos source/provenance opcionais; mantenha as credenciais separadas desses valores.

```http
POST /v1/memories
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "content": "Fixed streamable-http token identity fallback.",
  "path": "projects/memory-os/fixes",
  "source": "codex"
}
```

## Erros, paginação e limites

O registro temporário retorna 422 para solicitações de escopo inválidas, 401 para credenciais apresentadas inválidas, 410 no caminho de registro descontinuado e 429 quando a cota de um IP por dia UTC é esgotada. Limites de requisição de janela curta também se aplicam. As operações de status e vinculação exigem suas próprias verificações de credenciais.

```json
{
  "detail": [
    {
      "loc": ["body", "installation_fingerprint"],
      "msg": "<validation-message>",
      "type": "<validation-error-type>"
    }
  ]
}
```