Skip to content

compozy agent create

Create a global or workspace-local agent definition

For people running agent work25 pages in this section

compozy agent create

Create a global or workspace-local agent definition

Synopsis

Create a global or workspace-local agent definition through a running CompozyOS daemon.

compozy agent create <name> [flags]

Examples

  compozy agent create pricing_strategist \
    --workspace ~/dev/ad8 \
    --provider claude \
    --model claude-sonnet-5 \
    --reasoning-effort max \
    --prompt "You own pricing strategy." \
    -o json

Options

      --acp-option stringArray       ACP select option default (repeatable: id=value_id)
      --acp-toggle stringArray       ACP boolean option default (repeatable: id=true|false)
      --category stringArray         Agent category path segment (repeatable)
      --clear-fallback-chain         Remove every fallback route from the agent definition
      --command string               Optional provider command override
      --deny-tool stringArray        Denied tool pattern (repeatable)
      --disable-skill stringArray    Disabled skill name (repeatable)
      --fallback-route stringArray   Fallback route provider=<p>,model=<m>[,reasoning_effort=<r>][,speed=<s>][,command=<c>] (repeatable, ordered; command must be last and takes the rest verbatim)
  -h, --help                         help for create
      --model string                 Optional provider model
      --permissions string           Optional permission mode
      --prompt string                Agent system prompt body
      --prompt-file string           Read the agent system prompt body from a file
      --provider string              Provider name for sessions using this agent
      --reasoning-effort string      Optional default reasoning effort
      --speed string                 Optional default runtime speed (normal or fast)
      --tool stringArray             Allowed tool pattern (repeatable)
      --toolset stringArray          Allowed toolset reference (repeatable)
      --workspace string             Override workspace binding (ID, name, or path)

Options inherited from parent commands

      --json             Emit JSON output
  -o, --output string    Output format: human, json, jsonl, or toon (default "human")
      --profile string   Act as a profile for this command

Output Formats

The root -o, --output flag accepts these values. A renderer is supported only when this command writes that result; jsonl is for commands that emit one JSON record per line.

FormatCommand result
humanInteractive terminal rendering
jsonMachine-readable JSON rendering
jsonlOne JSON record per line when supported
toonCompact agent-readable rendering

Example:

compozy agent create <name> -o json

On this page