Agents

ccp agent manages AI 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

ccp agent list

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 <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 <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 create

ccp agent create --name <name> --model <model> [options]

Creates an agent and prints its id. Options:

• --org-id <org> — organization to create the agent in.
• --system <text> or --system-file <path> — the system prompt, as inline text or read from a UTF-8 file. Mutually exclusive.
• --tool <name> — repeatable; attach a tool by name.
• --reasoning-effort <level> — reasoning effort level.
• --metadata <key=value> — repeatable; attach arbitrary key/value metadata.

MCP server declarations cannot be set from the CLI yet.

ccp agent delete

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

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

apply, manifest delete, list, and create 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

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.