Guides
Levels and approvals
An agent acts on its own only up to its level. Above it, the exact action waits for a person, who can approve it, edit it or reject it.
Risk classes
Every tool in the catalogue declares what kind of action it is, which sets its class.
- R0
- Read, search, report.
- R1
- Draft, note.
- R2
- Reversible changes in your own systems.
- R3
- Reach known people, publish, change settings or credentials.
- R4
- Strangers, bulk, money, deletion, legal commitments. Always waits.
- L0
- observe
- up to R0
- L1
- prepare
- up to R1
- L2
- act inside
- up to R2
- L3
- act outward
- up to R3
- L4
- operate (as L3 for now)
- up to R3
How a call is decided
- The agent asks to call a tool. The agent only asks; tools run in the control plane.
- The control plane reads the agent fresh, so a level lowered a moment ago applies now.
- If the tool is in the agent's
require_approval, or is R4, or is above the level's ceiling, it waits as an approval. Otherwise it runs at once. - A person approves (the action runs once, as it stands), edits then approves (the edited action runs), or rejects (nothing runs, and the agent is told).
Every agent starts at L0. Setting any other level needs agents:autonomy, which owners and admins hold.
/v1/toolsList the tool catalogue
Every tool an agent can be given, with its risk class, and the autonomy levels with the highest class each may take without asking. Tools run in Rykon AI’s control plane, never in the sandbox. R4 always waits for a person, whatever the level.
curl https://api.rykon.ai/v1/tools \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"tools": [
{
"name": "record_finding",
"description": "Record one finding in the run record.",
"category": "report",
"risk": "R0",
"kind": "database",
"params": {
"finding": {
"type": "string",
"description": "The finding",
"maxLength": 2000
}
}
},
{
"name": "list_findings",
"description": "List the findings this run has recorded so far.",
"category": "read",
"risk": "R0",
"kind": "database",
"params": {}
}
],
"riskClasses": [
"R0",
"R1",
"R2",
"R3",
"R4"
],
"autonomyLevels": {
"L0": {
"description": "observe: reads and reports only, everything else waits for a person",
"ceiling": "R0"
},
"L1": {
"description": "prepare: may also draft",
"ceiling": "R1"
},
"L2": {
"description": "act inside: may also make reversible changes in the customer's own systems",
"ceiling": "R2"
},
"L3": {
"description": "act outward: may also reach known people and publish",
"ceiling": "R3"
},
"L4": {
"description": "operate: as L3 in v1 (R4 always waits, D11)",
"ceiling": "R3"
}
},
"defaultLevel": "L0",
"alwaysApproval": [
"R4"
]
}In the reference: List the tool catalogue
Why a person decides
An approval exists so that someone accountable looks at an action before it happens. An agent, or a script, approving its own work defeats that, so the routes that edit, approve and reject accept only a person signed in to the console. An API key is refused 403 forbidden whatever its scopes, and the refusal is in the audit log.
From your code you can read everything about approvals: list what is waiting, show it in your own tools, and link people to the console to decide.
Answering from an MCP client
/v1/approvalsList approvals
Actions that waited, or are waiting, for a person. proposed_input is what the agent asked for and never changes; action_input is what will run, which a person may edit. An approval expires at the earlier of the approval window and the run’s deadline.
Query parameters
- state'pending' | 'approved' | 'rejected' | 'expired' | 'cancelled'optional
- Only approvals in this state.
- runIdstring (uuid)optional
- Only this run’s approvals.
- limitintegeroptional
- 1 to 200. Default 100.
curl "https://api.rykon.ai/v1/approvals?state=pending" \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"approvals": [
{
"id": "c41e9b70-5d2a-4f83-9e61-7a0b3d8c2f94",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"tool_call_id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
"tool": "record_finding",
"risk": "R0",
"reason": "the agent's rules ask a person for this tool",
"proposed_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit."
},
"action_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
},
"state": "pending",
"edit_count": 1,
"edited_by": "member:2a6f9c13-8b4e-4d07-b1a5-6e3c0d9f7b28",
"edited_at": "2026-10-30T14:03:40.002Z",
"decided_by": null,
"decided_at": null,
"decision_note": null,
"expires_at": "2026-10-30T14:17:13.120Z",
"created_at": "2026-10-30T14:02:31.774Z",
"expired": false
}
]
}In the reference: List approvals
After the fact
A run's tool calls show what was asked (input), what ran (final_input) and the decision with its reason. The record keeps every step, append only.
/v1/runs/{id}/tool-callsList a run’s tool calls
Every tool the run asked to use and what was decided: allowed (within the agent’s level, run at once), approval (waited for a person) or refused. input is what the agent asked for; final_input is what ran, which differs when a person edited the action.
Path parameters
- idstring (uuid)required
- The run's id. An id from another account answers 404, exactly like one that does not exist.
curl https://api.rykon.ai/v1/runs/e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57/tool-calls \
-H "Authorization: Bearer $RYKON_AI_KEY"{
"toolCalls": [
{
"id": "e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57",
"tenant_id": "5e1d7c40-2b9a-4f6e-8d31-0c7a9e2b4f18",
"run_id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40",
"agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"call_key": "toolu_01HqK3",
"tool": "record_finding",
"risk": "R0",
"autonomy": "L0",
"input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit."
},
"final_input": {
"finding": "Northgate Supply is cheapest at $4.18 per unit (quote 2 of 3)."
},
"decision": "approval",
"decision_reason": "the agent's rules ask a person for this tool",
"state": "done",
"result": {
"recorded": true
},
"error": null,
"created_at": "2026-10-30T14:02:31.774Z",
"finished_at": "2026-10-30T14:03:52.180Z"
}
]
}In the reference: List a run’s tool calls