Register an agent

Registering an agent is what lets policy reason about it by name. See Agents for the model.

Requires agent registration permission

You need permission to submit agents in the target environment; approval is a separate, reviewer step.

1. Validate the agent manifest (owner, scope, surfaces, environments).
2. Submit it to create a pending agent.
3. Approve it (reviewer) — then it can operate per policy.

Validate the agent

Validate an agent manifest

UIAPICLI

1. Open Govern → Agents → Register.
2. Provide the agent's owner, scope, surfaces, and environments, then Validate.

POST/v1/registry/validate-manifest

Copy

curl -X POST "$GATEWAY/v1/registry/validate-manifest" \
-H "authorization: Bearer $TOKEN" \
-H "content-type: application/json" \
--data @agent.json

View validateRegistryManifest in the API reference →

Copy

gatewayctl validate-agent agent.yaml

Every gatewayctl verb accepts --format text|json.

Submit the agent

Submit the agent for approval

UIAPICLI

1. After a clean validation, click Register.
2. The agent appears in Govern → Agents awaiting approval.

POST/v1/agents

Copy

curl -X POST "$GATEWAY/v1/agents" \
-H "authorization: Bearer $TOKEN" \
-H "content-type: application/json" \
--data @agent.json

View createAgent in the API reference →

Copy

gatewayctl register-agent agent.yaml --format json

Every gatewayctl verb accepts --format text|json.

Approve and revoke

After approval (POST /v1/agents/{id}/approval), the agent operates per policy. To cut it off immediately, revoke it (POST /v1/agents/{id}/revoke) or use emergency‑disable — both take effect on the next request.