Browse documentation
Agents and deployments
Understand agent identity, immutable deployment versions, active state, and runtime callability.
View MarkdownAn agent is the stable product identity. A deployment is an immutable version of that agent's behavior and sandbox configuration.
Agent identity
| Field | Purpose |
|---|---|
| Name | Human-readable label |
| Slug | Stable Runtime API model identifier |
| Description | Purpose and operational context |
| Icon | Optional visual identifier |
| Active state | Controls whether the agent is callable |
| Active deployment | Immutable version used by new runs |
Deployment contents
A deployment pins:
- model and thinking-level defaults;
- system instructions;
- skills and prompt templates;
- hosted extensions and active tools;
- runtime environment metadata;
- managed image configuration;
- region and machine configuration;
- workspace upgrade policy;
- source and manifest integrity evidence.
Callability
An agent can appear in GET /api/v1/models when it is active and belongs to the API key's workspace.
Runtime execution also requires:
- a ready active deployment;
- valid provider configuration;
- runtime-ready billing;
- a key with the required scope.
Deployment lifecycle
queued
-> source uploaded
-> image build
-> runtime preparation
-> ready
-> active for future runsA failed deployment does not replace the active ready version.
Activating an older ready deployment is a rollback for future runs. Existing durable runs follow their own workspace upgrade policy before changing deployment.
Agent source
Agent behavior belongs in the project:
.pi/settings.json
.pi/SYSTEM.md
.pi/skills/**
.pi/prompts/**
.pi/extensions/**salambo.yaml controls deployment and runtime policy. It is not a second prompt or agent-behavior format.