Skip to main content

Register and reconcile a manifest

Goal: submit an agent manifest and resolve a reconciliation diff if the control plane flags one.

Register a new agent​

curl -sS -X POST localhost:8000/v1/agents \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "manifest": {...}}'
  • 201 + status: "reconciled" — done, the manifest matched what the declared tools actually advertise.
  • 422 + status: "rejected" — a hard conflict (see below). The submission is still recorded (append-only), just not usable.
  • 409 + status: "needs_review" — a declared tool's discovery endpoint was unreachable, and no override was supplied.

Read the reconciliation diff​

curl -sS localhost:8000/v1/agents/$AGENT_ID/reconciliation \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Each diff entry names the offending tool ref and one of:

Diff codeMeaningFix
UNKNOWN_TOOLThe manifest declares a tool ref discovery never advertisedRemove the ref, or confirm the tool's own /.well-known/oauth-protected-resource is correct
DECLARED_EXCEEDS_DISCOVEREDThe manifest claims a data class the tool doesn't exposeNarrow data_classes on that tool ref to what's actually advertised
DATA_CLASS_CONFLICTA privileged: true tool conflicts with its declared data classesReconcile the privileged flag with the tool's real classification
DISCOVERY_UNAVAILABLEThe tool's discovery endpoint didn't respondRetry, or resubmit with override: {reason: "..."} to accept needs_review

Re-submit after fixing the manifest​

Resubmitting is how you fix any of the above — manifests are append-only and versioned, so a correction is a new version, not an edit:

curl -sS -X POST localhost:8000/v1/manifests \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d @my-agent-manifest-v2.json

Preview a diff before registering (offline)​

The CLI reuses the same discovery client and reconciler the server runs, so its output matches what registration will do:

agentic-auth manifest validate my-agent.yaml   # schema only, no network
agentic-auth manifest lint my-agent.yaml       # style/consistency warnings
agentic-auth manifest diff my-agent.yaml       # preview-reconcile against live discovery

Why a rejected manifest is still committed​

A rejected or needs_review outcome is persisted, not rolled back — only a delegation-cycle error rolls back the whole submission, because a cyclic manifest set must leave no trace at all. Every other outcome is kept as history so "what did we try to declare, and why was it refused" never depends on someone having saved the response. See Reconciler for the full sequence.