Execution API

The Execution API is the primary interface for running and managing AI agents on the Kla platform. It allows you to start executions, monitor their progress in real-time, and handle human-in-the-loop approvals.

Base URL

https://api.kla.local/execution

Authentication

Include your JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Starting an Execution

To start an agent execution, send a POST request to /v1/executions. You can specify the agent by its ID or its immutable hash.

Request

POST /v1/executions
Content-Type: application/json

{
  "agentId": "agent-123",
  "input": {
    "prompt": "Analyze the quarterly report",
    "context": {
      "reportUrl": "https://example.com/report.pdf"
    }
  },
  "budgets": {
    "maxSteps": 50,
    "maxCostUsd": 5.0
  }
}

Response

{
  "executionId": "exec-456",
  "status": "PENDING",
  "message": "Execution started successfully"
}

Tracking Status

You can poll for status updates or subscribe via WebSocket for real-time events.

Polling

GET /v1/executions/exec-456

Response:

{
  "executionId": "exec-456",
  "status": "RUNNING",
  "currentStep": 3,
  "progressPercent": 15
}

WebSocket Subscription

Connect to the WebSocket endpoint to receive live updates.

const ws = new WebSocket('wss://api.kla.local/execution/ws?token=<your-token>');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'subscribe',
    executionId: 'exec-456'
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log('Update:', msg);
};

Handling Approvals

If an agent attempts a sensitive action (e.g., deleting a resource) that requires approval, the execution will pause and emit an approval_required event.

Approval Event

{
  "type": "execution.approval_required",
  "executionId": "exec-456",
  "data": {
    "approvalId": "appr-789",
    "action": "delete_resource",
    "reason": "Destructive operation"
  }
}

Submitting a Decision

To approve or deny the action:

POST /v1/approvals/appr-789/decision
Content-Type: application/json

{
  "decision": "APPROVED",
  "comment": "Proceed with deletion"
}

Client SDK

For TypeScript/JavaScript projects, we recommend using our official client SDK:

npm install @kla/execution-client

import { ExecutionClient } from '@kla/execution-client';

const client = new ExecutionClient({
  baseUrl: 'https://api.kla.local/execution',
  token: process.env.KLA_API_TOKEN
});

const execution = await client.startExecution({
  agentId: 'agent-123',
  input: { prompt: 'Hello world' }
});