Agent - PraisonAI

Manage custom agents discovered from .praisonai/agents/ (and .claude/agents/ / .agents/agents/ when present) — author them with create, then list and inspect with list / show. Distinct from praisonai agents (the multi-agent UI command).

Commands

praisonai agent create <name> [--describe TEXT] [--model TEXT] [--permission PRESET] [--global] [--force] [--yes]
praisonai agent list [--verbose]
praisonai agent show <name>

Command	Description
`create <name>`	Author a new custom agent definition (interactive or scriptable)
`list`	Show Name, Source (user/project), Model
`list --verbose`	Also Path and Role
`show <name>`	Agent details, system prompt, tools

create

Turn a one-line description into a permission-scoped .praisonai/agents/<name>.md — no editor round-trip.

Interactive

Run create with no flags and answer the four prompts (name, description, permission, model).

praisonai agent create

Agent name: reviewer
Describe what it does: Reviews diffs and suggests improvements
Permission [read-only/review/full] (full): read-only
Model (gpt-4o-mini):
✅ Created .praisonai/agents/reviewer.md
ℹ You can now run:
ℹ   praisonai run --agent reviewer "..."

Non-interactive / CI

Pass every value as a flag and add --yes to skip prompts — scriptable for CI.

praisonai agent create code-reviewer -d "Reviews diffs and suggests improvements" -p read-only -m gpt-4o-mini --yes

✅ Created .praisonai/agents/code-reviewer.md
ℹ You can now run:
ℹ   praisonai run --agent code-reviewer "..."

The resulting .praisonai/agents/code-reviewer.md:

---
model: gpt-4o-mini
role: Code Reviewer
goal: Reviews diffs and suggests improvements
mode: read-only
---
You are a careful code reviewer. Review the diff for correctness, ...

role is derived from the name (code-reviewer → Code Reviewer): _ and - become spaces, then title-cased. goal is your --describe text.

Global (user-wide)

Add --global to write to ~/.praisonai/agents/<name>.md instead of the project directory.

praisonai agent create researcher --global -d "Researches topics and summarises findings" --yes

If a same-named project agent already exists, a shadow warning fires — the project-local definition wins for run.

Flags

Flag	Short	Type	Default	Description
`NAME` (positional)	—	`str`	—	File stem for `.praisonai/agents/<name>.md`. Required — prompted for if missing in interactive mode. Path-unsafe names rejected.
`--describe`	`-d`	`str`	—	One-line description of what the agent should do. Fed to the system-prompt drafter and becomes `goal:` in frontmatter. Prompted interactively; defaults to `"A helpful <name> agent."` under `--yes` if omitted.
`--model`	`-m`	`str`	auto	Model to use. Defaults to the provider `init`/`run`/`setup` detect (silent, no persist). Interactive mode shows the detected default.
`--permission`	`-p`	`read-only \| review \| full`	`full`	Permission preset mapped to a `mode:` frontmatter value. Rejected if not a known preset (exit `1`).
`--global`	—	flag	`false`	Write to `~/.praisonai/agents/<name>.md` (user-global) instead of `<repo>/.praisonai/agents/<name>.md`.
`--force`	`-f`	flag	`false`	Overwrite an existing agent definition. Without it, exits `1` with “Agent already exists”.
`--yes`	`-y`	flag	`false`	Non-interactive: accept defaults, skip all prompts.

Permission presets

Presets reuse the same mode: grammar the runtime already understands — no parallel vocabulary.

Preset	`mode:` frontmatter	Grants
`read-only`	`read-only`	Reads allowed; edits, writes, and shell denied
`review`	`review`	Reads allowed; edits/writes denied; shell asks first
`full`	(omitted)	Full toolset — absence of `mode:` is the default

full deliberately omits mode: to keep files minimal. See Custom Agents & Commands → Scoping permissions for the full grammar.

Behaviour worth knowing

System prompt drafting is best-effort

The system prompt is drafted via the same Agent.run path as init --generate. On any failure, drafting degrades to an editable stub (“Describe how you should behave here”), prints a warning, and still writes the file with exit code 0. Edit the stub in place.

Path-safe names only

validate_agent_name rejects empty names, ., .., and any name containing / or \ — so every write stays inside the chosen agents directory. Invalid names exit 1 before any LLM call, so failure is cheap.

full omits mode:

--permission full writes no mode: key. Absence of mode: means the full toolset — the runtime’s default — so files stay minimal.

Shadow warning on --global

After writing, the CLI re-parses the exact file it wrote, then checks the precedence-resolved definition. If a higher-precedence (project-local) agent of the same name would win for run, it prints: “Another '' agent takes precedence for ‘run’: .” Rename this agent or remove the other to use it directly.

--force overwrites in place

Without --force, create refuses to touch an existing file and exits 1. With --force, it overwrites in place.

Names must be path-safe. ../foo, a/b, a\b, /abs, ., and .. are all rejected before any model call.

Prefer praisonai agent create for a single, focused agent; use praisonai init when you also want starter commands and tools next to it. See Custom Agents & Commands for the full definition format.

After a successful create, run the exact line the CLI prints:

praisonai run --agent code-reviewer "review the latest diff"

See praisonai run for the full runtime surface.

list

Show discovered agents with their source and model.

praisonai agent list
praisonai agent list --verbose

show

Inspect a single agent’s details, system prompt, and tools.

praisonai agent show researcher

No agents yet? Run praisonai agent create for the shortest path to a single custom agent, or praisonai init to scaffold a full starter project in .praisonai/.

Custom Agents & Commands

Define agents from Markdown

Run

Run with —agent

Init

Scaffold a starter project in one command

Agent Presets & Modes

The mode: shorthand behind permission presets

​Commands

​create

​Flags

​Permission presets

​Behaviour worth knowing

​list

​show

​Related

Custom Agents & Commands

Run

Init

Agent Presets & Modes

Commands

create

Flags

Permission presets

Behaviour worth knowing

list

show

Related