Quickstart - Sikaru SDK

This guide takes a product server from zero to one Sikaru-managed agent run. The example defines a support agent with a local CRM tool, sends a user request, and records the completed Experience so Sikaru can learn from production outcomes, failures, feedback, and eval evidence over time.

Prerequisites

A Sikaru project.
A project-scoped API key stored on your server.
Python 3.10+ or Node.js 18+.

Do not expose SIKARU_API_KEY in browser bundles, mobile apps, or customer-controlled code.

1. Install the SDK

Python
TypeScript

pip install sikaru-sdk

npm install @sikaru/sdk

2. Configure the server environment

export SIKARU_API_KEY="sk_sikaru_..."
export SIKARU_PROJECT_ID="proj_..."

Optional override for non-production environments:

export SIKARU_API_URL="https://api.sikaru.ai"

3. Create a project client

Python
TypeScript

from sikaru_sdk import Sikaru, tool

sikaru = Sikaru(project="proj_123")

import { createSikaru, tool } from "@sikaru/sdk";

const sikaru = createSikaru({
  apiKey: process.env.SIKARU_API_KEY!,
  project: process.env.SIKARU_PROJECT_ID!,
  baseUrl: process.env.SIKARU_API_URL,
});

4. Declare a product-owned tool

Local tools run in your process. Sikaru sees the declared capability name and the returned result, not your internal credentials.

Python
TypeScript

@tool("crm.search", description="Search CRM account records.")
def search_crm(account_id: str):
    return {"risk": "legal review", "account_id": account_id}

const searchCrm = tool({
  capability: "crm.search",
  description: "Search CRM account records.",
  inputSchema: { type: "object" },
  execute: async ({ accountId }) => {
    return { risk: "legal review", accountId };
  },
});

5. Run the agent

Python
TypeScript

support = sikaru.agent("support", tools=[search_crm])

result = support.respond(
    messages=[{"role": "user", "content": "Find renewal risk for Acme."}],
    user="user_123",
    conversation="conv_123",
    tenant="tenant_123",
)

print(result.output)

const support = sikaru.agent("support", {
  tools: { searchCrm },
});

const result = await support.respond({
  messages: [{ role: "user", content: "Find renewal risk for Acme." }],
  user: "user_123",
  conversation: "conv_123",
  tenant: "tenant_123",
});

console.log(result.output);

respond(...) starts a managed run, streams events back to the SDK, executes local tools when requested, records the final experience, and returns the final output.

What happens next

After the first run, Sikaru has a managed run record and a captured Experience. As you add more traces, feedback, corrections, and eval rubrics, Sikaru can identify recurring misses and propose reviewed improvements.

Stream and resume runs

Use lower-level run control when your app needs event-by-event rendering or recovery.

Record your own executions

Use Experience when your product already ran the agent behavior itself.

​Prerequisites

​1. Install the SDK

​2. Configure the server environment

​3. Create a project client

​4. Declare a product-owned tool

​5. Run the agent

​What happens next

Stream and resume runs

Record your own executions

Prerequisites

1. Install the SDK

2. Configure the server environment

3. Create a project client

4. Declare a product-owned tool

5. Run the agent

What happens next