Agents

ccp agents 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 agents list

ccp agents list [--org-id <org>]

Alias: ccp agents 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 agents get

ccp agents get <agent_id>

Prints the full definition: model, reasoning effort, tools, MCP declarations, metadata, version, definition source, timestamps, and system prompt. 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 agents create

ccp agents 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 apply

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

Applies a declarative resource manifest — the first version accepts exactly one Agent document, parsed locally as YAML or JSON and sent unchanged to the server, which owns validation and reconciliation. The server reports whether the resource was created, updated, or left unchanged, along with its version and (on update) the changed fields. --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

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.

Headless use

apply, list, and create accept --org-id (or the CCP_ORG_ID environment variable) to skip the interactive organization picker. get needs no org context — it addresses the agent by ID directly.

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.