Agents

An agent is the identity your AI application calls tools under. For each call, the Gateway checks three things that belong to the agent: its policy, its delegation and the gateway API key it presents. The Agents page lists your agents, and each agent's page manages these three things. See Agents for the concept.

Every role can open the agents list and an agent's page. What each role can change is listed below.

Who can do what

The Cloud API enforces these rules. See Roles and permissions.

The agents list

Each row shows:

With two or more agents, a summary line counts agents in observe mode, not authorized, without a policy, and active. The list loads 50 agents at a time; use the load-more control at the bottom for the rest.

A new organization without agents shows what an agent is made of (a policy, a delegation and a gateway key) and the next step.

Create an agent

1. Open the form

   Select New agent (owners, admins and developers). If the organization has no policy yet, the form says so and links to Policies, and an empty Agents page offers Create a policy first: without a policy, the agent denies every call.

2. Fill in the agent

   • Name: how the agent appears in actions, approvals and receipts. It must be unique in the organization.
   • Policy: the policy whose active version decides the agent's calls, or No policy (deny every call). The list shows the first 100 policies.
   • Description (optional).

3. Create

   Select Create agent. The agent's page opens. The agent cannot make calls yet: it needs a delegation and a gateway key.

Creating an agent can fail with NAME_TAKEN (the name is used), POLICY_NOT_FOUND or PLAN_LIMIT_EXCEEDED (the plan's agent limit is reached; see Billing).

The agent's page

The page header shows the agent's name and description, and Test a call, which opens a dry run for this agent (see Test and simulate). Under the header, a summary shows:

• Status: a disabled agent's calls are all refused.
• Enforcement: Enforced, or Observe until a time and which keys the window covers.
• Policy: the policy name, or No policy (every call is denied).
• Authorization: the number of active delegations (counted as in the list), or Not authorized.
• Gateway keys: the number of keys that are not revoked (expired keys included), or None yet.

Then come the Enforcement, Delegations and Gateway API keys cards, and Agent settings.

Agent settings

Agent settings holds Name, Status (Active or Disabled (every call refused)), Policy and Description. Select Save changes. Identifiers shows the agent ID and creation time.

• Only owners and admins can switch the policy. For developers the select is disabled, and the API answers ADMIN_REQUIRED if a developer changes it.
• Disabling the agent also ends its open observe window. Switching its policy ends the window too.
• K-Block does not delete agents in this version. Set Status to Disabled to stop an agent.

Delegations

A delegation is signed authority from the organization principal to the K-Block Gateway: the Gateway may open tasks for this agent and execute exactly the listed actions, within an optional amount limit and a time window. Without an active delegation, the Gateway denies every call of the agent. The agent's policy still decides each call. See Delegations.

The Delegations card lists each delegation with:

When several active delegations cover a call, the newest one is used.

Sign a delegation

You need the owner or admin role, and a copy of the organization principal's private key that your own account generated or imported in this browser. The principal is generated by an owner under Settings and lives only in the browser where it was generated, or where a key backup was imported (see Settings and Your account).

1. Open the form

   While the agent has no active delegation, the Authorize this agent form is already open. Otherwise select Sign a new delegation… on the Delegations card.

2. Choose the actions

   Check actions from Actions of your exposed tools, or type more in Other actions or patterns, separated by spaces or commas (for example refund.*). kblock.task is added automatically.

3. Set the limits

   • Spending limit per call (optional) and Currency. With a spending limit, calls of tools without an amount mapping are refused, because they carry no amount to check.
   • Valid from (optional) and Expires. The expiry defaults to 90 days from now and must be in the future.

4. Check the delegate

   The Delegate section shows the K-Block Gateway's KID, verified in your browser. When the dashboard has a pinned Gateway identity, the section confirms that this is the Gateway identity the dashboard trusts, and your browser signs a delegation for no other identity. Otherwise the page shows the warning No gateway identity is pinned: before you sign, compare the KID with the Gateway KID that K-Block gave you. If you cannot compare them, contact K-Block support before you sign. A warning appears when the KID differs from the agent's earlier delegations: sign only if you know that K-Block replaced the Gateway's identity; if you are not sure, contact K-Block support first.

5. Sign

   Select Sign and submit delegation. The delegation is signed in your browser and stored. The agent can call the delegated actions once it also has a gateway key.

If your account holds no copy of the principal's key in this browser, the form says so (The organization principal's key is not available to you in this browser) and links to Settings. If this browser's key storage cannot be read, the form shows the error "This browser's key storage is not available, so the principal's key cannot be used here" instead: that does not mean you have no copy. Close other dashboard tabs and reload the page. If it stays, check that the browser lets this site store data: some private windows and privacy settings block it. If the Gateway identity cannot be verified, the page tells you not to sign.

An agent can hold at most 100 delegations that are not revoked, withdrawn or expired. Beyond that, the Cloud API refuses a new one (CONFLICT, reason TOO_MANY_DELEGATIONS): revoke the ones that are no longer needed first.

Revoke a delegation

Revoke on a delegation row asks for confirmation, then signs a revocation with the principal's key. Pending and approved actions under that delegation can no longer execute.

If your account holds no copy of the principal's key in this browser, the Delegations card says "Revoking a delegation needs the organization principal's key, which is not available to you in this browser." and links to Organization settings. If this browser's key storage cannot be read, it shows the error "This browser's key storage is not available, so the principal's key cannot be used here"; follow the advice for the delegation form above.

If a call under the delegation is still running, the revocation is refused (CONFLICT, reason REVOCATION_PREDATES_EXECUTION). The delegation is then revocation pending: no new call uses it. The notice on the card offers Sign a fresh revocation, dated after the running call started; later, the delegation's row offers Sign revocation again. If the call is still running, the new revocation can be refused again: sign it once the call has ended.

A superseded delegation has no Revoke button: only its issuer, the previous principal, could sign its revocation, and it authorizes nothing anyway.

Gateway API keys

The agent presents a gateway API key to the Gateway. The Gateway API keys card lists this agent's gateway keys with their prefix (kb_live_… or kb_test_…), environment, last use and status (Active, Revoked or Expired).

Create a gateway key opens API keys with this agent preselected. The full key is shown once, when it is created.

The card is shown to owners, admins and developers only, because reading API keys needs that permission. It looks for the agent's keys among the organization's first 100 API keys.

Enforcement and observe windows

The Enforcement card shows whether the agent's policy is enforced.

• Enforced: no observe window is open. The card says this whenever no window is open, also for a disabled agent or one without a policy, whose calls are refused anyway.
• Observe mode until …: an observe window is open. Within it, the policy's relaxed decisions are recorded but not enforced. Explicit deny rules, guards and the delegation stay enforced. The card shows who started it, the reason and when it ends.

Owners, admins and developers can select End now. Window report shows what happened during the window, and Earlier windows lists past windows with their reports.

Owners and admins see Start observe… only when the organization's owner has turned observe mode on and given the live opt-in in Settings, and the agent is active and has a policy. The sheet asks which gateway keys the window covers (test, live or both), what it relaxes, the duration and a reason for the audit log. Observe never relaxes an emergency stop. Read Observe and shadow before you use it.

Next steps