Custom Agents, Commands & Tools

from praisonaiagents import Agent

agent = Agent(name="custom-cmd-agent", instructions="Handle custom /commands in chat.")
agent.start("Register /summarise as a custom command that summarises the chat.")

praisonai init

my-project/
├── .claude/
│   ├── agents/reviewer.md      ← picked up
│   └── commands/deploy.md      ← picked up
└── .agents/
    └── agents/planner.md       ← picked up

praisonai run --agent reviewer "Review the diff on this branch"
praisonai run --command deploy staging

# researcher.md frontmatter → tools: [web_search]
# .praisonai/tools/greet.py  → greet.greet
praisonai run --agent researcher --tools github --allow-local-tools \
  "Greet Ada, then research WebAssembly 3.0"
# → final tool list: web_search, github, greet.greet

---
name: reviewer
mode: read-only
---
You are a meticulous code reviewer…

---
name: git-assistant
permission:
  bash:
    "git *": ask
    "*": deny
  read: allow
---
You are a git-aware assistant.

<!-- .praisonai/agents/researcher.md — delegatable teammate -->
---
model: gpt-4o-mini
role: Research Specialist
goal: Gather accurate, cited facts on a topic
mode: subagent
tools:
  - web_search
---
You are a meticulous researcher. Provide concise, cited findings.

# Agent-facing: ask the agent to author the command, then call it
praisonai run --agent build "Create .praisonai/commands/migrate.md that rewrites a component from one framework to another using $1 $2 $3."

<!-- .praisonai/commands/migrate.md -->
---
description: Rewrite a component from one framework to another
argument-hint: <component> <from> <to>
model: gpt-4o
tools: read_file, write_file, grep
---

Rewrite the `$1` component from `$2` to `$3`.

Full request: $ARGUMENTS

praisonai run --command migrate SearchBar React Vue
# → template resolves to:
#   Rewrite the `SearchBar` component from `React` to `Vue`.
#   Full request: SearchBar React Vue

<!-- .praisonai/commands/review-pr.md -->
---
description: Review a pull request against the current branch
argument-hint: <pr-number> [reviewer]
model: gpt-4o
allowed-tools:
  - github
  - grep
  - read_file
---

Review PR #$1 for correctness, security, and style. Assign secondary review to $2.

$ARGUMENTS

tools: github, grep, read_file

---
name: review
allow_shell: true
---
Review this diff:

!`git diff --stat`

# .praisonai/tools/greet.py
from praisonaiagents import tool

@tool
def hello(name: str) -> str:
    """Say hello to name."""
    return f"Hello, {name}!"

export PRAISONAI_ALLOW_LOCAL_TOOLS=true
praisonai run "Say hello to Alex"
# → agent auto-discovers greet.hello and calls it

# .praisonai/tools/pricing.py
from praisonaiagents import tool

def _cents(usd: float) -> int:            # skipped — no @tool
    return int(round(usd * 100))

@tool
def quote(item: str, usd: float) -> str:
    """Return a formatted price quote for item at usd dollars."""
    return f"{item}: ${_cents(usd) / 100:.2f}"

export PRAISONAI_ALLOW_LOCAL_TOOLS=true
praisonai run "Quote espresso at 3.50"
# → calls pricing.quote; _cents is never exposed to the LLM

praisonai agent create code-reviewer -d "Reviews diffs and suggests improvements" -p read-only --yes
# writes: .praisonai/agents/code-reviewer.md

praisonai init
# writes:
#   .praisonai/agents/assistant.md
#   .praisonai/commands/review.md
#   .praisonai/tools/example.py   ← new

---
name: researcher
model: gpt-4o
mode: subagent
---
You are an expert researcher.

> /mydeploy staging

from praisonai_code.cli.features.custom_definitions import (
    load_agent_from_name,
    interpolate_command_template,
    discover_project_tools,      # NEW — returns loaded tool callables
)

config = load_agent_from_name("researcher")
prompt = interpolate_command_template("summarise", "Long text...")
tools = discover_project_tools()  # [<greet.hello>, <pricing.quote>, ...]