# Agents and deployments API

Create, inspect, update, archive, and deploy agents.

Use these endpoints to manage stable agent identity, immutable deployments, and runtime history.

Agent availability is **active or inactive**. Set `isActive` when you create or
update an agent. Agent objects expose `is_active`. Active agents that satisfy
runtime prerequisites can accept new native runs.

## List agents

```http
GET /api/v1/agents
```

Required scope:

```text
agents:read
```

Archived agents return `404` and are not projected as inactive resources.

```bash
curl "$SALAMBO_BASE_URL/api/v1/agents?limit=20" \
  -H "Authorization: Bearer $SALAMBO_API_KEY"
```

Query parameters:

| Parameter | Type   | Notes                  |
| --------- | ------ | ---------------------- |
| `limit`   | number | 1-100, defaults to 50. |
| `after`   | UUID   | Pagination cursor.     |

Archived agents are excluded from the list.

## Create an agent

```http
POST /api/v1/agents
```

Required scope:

```text
agents:write
```

```bash
curl "$SALAMBO_BASE_URL/api/v1/agents" \
  -H "Authorization: Bearer $SALAMBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docs Demo Agent",
    "description": "Runs documentation smoke tests.",
    "isActive": false
  }'
```

Request body:

| Field            | Type           | Required | Notes                                                      |
| ---------------- | -------------- | -------- | ---------------------------------------------------------- |
| `name`           | string         | yes      | Required, max 100 characters.                              |
| `description`    | string or null | no       | Max 500 characters.                                        |
| `icon`           | string or null | no       | Max 10 characters.                                         |
| `commandContent` | string         | no       | Agent instructions. A default template is used if omitted. |
| `isActive`       | boolean        | no       | Active/inactive switch. Defaults to `false` when creating. |

Response objects include:

```json
{
  "id": "uuid",
  "public_id": "agt_01J...",
  "object": "agent",
  "name": "Docs Demo Agent",
  "slug": "docs-demo-agent",
  "description": "Runs documentation smoke tests.",
  "is_active": false
}
```

## Get an agent

```http
GET /api/v1/agents/{agentId}
```

Required scope:

```text
agents:read
```

## Update an agent

```http
PATCH /api/v1/agents/{agentId}
```

Required scope:

```text
agents:write
```

```bash
curl -X PATCH "$SALAMBO_BASE_URL/api/v1/agents/YOUR_AGENT_ID" \
  -H "Authorization: Bearer $SALAMBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated purpose.",
    "isActive": true
  }'
```

At least one update field is required.

Archived agents return `404` and cannot be updated or reactivated.

## Archive an agent

```http
DELETE /api/v1/agents/{agentId}
```

Required scope:

```text
agents:write
```

This archives the agent and sets `is_active` to `false`.

## Agent deployments

```http
GET /api/v1/agents/{agentId}/deployments
POST /api/v1/agents/{agentId}/deployments
```

Deployments are immutable versions. Source deployment normally uses the CLI, which creates the deployment, attaches the compiled manifest, uploads the source archive, and waits for the hosted deployment worker.

Deployment objects identify source provenance through `source.commit_sha` and sandbox-image provenance through `sandbox_image`. Provider-owned preparation identifiers are not part of the public contract.

## Deployment runtime configuration

Runtime policy is captured when the deployment is created. It is immutable with that deployment and is not stored as mutable agent state.

The create request includes:

```json
{
  "sandboxImageMode": "managed",
  "runtimeConfig": {
    "sandboxRegion": "eu",
    "egressPolicyMode": "restricted",
    "egressAllowlist": ["api.openai.com"],
    "workspaceUpgradePolicy": "automatic",
    "otlpEndpointOverride": null,
    "otelIncludeContentOverride": false
  }
}
```

Deployment responses expose the resolved immutable value as `runtime_config`. When `sandboxRegion` is omitted, the workspace default is resolved and stored during deployment creation.

There is no agent-level runtime endpoint. To change region, egress, workspace-upgrade, or telemetry policy, create a new deployment and activate it after it becomes ready.

## Activate a deployment version

The deployment worker automatically activates a newly completed source deployment. Use the explicit activation endpoint when you need to make any other ready deployment active:

```http
POST /api/v1/agents/{agentId}/deployments/{deploymentId}/activate
```

The selected deployment can be older or newer than the currently active
version, but it must already be ready. Activating an older version is a rollback
for future runs; existing durable runs are unchanged.

Use the [Runs API](/docs/api/runs) to start, continue, inspect, stream, cancel, or
delete agent work.