> 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.

# The agent lifecycle

This guide follows a user from signing in to receiving an answer. It then explains how later work can benefit from memory and evaluated improvements.

> **Note**
>
> Optional capabilities depend on your project's configuration and the deployed service version.

## The whole journey

```mermaid
flowchart TD
    Access["Sign in or authenticate your app"] --> Agent["Create or choose an agent"]
    Agent --> Session["Start a session"]
    Session --> Task["Send a task"]
    Task --> Context["Prepare context"]
    Context --> Work["Agent uses a model and allowed tools"]
    Work --> Result["Receive output and artifacts"]
    Result --> Followup["Send a follow-up"]
    Followup --> Context
    Result --> Learn["Evaluate possible improvements when enabled"]
    Learn --> Future["Improve later work"]
```

## 1. Get access

A person signs into the dashboard and chooses an organization and project. An application or CLI authenticates with an API key. The key's permissions decide which operations it can perform.

```mermaid
flowchart LR
    Person["Person"] --> Login["Dashboard sign-in"]
    Login --> Project["Authorized project access"]
    App["App, SDK or CLI"] --> Key["API key"]
    Key --> Project
```

> **Tip**
>
> For CLI access, configure `SIKARU_API_KEY`. A browser login does not automatically configure your terminal.

Your application also identifies the tenant and end user whose sessions it is managing.

Start with the [Quickstart](/get-started/quickstart), [SDKs](/sdks-and-cli/sdks), or [CLI](/sdks-and-cli/cli).

## 2. Create an agent

An **agent** is the managed identity you call. Its **release** is an immutable version of its definition. Supply instructions and definition content, including your authored skills, or select an existing registered release.

```mermaid
flowchart LR
    Definition["Instructions and definition content"] --> Validate["Validate and provision"]
    Validate --> Release["Agent release"]
    Release --> Agent["Managed agent"]
    Agent --> A["Session A"]
    Agent --> B["Session B"]
```

Test an agent before relying on it in production. Saving a definition and verifying useful behavior are different steps. See [Agents and releases](/build/agents-and-releases).

### One service, many agents and sessions

Sikaru manages the execution infrastructure. Creating an agent with a supported definition does not require you to build a worker image or configure a server. Compatible agents can share the same execution engine while their sessions keep separate conversation state and workspaces.

```mermaid
flowchart TD
    A["Agent A"] --> S1["Session A1"]
    A --> S2["Session A2"]
    B["Agent B"] --> S3["Session B1"]
    S1 --> Service["Sikaru manages compatible execution"]
    S2 --> Service
    S3 --> Service
    Service --> State["State and workspace remain scoped to each session"]
```

A release describes agent behavior; an environment describes where its operations run. Sharing an execution engine does not share one user's conversation or files with another user. Unsupported execution requirements must be made available by the service before the release can run.

Execution is managed by Sikaru by default. You can choose local execution on a connected machine you control. Sikaru selects the underlying managed sandbox.

## 3. Start a session

A **session** is a durable conversation. A **run** is an execution of work. A session can contain multiple turns over time.

```mermaid
flowchart TD
    Create["Create session with tenant and user identity"] --> Pin["Pin release and approved settings"]
    Pin --> First["First task"]
    First --> Run["Execute a run"]
    Run --> Answer["Answer and saved state"]
    Answer --> Next["Next turn uses the same session"]
    Next --> Run
```

A session keeps its release when a newer release becomes active. New sessions can use the new release. Model selection, reasoning controls and a final-output schema are available through the supported request fields and project configuration. A valid output shape does not by itself prove a correct answer.

Keep the returned session, run and input IDs. Use idempotency keys when retrying the same operation. See [Sessions and steering](/run/sessions-and-steering).

## 4. Prepare context and do the work

The agent assembles the information needed for its next model call. This can include instructions, recent conversation, a summary of older context, allowed tools and relevant scoped memory when enabled.

```mermaid
flowchart TD
    Instructions["Pinned instructions"] --> Context["Current model context"]
    Conversation["Conversation and current task"] --> Context
    Memory["Relevant preferences and memory"] --> Context
    Results["Tool results"] --> Context
    Context --> Model["Model proposes the next step"]
    Model --> Harness["Harness checks and coordinates it"]
    Harness --> Tools["Allowed tools or child agents"]
    Tools --> Results
    Model --> Answer["Final answer"]
```

The **harness** is the execution engine behind the agent. The model generates responses and proposed actions; the runtime applies policy and coordinates execution.

Long conversations may be summarized to fit the model's context budget. The working prompt is not the complete retained history.

A manager can delegate a focused task to a named child agent, provide the necessary context, steer it, and use its result. Delegation does not mean the child automatically receives the parent's entire conversation.

## 5. Choose where tools execute

```mermaid
flowchart TD
    Agent["Hosted agent orchestration"] --> Choice{"Approved execution destination"}
    Choice --> Managed["Managed workspace"]
    Choice --> Local["Your machine running sikaru compute serve"]
    Choice --> Product["Your application's tool broker"]
    Managed --> Result["Return result to the session"]
    Local --> Result
    Product --> Result
```

Local compute runs admitted operations on your machine while agent orchestration remains hosted. The native executor must be running to handle its requests. See [Local compute](/run/local-compute).

For product-owned tools, your application executes the action and submits its result. Approval alone does not execute it.

```mermaid
sequenceDiagram
    participant Agent as Sikaru
    participant App as Your application
    actor User
    participant Tool as External service
    Agent-->>App: Pending action
    App->>User: Request approval if needed
    User-->>App: Decision
    opt Approved
        App->>Tool: Execute once
        Tool-->>App: Result
        App->>Agent: Completed or failed receipt
        Agent->>Agent: Continue execution
    end
```

> **Warning**
>
> If you lose an acknowledgement after an external action, check whether it happened before retrying. See [Runs and tool requests](/run/runs-and-tool-requests).

## 6. Change direction or stop

```mermaid
flowchart TD
    Input["New input"] --> Choice{"Desired behavior"}
    Choice --> Steer["Steer current work at a safe boundary"]
    Choice --> Queue["Queue a separate next turn"]
    Stop["Explicit cancellation request"] --> Cancel["Stop active work as cancellation is processed"]
```

Steering is the default during active work. Input arriving too late is retained as a follow-up. Already executed actions are not undone by a new instruction.

> **Warning**
>
> Closing the CLI or reaching a client timeout does not cancel hosted work. Request cancellation explicitly. Recovery uses saved progress and receipts; it does not reverse external effects.

## 7. Collect results and continue

Outputs can include an answer, files and retained artifacts. Download them through authorized APIs. File deletion is explicit; historical filesystem versions have a separate retention lifecycle.

```mermaid
flowchart LR
    Run["Run finishes"] --> Answer["Answer"]
    Run --> Artifacts["Files and artifacts"]
    Run --> State["Saved session state"]
    State --> Continue["Continue this session"]
    State --> Branch["Branch from an eligible completed snapshot"]
```

A branch is a new conversation based on a recorded snapshot. It does not duplicate live pending actions or undo actions already taken. Shared user memory is not rewound when you branch.

See [Files and artifacts](/run/files-and-artifacts) and [Session branching](/run/session-branching).

## 8. Define success and automate follow-up

An objective describes a desired outcome and checks its evidence. Producing a final answer and satisfying an objective are separate events. A schedule admits future work; a webhook reports an event to your application.

```mermaid
flowchart TD
    Schedule["Scheduled or user-requested work"] --> Run["Execution"]
    Run --> Check["Check objective evidence"]
    Check -->|satisfied| Success["Objective succeeds"]
    Check -->|more work allowed| More["Continue within policy and budget"]
    More --> Run
    Run --> Events["Events and webhook notifications"]
```

Missing evidence is not success. Pausing an objective does not cancel an active run. See [Objectives](/build/objectives), [Schedules](/run/schedules), and [Webhooks](/run/webhooks).

## 9. Memory and improvement

When enabled, scoped memory can help later work reuse relevant preferences and knowledge. Memory is selected information, not a copy of every past conversation in every prompt.

```mermaid
flowchart TD
    Work["Recorded work and results"] --> Propose["Propose an improvement"]
    Propose --> Evaluate["Evaluate and check policy"]
    Evaluate -->|accepted scoped update| Memory["Updated memory for later context"]
    Evaluate -->|qualifying release change| Release["New immutable release"]
    Evaluate -->|not accepted| Keep["Keep current behavior"]
    Release --> NewSessions["Future sessions use the active release"]
```

The service evaluates changes before admitting them. An improvement to a reusable release does not replace the pinned release of an existing session. Private optimization details remain service-owned.

To opt in at startup, add `--auto-improve` to `sikaru runs start` or `sikaru execution-sessions create`. It is off by default and requires the appropriate permission and a configured learning policy. Eligible work is processed asynchronously; the flag does not guarantee that every run immediately produces a new release. See the [CLI guide](/sdks-and-cli/cli).

## A useful distinction

| What you see        | What it means                                      |
| ------------------- | -------------------------------------------------- |
| Request accepted    | Sikaru admitted work; it may not have started yet. |
| Waiting for a tool  | A result or approval is still needed.              |
| Run completed       | The execution produced its final output.           |
| Objective succeeded | The configured outcome check passed.               |
| Memory updated      | An admitted scoped update can help later context.  |
| New release active  | Future sessions can use the promoted definition.   |

## Next steps

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

Create an agent, send a task, and read its result.

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

Continue conversations and steer active work.

#### [Runs and tool requests](/run/runs-and-tool-requests)

Handle pending actions, approvals, and receipts.

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

Test, review, and promote releases.