# API de agentes

Usa metadatos estables de identidad del agente sin secretos, mientras las credenciales permanecen en headers de solicitudes autenticadas.

- Canonical: https://docs.xmemo.dev/es/docs/api/agents
- Locale: es-ES
- Content-Locale: es-ES
- Canonical-Content-Digest: 5b588b532d65a893c7f7df2da740d550ecb57a24c6da41b80aeae86d66ef715a
- Edition-Digest: 211d5168513303ec43e3f0816b334dc39942f2114469cfb389d5f8f6ac0ca5be
- Source-Revision: sha256:4252897f178cee111afad2225e66b09df98104bfd6637c828a3b0287c28958ae

## 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.

```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 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.

```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 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.

```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>
```

## 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.

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

## 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.

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