# Agents



Create and update durable Agents by committing a manifest and running `ccp apply -f agent.yaml`. Keep the manifest as the source of truth.

`ccp agent` manages existing Agents on the managed-agents service. The server owns all validation — membership, model, tools, reasoning effort — so on a `400` the CLI passes the server's message through unrewritten; read it, it names valid values.

## Commands [#commands]

### `ccp agent list` [#ccp-agent-list]

```bash
ccp agent list [--org-id <org>]
```

Alias: `ccp agent ls`.

Lists the organization's agents: id, name, model, version, definition source, and last-updated time. Archived agents still appear, flagged with an `archived` marker.

### `ccp agent get` [#ccp-agent-get]

```bash
ccp agent get <agent_id> [--version <number>]
```

Prints the full definition: model, reasoning effort, tools, MCP declarations, metadata, version, definition source, timestamps, and system prompt. Pass `--version` to render a specific historical snapshot; omit it for the current definition. An archived agent's entry includes an `archived` marker with its timestamp. Unknown or inaccessible (cross-org) IDs return the server's `404` untouched — the CLI does not need an org context to run `get`, since the agent is addressed directly by ID.

### `ccp agent versions` [#ccp-agent-versions]

```bash
ccp agent versions <agent_id>
```

Lists every persisted definition snapshot, oldest first, with the latest marked `current`. Each entry shows the version, name, model, and update time. Like `get`, it needs no org context.

### `ccp agent delete` [#ccp-agent-delete]

```bash
ccp agent delete <agent_id> [--yes]
```

Permanently deletes an agent, every version, and its dependent runtime history. The command asks for confirmation first; pass `--yes` to skip the prompt. It works on any customer-owned agent: for an applied agent it also removes the manifest binding, so a later `ccp apply` of the same file creates a fresh agent id starting at version 1.

### `ccp apply` [#ccp-apply]

```bash
ccp apply -f <manifest.yaml> [--org-id <org>] [--dry-run]
```

Applies a declarative resource manifest — one `Agent` document and its optional Deployments and schedules, parsed locally as YAML or JSON and sent unchanged to the server, which owns validation and reconciliation. The server reports whether the Agent was `created`, `updated`, or left `unchanged`, along with its version and (on update) the changed fields, followed by a `created`, `updated`, `unchanged`, or `deleted` result for each of its Deployments and schedules. `--dry-run` runs the same validation and diff without persisting anything.

An Agent manifest looks like:

```yaml
apiVersion: agents.clusterbase.ai/v1
kind: Agent
metadata:
  name: release-notes
spec:
  name: Release Notes
  model: claude-sonnet-5
  system: |
    Write concise release notes.
  tools:
    - web_search
  mcp_servers: []
  reasoning_effort: low
  metadata:
    team: platform
  deployments:
    - name: weekday-build
      kickoff: Build and test the repository.
      environment:
        type: ephemeral
        template_id: workspace
        repos:
          - url: octocat/Hello-World
  schedules:
    - name: weekday-summary
      cron: "0 9 * * 1-5"
      timezone: America/Los_Angeles
      deployment: weekday-build
      enabled: true
```

`metadata.name` is the stable organization-scoped identity; changing `spec.name` only changes the display name. It must be a lowercase DNS label — lowercase letters, digits, and dashes, starting and ending with a letter or digit, 1–63 characters — so `release-notes` is valid while `Release Notes` and `release_notes` are rejected with a `400`. `spec.name` is free-form.

Applied agents remain runnable but must be edited by reapplying their manifest, not through imperative patch or archive calls. Additional YAML documents in the file are rejected locally, before any request is made; unknown fields are rejected by the server.

Deployment and schedule names are stable within the Agent. Omitting `spec.deployments` leaves existing applied Deployments untouched; a present list is authoritative, and `deployments: []` removes them only when no preserved schedule still references one. A Deployment supplies its kickoff and either an HTTP-only execution lane (no `environment`) or a fresh ephemeral VM with an optional validated template and repository list. Saved environment IDs, vaults, secret environment variables, and private scheduled-repository credentials are not accepted yet.

Omitting `spec.schedules` leaves existing applied schedules untouched; a present list is authoritative, and `schedules: []` explicitly removes all schedules managed by that Agent manifest. A schedule sets exactly one of `kickoff` (HTTP-only) or a manifest-local `deployment` name. Imperative and boot-managed resources are never pruned by `apply`.

### `ccp delete` [#ccp-delete]

```bash
ccp delete -f <manifest.yaml> [--org-id <org>] [--dry-run]
```

The declarative counterpart of `ccp agent delete`, addressed by manifest binding instead of id. `--dry-run` shows what would be deleted without persisting anything.

## Headless use [#headless-use]

`apply`, manifest `delete`, and `list` accept `--org-id` (or the `CCP_ORG_ID` environment variable) to skip the interactive organization picker. `get` and `versions` need no org context — they address the agent by ID directly. `agent delete` takes `--yes` to skip the confirmation prompt.

API errors include the server's `request_id`; quote it when reporting a failure.

## Endpoint [#endpoint]

Commands talk to the managed-agents service, resolved from `CCP_API_URL` (production is pinned to `https://agents.clusterbase.dev`; staging derives `managed-agents.<base>`). Set `CCP_AGENTS_API_URL` to override the derivation for bespoke clusters.