> This page is also available as Markdown: append .md to its URL. The full index of Sikaru docs is at https://docs.sikaru.ai/llms.txt. Code examples use only operations from the public API reference at https://docs.sikaru.ai/api-reference.

# Core concepts

Sikaru separates the definition of an agent from the conversations and executions that use it. This lets you reuse one agent across users, change its behavior through releases, and inspect each task on its own.

## How the resources relate

```mermaid
flowchart LR
    Org["Organization"] --> Project["Project"]
    Project --> Agent["Agent"]
    Agent --> Release["Release"]
    Release --> Session["Execution session"]
    Session --> Run["Run"]
```

An **organization** owns one or more **projects**. A project holds **agents**. Each agent has immutable **releases**. An **execution session** pins one release and holds a conversation. Each piece of work in a session is a **run**.

## Resources and identities

| Resource          | What it represents                                                                                                        | What to keep                                  |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| Organization      | Your team's ownership and access boundary                                                                                 | Organization selected in the dashboard        |
| Project           | Agents and related resources accessed by a project key                                                                    | Project ID                                    |
| Agent             | A reusable managed identity and its active release                                                                        | Agent slug, such as `support`                 |
| Release           | An immutable version of agent behavior                                                                                    | Release ID returned by creation or inspection |
| Execution session | A conversation with retained context and a pinned release                                                                 | Session ID                                    |
| Run               | One execution of work, with status and events                                                                             | Run ID                                        |
| Input receipt     | The recorded admission and delivery of a session input                                                                    | Receipt ID and request idempotency key        |
| Artifact          | A file associated with the session                                                                                        | File ID and session ID                        |
| Trace             | Recorded execution evidence, stored as a [Harbor ATIF](/improve/trace-ingestion#trajectory-format-harbor-atif) trajectory | Trace ID and source identity                  |
| Changeset         | A proposed release change with review evidence                                                                            | Changeset ID                                  |

> **Note**
>
> Some API operations call the agent selector `harness_id`. In the quickstart, supply the active agent slug in that position. The **harness** is the execution engine behind the agent; you do not install that engine in your application.

## Project, tenant, and user

A project API key authorizes your application to use project resources. `tenant_id` and `user_id` identify the customer and end user whose work your application is submitting. They are application identifiers, not replacement credentials.

> **Warning**
>
> Derive `tenant_id` and `user_id` from your authenticated application session. Do not accept an arbitrary tenant or session ID from a browser and forward it without checking that the caller owns it. Keep project keys on your backend. See [Authentication](/get-started/authentication).

## Sessions contain ongoing work

For a one-off task, use `runs.start`. For a conversation, create an execution session and append turns. A follow-up in the same session can use the retained context from prior work. Starting another session creates a separate conversation.

During active work, an appended input normally steers the current execution at a safe boundary. Use `delivery_mode="queue"` to request a separate next turn. Inspect input receipts to learn where the service delivered the input; late steering may become a follow-up.

A session keeps its release when a new release becomes active. Start a new session to use the newly active definition. [Branching](/run/session-branching) creates a new conversation from an eligible completed snapshot; it does not reverse actions already taken.

## Acceptance, execution, and evidence

Treat these as separate observations:

| Observation   | What tells you                                                                      |
| ------------- | ----------------------------------------------------------------------------------- |
| **Admission** | The API returns an identifier or receipt for accepted work.                         |
| **Execution** | Run status and events show progress, waiting, completion, or failure.               |
| **Evidence**  | Retained trajectories and measured usage describe what is available for inspection. |
| **Quality**   | Evaluation results indicate how selected evidence performed against a rubric.       |

> **Tip**
>
> An accepted request is not a completed answer. A completed answer is not necessarily a passing evaluation. Missing measurements are unknown, not zero.

## Tools and execution environments

Managed execution is the default. The other options:

* **Local compute** lets admitted commands run on a machine you control while orchestration stays hosted.
* **Product-owned tools** let your backend perform an action and submit its result.
* **Managed connections** let Sikaru call tools from authorized application or remote MCP connections.

Tool access needs an actual capability and grant. Naming a tool in the prompt does not register or authorize it. See [Tools and connections](/build/tools-and-connections).

## Releases and improvement

Release review uses **draft**, **staging**, and **production**. Evaluate a candidate and inspect its evidence before promotion. Automatic improvement is optional, requires permission and configuration, and may consume additional compute. Enabling it does not guarantee that each run produces a new release.

## Next steps

#### [Run your first agent](/get-started/quickstart)

Create your first agent, submit a task, and read its result.

#### [Agents and releases](/build/agents-and-releases)

Manage releases and promote reviewed changes.

#### [Sessions and steering](/run/sessions-and-steering)

Continue conversations and steer active work.

#### [Authentication](/get-started/authentication)

Set up project keys and keep them on your backend.