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

  1. The agent asks to call a tool. The agent only asks; tools run in the control plane.
  2. The control plane reads the agent fresh, so a level lowered a moment ago applies now.
  3. 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.
  4. 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.

GET/v1/tools

List 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.

Needsagents:readReturns200 OK
GET/v1/tools
curl https://api.rykon.ai/v1/tools \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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

The MCP server lists what waits for you with a link to the console, and stops there: no MCP connection can answer a decision or approve an action, whatever your role. A person answers, in the console.
GET/v1/approvals

List 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.

Needsapprovals:readReturns200 OKPaged by limit

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.
GET/v1/approvals
curl "https://api.rykon.ai/v1/approvals?state=pending" \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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.

GET/v1/runs/{id}/tool-calls

List 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.

Needsruns:readReturns200 OK

Path parameters

idstring (uuid)required
The run's id. An id from another account answers 404, exactly like one that does not exist.
GET/v1/runs/{id}/tool-calls
curl https://api.rykon.ai/v1/runs/e9d02a6b-3c71-4b5f-8e4a-2f6c1d9b0a57/tool-calls \
  -H "Authorization: Bearer $RYKON_AI_KEY"
Response
200 OK
{
  "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