API de agentes

Registro de agentes y límite de autenticación

POST /v1/agents/temporary-register crea un agente temporal no reclamado y un espacio de memoria temporal aislado, como máximo una vez por IP de cliente por día UTC. La ruta antigua /v1/agents/register devuelve 410. La creación formal de agentes utiliza endpoints autenticados del plano de control. La identidad y los metadados de instalación del agente no son credenciales y no amplían la autorización de memoria.

• Registro temporal: POST /v1/agents/temporary-register (anónimo permitido; las credenciales presentadas no válidas se rechazan).
• Flujo de agente temporal: GET /v1/agents/status; GET /v1/agents/bind/status; POST /v1/agents/bind/confirm-current-user; POST /v1/agents/bind/deny-current-user.
• Flujo de agente formal: POST /v1/agents/rotate.

Esquema de solicitud de registro

POST /v1/agents/temporary-register acepta AgentSelfRegistrationRequest. Los campos obligatorios son entry_type, client_name, installation_fingerprint (1..512 caracteres) y requested_scopes (un subconjunto no vacío de read:temporary_memory y write:temporary_memory). Otros ámbitos son rechazados. Los metadados opcionales de proyecto e instalación no pueden otorgar permisos.

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 respuesta de registro

Un registro correcto devuelve AgentSelfRegistrationResponse con agent_id (string), claim_code (string), bind_url (string), status (string), connection_method (string) y trust_level (integer) obligatorios. temporary_token es un string o null opcional. Guarda un token temporal solo en el almacén de credenciales del cliente; no es un valor de identidad del agente.

{
  "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 estado, bind y rotación

OpenAPI declara una respuesta de objeto JSON sin tipo y ningún cuerpo de solicitud para GET /v1/agents/status, GET /v1/agents/bind/status, POST /v1/agents/bind/deny-current-user y POST /v1/agents/rotate. POST /v1/agents/bind/confirm-current-user también carece de tipo de cuerpo en OpenAPI; la implementación actual de la ruta lee confirmation_token desde un objeto JSON o un parámetro de consulta. Las respuestas de estado y bind del agente temporal son objetos de runtime cuyas propiedades no están declaradas en la especificación versionada. La rotación está restringida por la ruta a un token formal asociado a un agente.

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>

Atribución del agente en llamadas de memoria

El campo source registra qué agente produjo una memoria y se almacena como provenance; no afecta a la autorización. En llamadas MCP por HTTP streaming, los headers de identidad describen el cliente y la instalación local estable. La API REST usa la key autenticada junto con campos source/provenance opcionales; mantén las credenciales separadas de estos valores.

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"
}

Errores, paginación y límites de velocidad

El registro temporal devuelve 422 para solicitudes de ámbito no válidas, 401 para credenciales presentadas no válidas, 410 en la ruta de registro retirada y 429 cuando se agota la cuota de una IP por día UTC. También se aplican límites de solicitud en ventanas cortas. Las operaciones de estado y vinculación requieren sus propias comprobaciones de credenciales.

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