An agent is the name under which an AI application calls tools through the Gateway. In K-Block an agent is a record in your organization, not a running program and not a cryptographic identity. Everything that decides what the application may do hangs off that record: the policy that judges each call, the delegations that authorize it, and the gateway API keys it connects with.
Create one agent for each application (or each distinct role of an application) whose tool calls you want to judge, record and audit separately.
What is an agent?
An agent is four things put together:
| Part | What it does |
|---|---|
| The record | A name (unique in the organization), a description and a status (active or disabled). Actions, approvals and receipts show this name. |
| One policy | The policy whose active version decides each of the agent's calls: allow, require approval or deny. See Policies. |
| Delegations | Signed grants from the organization principal that authorize the Gateway to perform specific actions for this agent, until they expire. See Delegations. |
| Gateway API keys | The secrets your application presents to the Gateway. Each gateway key belongs to exactly one agent, so the key tells the Gateway which agent is calling. |
Application
presents a gateway API key
Gateway
finds the key's agent
Policy
of that agent decides
Delegation
of that agent authorizes
Does an agent have its own key?
No signing key. The agent authenticates to the Gateway only with a gateway API key, a bearer secret. The signed records of a protected action (the task, proposal, execution and result) are signed by the Gateway with its own service identity, under a delegation from the organization principal to the Gateway that names the agent. Your application does not need a K-Block private key to call tools through the Gateway.
An agent record can store an optional agent KID, a public K-Block identity of type agent, set through the Cloud API. K-Block verifies it when you set it and shows it on the agent page, but in this version nothing uses it: not authentication, not decisions, not evidence. Leave it empty unless you have a reason to record it.
Status and lifecycle
| Status | Calls through the Gateway |
|---|---|
active | Accepted, if the key is valid, and then judged by the policy and the delegations. |
disabled | Refused. The agent's gateway keys stop authenticating, and an approved action of this agent is not executed while the agent is disabled. |
Disabling an agent also ends its open observe window. Enabling it again restores its keys and delegations as they were; observe stays off until someone starts a new window.
An agent cannot be deleted in this version: there is no delete control or route. Disable an agent you no longer use. The number of agents is limited by the organization's plan, and disabled agents count toward that limit.
Create an agent
Owners, admins and developers can create agents (and management API keys with the agents:write scope). In the dashboard, open Agents and select New agent, enter a Name, choose a Policy and select Create agent.
A new agent can do nothing yet. Before its first call it needs:
- A policy with an active version. An agent without a policy, or whose policy has no active version, has every call denied with
NO_POLICY. - A delegation signed by the organization principal. Without one, every call that the policy does not deny is denied with
NO_DELEGATION(orNO_PRINCIPALwhile the organization has no principal), and the agent's tool list is empty. - A gateway API key, which your application sends to the Gateway.
The full walk-through is in Set up an agent.
Policy association
Each agent points at one policy (or none). Several agents can share a policy. The Gateway reads the policy's active version on every call, so activating a new version changes the agent's decisions from the next call on.
Who can change the association:
| Change | Who |
|---|---|
| Choose the policy when creating the agent | Owner, admin, developer, management API keys with agents:write |
| Switch an existing agent to another policy | Owner or admin, signed in. Developers and management API keys get ADMIN_REQUIRED. |
Switching is restricted because the policy decides what the agent's delegations let through without approval. A switch also ends the agent's open observe window, and an allowed action decided under the previous policy but not yet executed is refused at execution with POLICY_CHANGED.
Delegations
A delegation is what authorizes the agent at all. The organization principal signs, in the browser of someone who holds its key, which actions the Gateway may perform for this agent, with an expiry and an optional spending limit per call. On the agent page, owners and admins see the Authorize this agent form while the agent has no active delegation; once it has one, they open the form again with Sign a new delegation… in the Delegations card.
For each call the Gateway uses the newest delegation that is still valid and covers the call's action. An agent can have at most 100 active delegations. The agent's tool list (tools/list) contains only tools whose actions a valid delegation grants. Details, revocation and expiry are in Delegations.
Gateway API keys
A gateway key has the form kb_live_… or kb_test_…. It is shown once, when it is created, and K-Block stores only a keyed hash of it.
- Owners, admins and developers create gateway keys, each bound to one agent of the organization. From the agent page, Create a gateway key in the Gateway API keys card opens the API keys page with the agent selected.
- The environment (
liveortest) is recorded on every action and decides which observe windows apply. Test and live keys reach the same tools, MCP servers and credentials: a test call is a real call. - A key can have an expiry. A revoked or expired key, a disabled agent, or a key whose creator has left the organization or lost the role needed to create it, is refused with HTTP 401.
Your application sends the key as Authorization: Bearer kb_live_… to the Gateway's MCP endpoint. See API keys and the TypeScript client.
Observe windows
An observe window is a time-limited period in which an agent's policy is observed rather than enforced for certain calls: calls that the policy's default would deny or hold for approval are allowed and executed, and each is marked as an observe override. It lets you learn what a new policy would block before you enforce it. Explicit deny rules are always enforced, and observe never relaxes an emergency stop.
| Property | Rule |
|---|---|
| Scope | One agent, and the environments you choose (live, test or both). At most one open window per agent. |
| Prerequisites | The owner turned observe mode on and gave the live opt-in in Settings; the agent is active and its policy has an active version that is not an emergency stop. |
| Who starts it | An owner or admin, signed in, with Start observe… in the agent's Enforcement card. You type the agent's name, a reason of 10–1000 characters and a duration up to the owner's maximum (at most 168 hours). |
| What it relaxes | default relaxes only the policy's default; default_and_approvals also relaxes require_approval rules that are not marked as guards. |
| Who ends it | Owners, admins and developers (End now) and management API keys with agents:write, or automatically: when it expires, when the agent is disabled or switched to another policy, on an emergency stop, when the owner turns observe off or withdraws the live opt-in, or when the owner lowers the maximum below the window's length. |
What can go wrong
| Symptom | Likely cause |
|---|---|
Every call is denied NO_POLICY | The agent has no policy, or its policy has no active version. |
Every call is denied NO_DELEGATION; the tool list is empty | No valid delegation from the current principal grants the action, or the delegation expired, was revoked, was signed by a principal that has since been replaced, or was signed for a Gateway identity that has since been replaced. |
| HTTP 401 from the Gateway | The key is wrong, revoked or expired, the agent is disabled, or the key's creator left or lost their role. |
ADMIN_REQUIRED when saving the agent | A developer tried to switch the agent's policy. |
The Gateway identity is K-Block's, and only K-Block can replace it. If that happened, an owner or admin who holds the principal key signs a new delegation on the agent's page: the signing form warns when the Gateway identity differs from the agent's earlier delegations. If you did not expect the change, contact K-Block support before you sign.
More in Gateway and tools.