SDK Reference

TypeScript SDK for the KeylessAI AI Action Governance Kernel.

Installation

npm install @keylessai/sdk

Constructor

import { KeylessAI } from '@keylessai/sdk';

const keyless = new KeylessAI(config: KeylessConfig);

KeylessConfig

Field	Type	Required	Description
apiKey	string	Yes	API key (ka_live_xxx or ka_test_xxx)
orgId	string	Yes	Organization UUID
agentId	string	Yes	Agent UUID for this SDK instance
baseUrl	string	No	Default: https://app.keyless-ai.com/api/v3
autoPolicy	boolean	No	Default: true. Auto-requires approval for $1,000+
timeout	number	No	Request timeout in ms. Default: 30000
maxRetries	number	No	Retry count on transient failures. Default: 2

Methods

execute(input: ExecuteInput): Promise<ExecuteResult>

Execute a governed action through the full Kernel pipeline: Intent → Policy → Approval → Execute → Ledger.

ExecuteInput

Field	Type	Required	Description
action	string	Yes	Action name (e.g., "ads.budget_increase")
amount	number	No	Action amount for budget tracking
target	Record<string, unknown>	No	Structured target metadata
idempotencyKey	string	No	Prevents duplicate execution
requireApproval	boolean	No	Force approval regardless of policy

ExecuteResult

Field	Type	Description
intentId	string	Intent UUID
executionId	string | null	Execution UUID (null if awaiting approval)
status	'completed' | 'awaiting_approval' | 'denied' | 'failed'	Final status
result	Record<string, unknown>	Execution result payload
error	string	Error message (if failed/denied)
cost	number	Actual cost deducted from budget
riskScore	number	Computed risk score (0.0 - 1.0)
steps	PipelineStep[]	Detailed pipeline step log

---

simulate(input: SimulateInput): Promise<SimulateResult>

Dry-run an action through the policy engine without executing. Returns the policy decision, risk score, and budget impact.

SimulateResult

Field	Type	Description
riskScore	number	Computed risk (0.0 - 1.0)
policyDecision	'allow' | 'require_approval' | 'deny'	Policy verdict
budgetImpact	{ cost, remaining }	Projected budget effect
requiresApproval	boolean	Whether approval is needed
warnings	string[]	Policy warnings

---

ledger(query: LedgerQuery): Promise<LedgerResult>

Query the audit ledger for intents, executions, and approvals.

LedgerQuery

Field	Type	Description
intentId	string	Filter by specific intent
agentId	string	Filter by agent
status	string	Filter by status
from	string	Start date (ISO-8601)
to	string	End date (ISO-8601)
limit	number	Max results (default 50, max 100)

---

waitForApproval(intentId: string, options?: WaitOptions): Promise<ApprovalResult>

Long-poll until the intent is approved or rejected. Default timeout: 5 minutes.

Field	Type	Default	Description
timeout	number	300000	Max wait time in ms
pollInterval	number	3000	Poll interval in ms

---

resume(intentId: string): Promise<ExecuteResult>

Resume execution of an approved intent. Runs the remaining pipeline steps (budget check, execute, audit).

Error Handling

import { KeylessAI, KeylessError } from '@keylessai/sdk';

try {
  const result = await keyless.execute({
    action: 'ads.budget_increase',
    amount: 50000,
  });
} catch (err) {
  if (err instanceof KeylessError) {
    console.error(err.statusCode); // 403, 409, 422, etc.
    console.error(err.code);       // 'BUDGET_EXCEEDED', 'POLICY_DENIED', etc.
    console.error(err.message);    // Human-readable error
  }
}

Error Codes

Code	HTTP	Description
POLICY_DENIED	403	Action denied by policy engine
BUDGET_EXCEEDED	422	Insufficient budget remaining
DUPLICATE_EXECUTION	409	Idempotency key already used
INTENT_LOCKED	409	Intent already being executed
APPROVAL_EXPIRED	410	Approval window has expired
AGENT_INACTIVE	403	Agent is disabled or not found
RATE_LIMITED	429	Too many requests