Role Creation

An agent file (agent.yaml by default; role.yaml still works) defines your agent — its model, system prompt, tools, guardrails, and everything else. The unified initrunner new command provides multiple seed modes and an interactive refinement loop for creating roles. The web dashboard offers a complementary GUI-based flow.

Quick Comparison

Quick Start

# Generate from a description with interactive refinement
initrunner new "A code review assistant that reads git diffs"

# Start from a template, skip refinement
initrunner new --template rag --no-refine

# Blank template with a specific provider
initrunner new --blank --provider anthropic

# Load from a bundled example
initrunner new --from hello-world

# Load from an InitHub bundle (browse at hub.initrunner.ai)
initrunner new --from hub:owner/package

# No seed -- guided start menu in a terminal (since v2026.6.2)
initrunner new

# Build a role with no AI -- a deterministic structured form (since v2026.6.2)
initrunner new --offline

CLI Flags

Seed modes are mutually exclusive: specify at most one of DESCRIPTION, --from, --template, --blank, or --offline.

Seed Modes

Description (AI-Powered)

initrunner new "A knowledge assistant that searches company docs"

Sends the description plus a dynamic schema reference to the configured LLM. The schema reference is built by introspecting Pydantic models (build_schema_reference()) and the live tool registry (build_tool_summary()), so it always stays in sync with the code.

If the generated YAML has validation errors, the builder automatically retries once by sending the errors back to the LLM.

Reasoning-Aware Generation

When your description implies autonomous or planning behavior (e.g., "plans tasks", "works autonomously", "spawns sub-agents", "self-critiques"), the wizard automatically generates reasoning configuration with the appropriate strategy, autonomy settings, and cognitive tools (think, todo, spawn). The schema reference includes the full reasoning primitives spec, so the LLM can produce valid reasoning configurations without manual editing.

initrunner new "An autonomous research agent that plans tasks, spawns sub-agents, and self-critiques"

This generates a role with:

• reasoning: { pattern: todo_driven, auto_plan: true, reflection_rounds: 1 }
• think (with critique), todo, and spawn tools
• autonomy with appropriate guardrails

See Reasoning Primitives for the full guide on reasoning strategies and cognitive tools.

Provider Auto-Detection

When --provider is omitted, InitRunner checks for available API keys in the environment (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) and uses the first provider found. Falls back to openai.

Credential Preflight

Since v2026.6.2, before an AI-backed seed in the guided menu, the builder resolves the API key (from the credential vault and the environment) and prints the model it is about to use:

Using openai:gpt-5.4

If no key is configured and you are in an interactive terminal, it offers to enter a key inline, switch provider, or build offline, instead of failing with a 401 partway through generation. Switching provider re-resolves the model and any custom-endpoint preset. When stdin is not a TTY, the preflight is skipped and a missing key surfaces as the usual authentication error from the model call. The credential vault and resolver are covered in Security.

Example

initrunner new "A Python tutor that executes code examples and explains errors" \
  --provider anthropic \
  --output tutor-role.yaml \
  --no-refine

Template

initrunner new --template rag

Available templates: basic, rag, daemon, memory, ollama, api, telegram, discord.

Blank

initrunner new --blank

Produces a minimal valid role YAML with sensible defaults.

From Source

initrunner new --from ./existing-role.yaml   # local file
initrunner new --from hello-world            # bundled example
initrunner new --from hub:owner/package      # hub bundle

Resolution order for --from SOURCE:

1. Starts with hub: — fetches from InitHub (role YAML only)
2. Exists as a filesystem path — loads the local file
3. Otherwise — looks up as a bundled example name

For multi-file example/hub bundles, only the primary role YAML is loaded into the builder. Omitted sidecar files (skills, configs, etc.) are listed as a warning. Use initrunner examples copy <name> to get all files.

No Seed (Guided Menu)

initrunner new

Since v2026.6.2, running initrunner new with no seed in an interactive terminal shows a numbered start menu. Each option is annotated with whether it needs an API key:

How would you like to start?

  1. Describe it in natural language   (AI generates it)   (default)
  2. Start from a template             (no API key needed)
  3. Start from a bundled example      (no API key needed)
  4. Build it manually, no AI          (no API key needed)
  5. Import LangChain / PydanticAI / Agent Spec   (AI assists)

Option 1 (the default) runs the AI describe-then-refine flow. Options 2 through 4 need no API key. Option 4 jumps to the offline form.

When stdin is not a TTY (piped input, CI), the menu is skipped and the previous behavior applies: the LLM starts a conversation asking what kind of agent to build.

Offline (No API Key)

initrunner new --offline

Since v2026.6.2, the offline builder produces a valid role.yaml through a deterministic structured form with no LLM or network call. It walks you through:

• Agent name (validated against the kebab-case name pattern) and one-line description
• System prompt (with an option to open an editor for a longer prompt)
• Provider and model (confirm the detected provider or pick another)
• A tool multi-select, prompting for each tool's required config
• Feature toggles: long-term memory, document ingestion (RAG), and a cron trigger

Entered tool-field values are parsed through YAML, so numbers, booleans, and lists keep their types (100 becomes an integer, true a boolean, [a, b] a list). The assembled YAML flows into the same preview, refinement, and save path as any other seed. --offline requires an interactive terminal. This is also the fallback the credential preflight offers when no API key is configured.

First-Run Offline Path

Since v2026.6.2, running a bare initrunner in a terminal with no provider configured offers to build an agent offline, rather than only printing the setup hint. Accepting it runs the same offline form as initrunner new --offline, so you can get a working role.yaml before adding any API key.

Refinement Loop

After the initial seed, the builder shows a syntax-highlighted YAML panel with the agent name and validation status:

+-- code-reviewer -------------------- VALID --+
| name: code-reviewer                           |
| model: openai:gpt-5-mini                      |
| prompt: You review code for bugs and style.   |
| ...                                           |
+-----------------------------------------------+

Refine: describe a change, :help for commands, Enter to save, :quit to discard >

• Type plain text to ask the AI to refine the YAML (e.g. add memory and switch to claude)
• Press Enter (empty input) or type save to write the file
• Type quit or q to discard without saving
• Use --no-refine to skip the loop entirely

The refinement LLM has the full schema reference and tool registry, so it can add tools, triggers, memory, and other features by name. Since v2026.6.2, each AI refinement prints a one-line +adds -removes change summary after it runs.

Refinement Commands

Since v2026.6.2, input that starts with : (or a bare ? for help) runs a deterministic command instead of calling the LLM:

If no API key is configured, template, example, and offline roles can still be refined: the : commands (including :model) keep working, while plain-text AI refinement is replaced by a hint instead of failing with an authentication error.

Post-Creation Output

After saving, the builder shows contextual next-step hints based on the role's features:

Created agent.yaml

Next steps:
  initrunner ingest agent.yaml
  initrunner run agent.yaml -p 'hello'
  initrunner validate agent.yaml

Templates

Scaffold from a built-in template:

initrunner new --template basic
initrunner new --template rag --no-refine

Available templates: basic, rag, daemon, memory, ollama, api, telegram, discord.

# RAG agent with document search
initrunner new --template rag

# Background daemon that runs on a schedule
initrunner new --template daemon

# Agent with long-term memory
initrunner new --template memory

Scaffolding Tools and Skills

Scaffold tools and skills with dedicated commands:

# LLM-scaffold a custom tool from a description (since v2026.6.9)
initrunner tool new "<what the tool should do>"

# Or scaffold a static template module
initrunner new --template tool

# Scaffold a skill directory
initrunner skill new my-skill

The tool new scaffolder and the live -i --format rich authoring loop are covered in Custom Tools.

Copy an Example

Browse and copy community examples:

initrunner examples list                  # browse available examples
initrunner examples show hello-world      # preview the YAML
initrunner examples copy hello-world      # copy files to current directory

Other notable examples:

• See examples/policies/agent/ in the repository for agent-as-principal delegation and tool policy examples. Docs: Agent Policy Engine.

See Examples for the full catalog.

Dashboard — Create Role

The web dashboard at /agents/new runs a three-step flow: configure, editor, success.

Configure Step

Pick one of five seed modes:

• Describe: a natural language description the LLM turns into YAML
• Template: start from a named preset
• Blank: a minimal skeleton
• InitHub: browse hub.initrunner.ai and seed from a bundle
• Import: convert pasted LangChain or PydanticAI source

Fill in the agent name, provider, and model, then click the action button (Generate, Load from Hub, or Import, depending on the mode). Every mode except InitHub calls POST /api/builder/seed (SeedRequest); InitHub calls POST /api/builder/hub-seed. Both return the YAML, a plain-English explanation, and any validation issues.

Editor Step

1. Review and edit the generated YAML; edits are re-checked with POST /api/builder/validate and the issues are listed under the editor
2. Pick the directory and filename to write to
3. Click Save Agent, which calls POST /api/builder/save (SaveRequest)

A 409 puts the page into an overwrite prompt that re-sends the save with force: true.

API Endpoints

POST /api/builder/save returns 409 if a file with the same name already exists, unless force is set.

Dashboard — Edit Existing Roles

The agent detail page (/agents/{agent_id}) includes an editable YAML tab with Save and Reset buttons.

• Save calls POST /api/builder/save with the updated YAML content, force: true, and the agent's existing directory and filename
• Creates a .bak backup of the existing file before overwriting
• Validates the YAML against the flat AgentDocument schema before writing

Manual YAML

For full control, create an agent.yaml by hand. The file is the agent: a name, a prompt, the tools. See Configuration for the full schema reference. Old envelopes still load; convert them with initrunner doctor --fix. See Envelope Migration.

Minimum Viable Role

The smallest valid role needs a name, a system prompt, and a model:

name: my-agent
description: A helpful assistant
model: openai:gpt-5-mini
prompt: |
  You are a helpful assistant.

Adding Tools

Add a tools list. A bare name enables defaults; a mapping adds options:

tools:
  - filesystem:
      root_path: .
      read_only: true
  - shell:
      require_confirmation: true
      timeout_seconds: 30

Adding Memory

Add a memory section so the agent remembers across sessions:

memory:
  max_sessions: 10
  max_resume_messages: 20
  semantic:
    max_memories: 500

Run with --resume to pick up where you left off. See Memory for details.

Adding Ingestion / RAG

Add an ingest section to let the agent search your documents:

ingest:
  sources:
    - "./**/*.md"
  chunking:
    strategy: paragraph
    chunk_size: 512
    chunk_overlap: 50

Run initrunner ingest agent.yaml to index, then ask questions about your docs. See Ingestion for details.

Adding Triggers and Sinks

Triggers automate when the agent runs. Sinks control where output goes:

triggers:
  - type: cron
    schedule: "*/30 * * * *"
    prompt: Check for new items and summarize what changed.
  - type: file_watch
    paths: ["./src/**/*.py"]
sinks:
  - type: file
    path: ./reports/output.md
  - type: webhook
    url: "${SLACK_WEBHOOK_URL}"

See Triggers and Sinks for all options.

Adding Guardrails

Set resource limits to keep the agent safe:

guardrails:
  max_tokens_per_run: 10000
  max_tool_calls: 10
  timeout_seconds: 60
  max_request_limit: 10

See Guardrails for the full reference.

Programmatic Usage

The builder service layer (services/agent_builder.py) is UI-agnostic and can be used by CLI, API, and dashboard:

from initrunner.services.agent_builder import BuilderSession
from pathlib import Path

session = BuilderSession()

# Seed from description
turn = session.seed_description("a code review bot", "openai")

# Refine
turn = session.refine("add git and filesystem tools", "openai")

# Save
result = session.save(Path("role.yaml"))
print(result.next_steps)

Legacy one-shot generation is still available via generate_role() and generate_role_sync(), which now delegate to BuilderSession internally.

Validation

Check your YAML before running:

initrunner validate role.yaml

This parses the file and validates it against the flat AgentDocument schema. Errors are printed with field paths so you can fix them quickly.

Security Notes

• Name validation: name must match ^[a-z0-9][a-z0-9-]*[a-z0-9]$
• Directory restrictions: API writes are restricted to configured role directories; path traversal (..) is rejected
• Overwrite protection: CLI prompts before overwriting; POST /api/builder/save returns 409 if the file exists and force is not set; save_role_yaml_sync() creates a .bak backup before overwriting
• Validation before write: YAML is parsed and validated against the flat AgentDocument schema before being written to disk

Next Steps

• Configuration — Full YAML schema reference
• Tools — All available tools and their configuration
• Examples — Complete, runnable agents for common use cases
• Quickstart — Get your first agent running in under five minutes