Connecting Your Agent

The KeyRunner SDK connects your agent to the Control Plane so that every tool call it makes is governed by your policies automatically.

Your workspace ID and agent ID are shown in a ready-to-copy snippet on the agent's detail page - you do not need to look them up manually.

Node.js

npm install @keyrunner/sdk

import { KeyRunnerSDK } from '@keyrunner/sdk';

const sdk = new KeyRunnerSDK({
  workspaceId: '<your-workspace-id>',
  agentId: '<your-agent-id>',
});

// Execute a governed tool call
const result = await sdk.execute('tool_name', { arg: 'value' });

// List the tools your agent is allowed to call
const tools = await sdk.getTools();

Python

pip install keyrunner

from keyrunner import KeyRunnerSDK

sdk = KeyRunnerSDK(
    workspace_id="<your-workspace-id>",
    agent_id="<your-agent-id>",
)

# Execute a governed tool call
result = await sdk.execute("tool_name", {"arg": "value"})

# List the tools your agent is allowed to call
tools = await sdk.get_tools()

When a call is blocked

If a call does not meet your policy requirements, the SDK raises an error with a clear reason - for example, the tool is not in the agent's policy, or the tool has been disabled. Your agent code can catch this and handle it appropriately:

try {
  const result = await sdk.execute('tool_name', args);
} catch (err) {
  if (err.denied) {
    console.log(err.reason); // what blocked the call
  }
}

Credentials are never exposed to the agent

The SDK does not handle API credentials. When a call is allowed, KeyRunner retrieves the credentials for that API from your configured secret store on the server side and executes the request on behalf of the agent. The agent process never sees the raw credentials.