API Agents

Enregistrement d'agent et limite d'authentification

POST /v1/agents/temporary-register crée un agent temporaire non réclamé et un espace de mémoire temporaire isolé, au maximum une fois par IP cliente par jour UTC. L'ancien chemin /v1/agents/register renvoie 410. La création formelle d'agent utilise des points de terminaison authentifiés du plan de contrôle. L'identité et les métadonnées d'installation de l'agent ne sont pas des identifiants et n'élargissent pas l'autorisation d'accès à la mémoire.

• Enregistrement temporaire : POST /v1/agents/temporary-register (anonyme autorisé ; les identifiants présentés non valides sont rejetés).
• Flux d'agent temporaire : GET /v1/agents/status ; GET /v1/agents/bind/status ; POST /v1/agents/bind/confirm-current-user ; POST /v1/agents/bind/deny-current-user.
• Flux d'agent formel : POST /v1/agents/rotate.

Schéma de requête d'enregistrement

POST /v1/agents/temporary-register accepte AgentSelfRegistrationRequest. Les champs requis sont entry_type, client_name, installation_fingerprint (1..512 caractères) et requested_scopes (un sous-ensemble non vide de read:temporary_memory et write:temporary_memory). Les autres portées sont rejetées. Les métadonnées facultatives de projet et d'installation ne peuvent pas accorder de permissions.

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

Schéma de réponse d'enregistrement

Un enregistrement réussi renvoie AgentSelfRegistrationResponse avec les champs requis agent_id (chaîne), claim_code (chaîne), bind_url (chaîne), status (chaîne), connection_method (chaîne) et trust_level (entier). temporary_token est une chaîne facultative ou null. Stockez un jeton temporaire uniquement dans le magasin d'identifiants du client ; ce n'est pas une valeur d'identité d'agent.

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

Schémas de statut, d'association et de rotation

OpenAPI déclare une réponse d'objet JSON non typé et aucun corps de requête pour GET /v1/agents/status, GET /v1/agents/bind/status, POST /v1/agents/bind/deny-current-user et POST /v1/agents/rotate. POST /v1/agents/bind/confirm-current-user est également sans type de corps dans OpenAPI ; l'implémentation actuelle de la route lit confirmation_token à partir d'un objet JSON ou d'un paramètre de requête. Les réponses de statut et d'association d'agent temporaire sont des objets d'exécution dont les propriétés ne sont pas déclarées dans la spécification validée. La rotation est restreinte par la route à un jeton formel associé à un agent.

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>

Attribution de l'agent sur les appels de mémoire

Le champ source enregistre quel agent a produit une mémoire et est stocké comme provenance ; il n'affecte pas l'autorisation. Pour les appels MCP HTTP diffusables en continu, les en-têtes d'identité décrivent le client et l'installation locale stable. L'API REST utilise la clé authentifiée ainsi que des champs source/provenance facultatifs ; gardez les identifiants séparés de ces valeurs.

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

Erreurs, pagination et limites de débit

L'enregistrement temporaire renvoie 422 pour les demandes de portée non valides, 401 pour les identifiants présentés non valides, 410 sur le chemin d'enregistrement retiré et 429 lorsque le quota d'une IP par jour UTC est épuisé. Des limites de requêtes sur fenêtres courtes s'appliquent également. Les opérations de statut et d'association nécessitent leurs propres vérifications d'identifiants.

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