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