Set up an agent

An agent in K-Block is a record that stands for one of your AI agents or automations. Three things decide what it can do: the policy that decides each of its calls, the delegation that grants it actions, and the gateway API key it authenticates with. Without all three, the Gateway refuses its calls.

This page sets up all three, connects the agent, and explains how to switch it off again. For the concept, see Agents.

Before you start

1. Create the agent

1. Open the form

   In the dashboard, open Agents and select New agent.

2. Fill it in

   • Name: how the agent appears in actions, approvals and receipts (up to 200 characters, unique in the organization; 409 NAME_TAKEN otherwise).
   • Policy: the policy whose active version decides this agent's calls. No policy (deny every call) is allowed, but the agent can then do nothing.
   • Description (optional).

3. Create

   Select Create agent. The dashboard opens the agent's page.

The number of agents per organization depends on your plan (402 PLAN_LIMIT_EXCEEDED over the limit). Agents cannot be deleted. When you no longer need one, disable it (see Lifecycle).

2. Choose its policy

The policy is the agent's rulebook: for each call it says allow, deny or require approval. Every agent uses at most one policy, and several agents can share one. A policy that has no active version denies every call (NO_POLICY), as does an agent without a policy.

To change the policy later, an owner or admin opens the agent and changes Policy under Agent settings, then selects Save changes. Switching the policy:

• takes effect on the agent's next call;
• ends any open observe window of the agent;
• makes calls that the old policy allowed but that have not run yet fail with POLICY_CHANGED; the agent's next call is decided by the new policy;
• leaves pending approval requests and calls a person already approved as they are: they can still be decided and run.

Before you rely on the policy, try it: Test a call on the agent's page runs a dry run of a call against the agent's current setup, without executing anything. See Test and simulate.

3. Sign a delegation

A delegation is a signed statement by your organization's principal that the Gateway may act for this agent, for a list of actions, until a set time. The Gateway checks it on every call: a call whose action no valid delegation grants is denied (NO_DELEGATION), and tools whose action is not granted do not appear in the agent's tools/list.

The delegation is signed in your browser with the principal's key. The Cloud API and K-Block's database never receive or store that key: it is generated, stored and used in your browser by the dashboard's code (see How the browser stores keys). On a new agent's page, the form Authorize this agent is open; otherwise select Sign a new delegation… under Delegations.

1. Choose the actions

   Under Actions of your exposed tools, tick the actions this agent may use. In Other actions or patterns you can add more, separated by spaces or commas, including prefix patterns such as refund.*. kblock.task is added automatically. A bare * and the kblock. namespace are not allowed.

   The delegation only makes actions possible: the policy still decides every call.

2. Set the limits

   • Spending limit per call (optional) and Currency: the largest amount one call may carry. With a limit, calls of tools without an amount mapping are refused, because they carry no amount to check.
   • Valid from (optional) and Expires: the window in which the delegation is valid. The form proposes 90 days from now; the expiry must be in the future.

   An approval request never outlives the delegation it acts under: its expiry is cut to the delegation's.

3. Check the delegate

   Under Delegate, the form shows the K-Block Gateway's key ID (KID), the identity that receives the authority. When the dashboard knows which Gateway identity to trust, it confirms that this KID is that identity. If you see No gateway identity is pinned instead, compare the KID with the Gateway KID that K-Block gave you before you sign; if you do not have it, contact K-Block support. A warning also appears when the KID differs from the one this agent's earlier delegations went to.

4. Sign

   Select Sign and submit delegation. On success the page says the delegation was signed and stored, and it appears under Delegations with its permissions, spending limit, state and validity.

The Cloud API checks that the delegation is signed by the organization's current principal, delegates to the registered Gateway, names exactly this organization and agent, grants kblock.task, carries no constraint other than a spending limit, and has not expired. An agent can hold at most 100 active delegations. When several delegations cover a call, the newest usable one is used.

4. Create the gateway API key

The agent authenticates to the Gateway with a gateway API key. Each key belongs to exactly one agent.

1. Open the form

   On the agent's page, under Gateway API keys, select Create a gateway key. (Or open API keys and select New API key.)

2. Fill it in

   • Name: where the key is used, for example support-agent-prod.
   • Environment: Live or Test. It is recorded on every action made with the key and shown to approvers.
   • Agent: the agent this key authenticates.
   • Expires (optional): leave empty for a key that does not expire.

   Owners and admins also see a Kind choice; keep Gateway key. (Management keys are for scripts that use the Cloud API; see API keys.)

3. Create and copy the key

   Select Create key. The full key, of the form kb_live_… or kb_test_…, is shown once. Copy it into your agent's secret store now: K-Block keeps only a keyed hash and cannot show it again. The same panel shows the Gateway MCP endpoint your agent connects to (the Gateway URL followed by /mcp) and the Gateway KID; keep the KID to check receipts later. If the panel does not show one of them, contact K-Block support.

A key keeps working only while the member who created it is still an enabled member with a role that may create gateway keys. When that member leaves the organization or is demoted below developer, their keys are revoked.

5. Connect the agent

The agent connects to the Gateway's MCP endpoint over Streamable HTTP and sends the key as a bearer token:

POST /mcp HTTP/1.1
Host: gateway.example.com
Authorization: Bearer kb_live_…
Content-Type: application/json
Accept: application/json, text/event-stream

Any MCP client that supports Streamable HTTP and custom headers can do this. The TypeScript client handles the connection, approvals and results for you. This program reads the Gateway URL and the API key from KBLOCK_GATEWAY_URL and KBLOCK_API_KEY, two environment variables of its own:

import { connectKBlock, explainResult } from "@kblockai/client";

const client = await connectKBlock({
  gatewayUrl: process.env.KBLOCK_GATEWAY_URL ?? "", // e.g. https://gateway.example.com
  apiKey: process.env.KBLOCK_API_KEY ?? "",          // the agent's gateway API key
});

// Only the tools this agent's delegation grants, enabled and authorized.
const tools = await client.listTools();
console.log(tools.map((t) => t.name));

const result = await client.callTool("lookup_order", { order_id: "ord_123" });
console.log(explainResult(result));
await client.close();

Install it with npm install --save-exact @kblockai/client@0.1.0-rc.1 (a pre-release). For Python, see Python; for the full client, see TypeScript client.

Check the connection

See Gateway and tools troubleshooting for more.

Lifecycle

Disable the agent

On the agent's page, set Status under Agent settings to Disabled (every call refused) and select Save changes. From the next request on, the Gateway refuses the agent's keys with 401, and approved calls that have not run yet are refused when the agent retries them. Disabling also ends the agent's open observe window. Set the status back to Active to re-enable it; its keys and delegations work again if they are still valid.

Revoke a delegation

Under Delegations, select Revoke on the delegation and confirm with Sign revocation. The revocation is signed with the principal's key and takes effect at the time it is signed. Pending and approved calls under the delegation can no longer execute, and its actions disappear from the agent's tools/list unless another delegation grants them.

If a call under the delegation is executing at that moment and the revocation is dated at or before it, the revocation is refused (409 CONFLICT, reason REVOCATION_PREDATES_EXECUTION), but the delegation is already withdrawn: no new call can use it, and it is listed as revocation pending. The page then offers Sign a fresh revocation (in the list, Sign revocation again). A revocation dated after the running call started is recorded.

A delegation also ends on its own at its expiry. Sign a new one before then if the agent should keep working.

Revoke a gateway API key

Open API keys, find the key, and select Revoke, then confirm. Requests with the key fail immediately with 401, including the next request of an agent that is already connected. Create a new key and give it to the agent to rotate.

Revoking a key or a delegation does not cancel calls that are already waiting for approval. A call made with a revoked key stays open, and a repeat with another gateway key of the same agent can still continue it and, once it is approved, run it. To stop one of those, an owner or admin cancels it on its action page; see How approvals work.

Next steps