# Agent API

使用稳定且不含 secret 的 agent identity metadata，同时让 credential 保留在 authenticated request headers 中。

- Canonical: https://docs.xmemo.dev/zh/docs/api/agents
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 5b588b532d65a893c7f7df2da740d550ecb57a24c6da41b80aeae86d66ef715a
- Edition-Digest: 004f304a5be3eed965ac564ee831f083325912c7a7e040df581946fdb61f446d
- Source-Revision: sha256:4252897f178cee111afad2225e66b09df98104bfd6637c828a3b0287c28958ae

## Agent registration and authentication boundary

POST /v1/agents/temporary-register 用于创建未领取的 temporary Agent 以及隔离的 Temporary Memory Space，每个客户端 IP 每个 UTC 日最多调用一次。旧的 /v1/agents/register 路径返回 410。正式 Agent 创建使用经过认证的 control plane endpoints。Agent identity 和 installation metadata 不是 credentials，也不会扩大 memory authorization。

- Temporary registration：POST /v1/agents/temporary-register（允许匿名；提交的无效凭据将被拒绝）。
- Temporary-agent flow：GET /v1/agents/status；GET /v1/agents/bind/status；POST /v1/agents/bind/confirm-current-user；POST /v1/agents/bind/deny-current-user。
- Formal-agent flow：POST /v1/agents/rotate。

## Registration request schema

POST /v1/agents/temporary-register 接受 AgentSelfRegistrationRequest。必填字段为 entry_type、client_name、installation_fingerprint（1..512 个字符）以及 requested_scopes（read:temporary_memory 和 write:temporary_memory 的非空子集）。其他 scope 均会被拒绝。可选的 project 和 installation metadata 不能用于授予权限。

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

## Registration response schema

成功的 registration 返回 AgentSelfRegistrationResponse，其中 required fields 是 agent_id（string）、claim_code（string）、bind_url（string）、status（string）、connection_method（string）和 trust_level（integer）。temporary_token 是可选的 string 或 null。只将 temporary token 保存在 client credential store 中；它不是 agent identity value。

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

## Status, bind, and rotation schemas

OpenAPI 声明 GET /v1/agents/status、GET /v1/agents/bind/status、POST /v1/agents/bind/deny-current-user 和 POST /v1/agents/rotate 返回 untyped JSON object，且没有 request body。POST /v1/agents/bind/confirm-current-user 在 OpenAPI 中同样 body-untyped；当前 route implementation 从 JSON object 或 query parameter 读取 confirmation_token。Temporary-agent status 和 bind responses 是 runtime objects，其 properties 未在 committed spec 中声明。Rotation 由 route 限制为与 agent 关联的 formal token。

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

## Agent attribution on memory calls

source field 记录产生 memory 的 agent，并作为 provenance 保存；它不影响 authorization。对于 streamable HTTP MCP calls，identity headers 描述 client 和稳定的本地 install。REST API 使用 authenticated key，以及可选的 source/provenance fields；请将 credentials 与这些 values 分开。

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

## Errors, pagination, and rate limits

Temporary registration 在 scope 请求无效时返回 422，提交无效凭据时返回 401，访问已废弃的 registration 路径时返回 410，单 IP 每日（UTC）配额用尽时返回 429。短时间窗口的请求限制同样适用。Status 和 bind 操作需要独立的凭据校验。

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