# Agents and deployments

Understand agent identity, immutable deployment versions, active state, and runtime callability.

An 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

```text
queued
  -> source uploaded
  -> image build
  -> runtime preparation
  -> ready
  -> active for future runs
```

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

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