K
KoladrDocs
Sign in

SDK & Integration

The Koladr SDK is how your agents communicate with the control plane. This guide covers installation, the core API methods, and a complete real-world example.

How the SDK Works

The SDK provides a thin client that sends structured data to the Koladr API. Your agent uses four primary methods:

  1. startRun() — opens a new run session
  2. logEvents() — records events during the run
  3. requestAction() — requests permission to take an action
  4. endRun() — closes the run with an outcome summary

Every call is authenticated with your API key. The SDK handles retries, serialization, and error formatting.

Installation

npm install @koladr/sdk

The SDK is a TypeScript-first package with full type definitions. It works in Node.js, Bun, and any server-side JavaScript runtime.

Initialization

koladr.ts
import { KoladrClient } from "@koladr/sdk";

const koladr = new KoladrClient({
  apiKey: process.env.KOLADR_API_KEY!,
  agentId: "agt_support_bot_prod",
});

The agentId is the ID you received when registering your agent in the dashboard. The apiKey should come from your environment variables.

Starting a Run

Call startRun() at the beginning of every agent task. Include a trigger (what initiated this run) and any relevant metadata.

start-run.ts
const run = await koladr.startRun({
  trigger: "support-ticket",
  metadata: {
    ticketId: "TKT-1042",
    customerTier: "premium",
    channel: "chat",
  },
});

// run.id is the unique identifier for this run session
console.log("Run started:", run.id);

The returned run.id is used in all subsequent calls to associate events and actions with this run.

Logging Events

Use logEvents() to record what your agent is doing during a run. Events create the timeline that operators and approvers see in the dashboard.

log-events.ts
await koladr.logEvents(run.id, [
  {
    type: "context.retrieved",
    data: {
      source: "knowledge-base",
      documentsFound: 3,
      relevanceScore: 0.92,
    },
  },
  {
    type: "intent.classified",
    data: {
      intent: "refund-request",
      confidence: 0.95,
      reason: "Customer reported defective product",
    },
  },
]);

✦Log generously

The more context you log, the easier it is for approvers to make decisions and for operators to investigate incidents. Include confidence scores, sources, and reasoning.

Requesting an Action

When your agent needs to perform a real-world action, use requestAction(). This is the critical control point where Koladr evaluates policies and determines the outcome.

request-action.ts
const result = await koladr.requestAction(run.id, {
  action: "refund.create",
  params: {
    amount: 79.99,
    currency: "USD",
    reason: "Defective product — customer request",
    orderId: "ORD-8837",
  },
  riskContext: {
    customerTier: "premium",
    orderAge: "3 days",
  },
});

The action field is a string identifier for the type of action (e.g. refund.create, email.send, ticket.update). The params contain the action-specific data. Optionally include riskContext for additional policy evaluation data.

Handling Responses

Every requestAction() call returns a result with a status. Your agent should handle each status appropriately:

handle-response.ts
switch (result.status) {
  case "approved":
    // Action was allowed by policy and executed
    console.log("Refund processed:", result.executionId);
    break;

  case "pending_approval":
    // Action requires human review — agent should wait or move on
    console.log("Refund pending approval:", result.approvalId);
    // Optionally poll for resolution or handle asynchronously
    break;

  case "blocked":
    // Policy blocked this action
    console.log("Refund blocked:", result.reason);
    // Handle gracefully — inform the customer, escalate, etc.
    break;

  case "error":
    // Something went wrong during execution
    console.error("Execution failed:", result.error);
    break;
}

Ending a Run

Always end runs, even when errors occur. This keeps your run history clean and ensures operators can distinguish between completed and abandoned runs.

end-run.ts
await koladr.endRun(run.id, {
  outcome: "completed",
  summary: "Processed refund request for order ORD-8837",
});

Full Example: Support Agent Refund Flow

Here is a complete example showing a support agent handling a refund request through Koladr:

support-agent.ts
import { KoladrClient } from "@koladr/sdk";

const koladr = new KoladrClient({
  apiKey: process.env.KOLADR_API_KEY!,
  agentId: "agt_support_bot_prod",
});

async function handleSupportTicket(ticket: {
  id: string;
  customerTier: string;
  message: string;
}) {
  // 1. Start a run
  const run = await koladr.startRun({
    trigger: "support-ticket",
    metadata: { ticketId: ticket.id, customerTier: ticket.customerTier },
  });

  try {
    // 2. Log context retrieval
    await koladr.logEvents(run.id, [
      {
        type: "context.retrieved",
        data: { source: "knowledge-base", query: ticket.message },
      },
    ]);

    // 3. Agent determines a refund is appropriate
    await koladr.logEvents(run.id, [
      {
        type: "intent.classified",
        data: { intent: "refund-request", confidence: 0.95 },
      },
    ]);

    // 4. Request the refund action through Koladr
    const result = await koladr.requestAction(run.id, {
      action: "refund.create",
      params: {
        amount: 79.99,
        currency: "USD",
        reason: "Defective product",
        orderId: "ORD-8837",
      },
    });

    if (result.status === "approved") {
      await koladr.logEvents(run.id, [
        { type: "action.completed", data: { refundId: result.executionId } },
      ]);
    } else if (result.status === "pending_approval") {
      await koladr.logEvents(run.id, [
        { type: "action.pending", data: { approvalId: result.approvalId } },
      ]);
    } else {
      await koladr.logEvents(run.id, [
        { type: "action.blocked", data: { reason: result.reason } },
      ]);
    }

    // 5. End the run
    await koladr.endRun(run.id, {
      outcome: result.status === "approved" ? "completed" : "escalated",
      summary: `Refund ${result.status} for order ORD-8837`,
    });
  } catch (error) {
    await koladr.endRun(run.id, {
      outcome: "error",
      summary: String(error),
    });
    throw error;
  }
}

ℹREST API

If you are not using TypeScript, you can call the Koladr API directly over HTTP. The SDK methods map 1:1 to REST endpoints. See the API reference for details.

Error Handling

The SDK throws typed errors for common failure modes:

  • KoladrAuthError — invalid or expired API key
  • KoladrNotFoundError — run or agent not found
  • KoladrValidationError — invalid request parameters
  • KoladrRateLimitError — too many requests

Wrap your Koladr calls in try/catch blocks and always end the run in a finally block to prevent orphaned runs.

Next

Policies

Define rules for how agent actions are governed

→