> ## Documentation Index
> Fetch the complete documentation index at: https://www.sikaru.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sikaru SDK: Continual Learning for Managed Agents

> Build managed AI agents that continually improve from production failures, user feedback, evals, Harbor-compatible trajectories, and OpenInference-compatible traces.

The Sikaru SDK is a small set of server-side primitives for running managed agents and feeding production experience back into their behavior.

Use it to start managed runs, expose product-owned tools, capture agent trajectories, upload OpenInference-compatible traces, connect eval evidence, and review behavior updates before they reach users.

Sikaru is built for production agents that should improve from real work without losing release control. Failures, user feedback, corrections, outcomes, and eval results become evidence for safer and more useful managed-agent behavior.

## Why use Sikaru

Sikaru gives agent teams a practical loop for continual improvement:

* **Run managed agents** from your product server with durable streaming and resume.
* **Keep tools private** by executing product capabilities inside your infrastructure.
* **Capture Experience trajectories** that are compatible with Harbor-style agent trajectory workflows.
* **Bring existing traces** through OpenInference-compatible spans, OTLP resource spans, or native Sikaru trajectories.
* **Use evals as release checks** before managed behavior changes reach staging or production.
* **Review every update** with public diffs, evidence, and explicit approve/promote actions.

## Start here

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/docs/quickstart">
    Install the SDK, configure a project key, declare a tool, and run your first managed agent.
  </Card>

  <Card title="Core concepts" icon="sparkles" href="/docs/concepts">
    Learn how managed agents, evals, Harbor trajectories, and OpenInference-compatible traces fit together.
  </Card>
</CardGroup>

## Choose a workflow

<CardGroup cols={2}>
  <Card title="Managed agent runs" icon="terminal" href="/docs/agents">
    Use `respond`, stream runs manually, resume durable runs, and register local or provider tools.
  </Card>

  <Card title="Experience ingestion" icon="route" href="/docs/experience">
    Record Harbor-compatible agent trajectories, OpenInference spans, signals, outcomes, failures, and raw traces.
  </Card>

  <Card title="Standards files" icon="files" href="/docs/standards">
    Define managed behavior with instructions, skills, eval rubrics, and explicit trace uploads.
  </Card>

  <Card title="Review improvements" icon="git-pull-request" href="/docs/improvements">
    Inspect diffs and evidence, approve to staging, then promote reviewed behavior to production.
  </Card>
</CardGroup>

## Core primitives

| Primitive     | Use it for                                                                                                                                                  |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Sikaru`      | Project-scoped client configured with a server-side API key.                                                                                                |
| `Agent`       | Managed agent entrypoint for a Sikaru-hosted harness.                                                                                                       |
| `Run`         | Durable execution you can stream, resume, and feed tool results into.                                                                                       |
| `Tool`        | Product-owned local or brokered capability Sikaru may request during a run.                                                                                 |
| `Experience`  | Sikaru's agent trajectory abstraction: messages, tool calls, telemetry, outcomes, corrections, and rewards. It is Harbor ATIF and OpenInference compatible. |
| `Improvement` | Reviewable behavior change with public diffs, eval evidence, and release actions.                                                                           |

## Continual learning loop

```mermaid theme={null}
flowchart LR
  Run[Managed agent run] --> Experience[Experience trajectory]
  Experience --> Signals[Failures, feedback, outcomes]
  Signals --> Evals[Eval cases and regression checks]
  Evals --> Change[Reviewed behavior update]
  Change --> Agent[Sikaru-managed agent]
  Agent --> Run
```

Sikaru does not let production agents rewrite themselves without review. It turns real-world evidence into proposed updates, checks those updates against evals and regressions, and keeps humans in the release loop.

## Request flow

```mermaid theme={null}
sequenceDiagram
  participant Product as Product server
  participant SDK as Sikaru SDK
  participant Sikaru as Sikaru API
  participant Tool as Product tool

  Product->>SDK: sikaru.agent("support")
  Product->>SDK: agent.respond(messages, user, conversation)
  SDK->>Sikaru: start managed run
  Sikaru-->>SDK: stream run events
  SDK->>Tool: execute declared local tool
  Tool-->>SDK: result
  SDK->>Sikaru: submit tool result
  Sikaru-->>SDK: run.completed
  SDK->>Sikaru: commit Experience to /v1/trace-streams
  SDK-->>Product: output + run metadata
```

<Warning>
  Keep Sikaru API keys on application servers only. Do not ship them to browsers, mobile clients, or customer-visible automation sandboxes.
</Warning>

## Packages

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install sikaru-sdk
    ```

    ```python theme={null}
    from sikaru_sdk import Sikaru, tool
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install @sikaru/sdk
    ```

    ```ts theme={null}
    import { createSikaru, tool } from "@sikaru/sdk";
    ```
  </Tab>
</Tabs>

## Authentication

All SDK calls use a project-scoped API key.

```bash theme={null}
export SIKARU_API_KEY="sk_sikaru_..."
export SIKARU_PROJECT_ID="proj_..."
export SIKARU_API_URL="https://api.sikaru.ai"
```

The default API URL is `https://api.sikaru.ai`. You only need `SIKARU_API_URL` when targeting another environment.

<Info>
  Project keys are created after signing in to Sikaru and provisioning a project. The platform shows the key once during setup and supports rotation from project settings.
</Info>