Agent Presets & Modes

Run safe, named agents with zero config — or declare per-agent permissions in YAML / Markdown

from praisonaiagents import Agent

agent = Agent(name="preset-agent", instructions="You are a research assistant.")
agent.start("Apply the research preset and summarise this topic: AI agents.")

Built-in build, plan, and review agents run safely with one command — and you can declare your own per-agent permissions in YAML or Markdown.

The user runs a named preset; PraisonAI loads scoped permissions and the agent completes the task within that mode.

How It Works

Quick Start

1. Run a built-in preset (no files, no flags)

   # Read-only explorer — never modifies files
   praisonai run --agent plan "explore this repo"
   
   # Code reviewer — asks before running shell commands
   praisonai run --agent review "review the recent diff"
   
   # Full toolset — implements and modifies code
   praisonai run --agent build "add a /health endpoint"

   All three work immediately after installing praisonai. No YAML, no configuration.

2. Define your own agent with a mode

   Create .praisonai/agents/reviewer.md:

   ---
   name: reviewer
   model: gpt-4o-mini
   mode: read-only
   permission:
     shell:
       "git *": ask
       "*": deny
   ---
   You are a meticulous code reviewer. Read code and diffs and provide thorough review feedback. Do not modify files.

   Then run it:

   praisonai run --agent reviewer "review the last commit"

Built-in Presets

Three agents are shipped with the wrapper and work with zero configuration.

Choosing a Mode

Rule of thumb: Start with plan. Promote to review if the agent needs to run inspection commands (git log, grep). Use build only when the agent genuinely needs to modify files.

Defining Your Own Agent

Markdown frontmatter (recommended)

Create a .md file in .praisonai/agents/ (project scope) or ~/.praisonai/agents/ (user scope):

---
name: reviewer
model: gpt-4o-mini
mode: read-only
permission:
  shell:
    "git *": ask
    "*": deny
---
You are a meticulous code reviewer…

The mode: sets coarse defaults. The permission: block then overrides specific rules — here, shell: "git *": ask means git commands prompt the user while everything else is denied.

YAML equivalent

# .praisonai/agents/reviewer.yaml
name: reviewer
model: gpt-4o-mini
mode: read-only
permission:
  shell:
    "git *": ask
    "*": deny

Flat permission form

name: ci-runner
mode: plan
permission:
  read: allow
  edit: deny
  write: deny

Bare capability keys (read, edit) are normalised to read:, edit: automatically.

Nested per-capability form

name: git-assistant
permission:
  bash:
    "git log *": allow
    "git diff *": allow
    "*": deny
  read:
    "*": allow

Modes Reference

mode: is a coarse shorthand that applies a full rule set without writing individual permission lines.

build and full apply no rules (empty rule set — full toolset). plan is an alias of read-only.

Python String Params Fail Closed Too

When you pass a string to any of these Agent(...) params, PraisonAI validates it against a closed set of preset names — a typo raises ValueError at construction time with a “Did you mean …?” suggestion, so a misspelled preset never silently reverts to defaults:

Free-form params (knowledge=, guardrails=, skills=, runtime=, auth=) accept arbitrary strings and are deliberately not validated.

Case-insensitive, whitespace-tolerant, -/_ interchangeable — "read-only", "READ_ONLY", and " read_only " all resolve to the same preset. The same rule applies to the string form of Agent(autonomy=…), context=, output=, execution=, approval=, learn=, and self_improve=. See each feature page for the accepted preset names. Validation and resolution share one source of truth — canonical_preset_key() in praisonaiagents/config/parse_utils.py (PR #4186) — so every preset dict key must already be canonical; never add a non-canonical key like "full-auto".

from praisonaiagents import Agent

# Typo raises immediately — no silent fallback:
Agent(instructions="t", approval="read_onl")
# ValueError: Unknown preset 'read_onl' for parameter 'approval'.
#             Did you mean 'read_only'?

# To keep the default explicitly, pass it:
Agent(instructions="t", approval=False)         # explicit off
Agent(instructions="t", execution="balanced")   # explicit default

Permission Block Reference

The permission: block supports three actions:

Case insensitive: ALLOW, Allow, and allow are all valid.

Validation fails closed: an unknown action (e.g. permitt) raises ValueError at load time so a typo never silently produces an unrestricted agent.

Bare keys normalised: read → read:, bash → bash:.

Explicit permission: always wins over mode: defaults. If mode: review sets bash:*: ask but your permission: block sets bash: deny, the final rule is deny.

Precedence

Definition discovery (lowest → highest priority)

A project .praisonai/agents/plan.md completely replaces the built-in plan preset.

Permission resolution at invocation (lowest → highest priority)

CLI flags always win. This lets you use a shared team definition and override specific rules per invocation.

# Team definition has mode: review (bash:*: ask)
# CLI override: allow git commands without prompting
praisonai run --agent reviewer "review the diff" --allow 'bash:git *'

ask Keeps the Run Interactive

Any ask rule in the resolved permission set forces an interactive approval backend even when --approval is not passed. The agent pauses and prompts before each matching tool call.

Use ask for shell operations you want visibility into but don’t want to block entirely — the review preset does exactly this for bash.

If the run is non-interactive (CI, --no-tty), an unresolved ask falls back to deny.

Common Patterns

Read-only researcher

mode: plan
# or mode: read-only — they're identical

Git-only assistant

permission:
  bash:
    "git log *": allow
    "git diff *": allow
    "git show *": allow
    "*": deny
  read:
    "*": allow

Deny-by-default with selective allows

permission:
  read:
    "*/src/*": allow
  bash:
    "grep *": allow
  edit: deny
  write: deny
  execute: deny

Best Practices

Related