# Agents API

credentialはauthenticated request headerに保持し、secretではない安定したagent identity metadataを使います。

- Canonical: https://docs.xmemo.dev/ja/docs/api/agents
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: 5b588b532d65a893c7f7df2da740d550ecb57a24c6da41b80aeae86d66ef715a
- Edition-Digest: 51a0504f7766d229afa1c4493994ada8b721a052d0e857bdcfa49c20845587a4
- Source-Revision: sha256:4252897f178cee111afad2225e66b09df98104bfd6637c828a3b0287c28958ae

## Agent registrationとauthentication boundary

POST /v1/agents/temporary-register は、クライアントIPごとにUTC日あたり最大1回、未クレームの temporary Agent と隔離された Temporary Memory Space を作成します。以前の /v1/agents/register パスは 410 を返します。正式な Agent 作成には、認証された control plane エンドポイントを使用します。Agent identity と installation metadata は credential ではなく、memory authorization を拡張しません。

- Temporary registration: POST /v1/agents/temporary-register（匿名アクセス可能。提示された無効な credentials は拒否）。
- 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が成功すると、requiredなagent_id（string）、claim_code（string）、bind_url（string）、status（string）、connection_method（string）、trust_level（integer）を持つAgentSelfRegistrationResponseが返ります。temporary_tokenはoptionalな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、rotationのschema

OpenAPIはGET /v1/agents/status、GET /v1/agents/bind/status、POST /v1/agents/bind/deny-current-user、POST /v1/agents/rotateについて、untyped JSON object responseとrequest bodyなしを宣言します。POST /v1/agents/bind/confirm-current-userもOpenAPIではbody-untypedで、現在のroute implementationはJSON objectまたはquery parameterからconfirmation_tokenを読み取ります。Temporary-agent statusとbind responseはruntime objectで、そのpropertyは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>
```

## Memory callでのagent attribution

source fieldはどのagentがmemoryを生成したかを記録し、provenanceとして保存されますが、authorizationには影響しません。Streamable HTTP MCP callではidentity headerがclientと安定したlocal installを示します。REST APIはauthenticated keyと任意のsource/provenance fieldを使うため、credentialはこれらの値と分けて管理してください。

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

## Error、pagination、rate limit

Temporary registration は、無効な scope 要求に対して 422、提示された無効な credentials に対して 401、廃止された registration パスに対して 410、および 1 IP あたり 1 UTC 日のクォータを使い果たしたときに 429 を返します。短いウィンドウのリクエスト制限も適用されます。Status および bind 操作には、独自の credential チェックが必要です。

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