Autonomous Mode

Autonomous mode lets an agent plan its own work, execute steps, adapt when things go wrong, and signal completion — all without human input. It's enabled by the spec.autonomy section and the -a CLI flag.

How It Works

An autonomous agent follows a plan-execute-adapt loop:

1. Plan — The agent calls update_plan to create a step-by-step checklist
2. Execute — It works through each step using its tools
3. Adapt — If a step fails, the agent modifies its plan (add retries, skip, investigate)
4. Finish — The agent calls finish_task with a status when all steps are complete

Two tools are auto-registered when autonomy is enabled:

Example: Deployment Checker

A complete autonomous agent that verifies deployments:

apiVersion: initrunner/v1
kind: Agent
metadata:
  name: deployment-checker
  description: Autonomous deployment verification agent
  tags: [devops, autonomous, deployment]
spec:
  role: |
    You are a deployment verification agent. When given one or more URLs to check,
    create a verification plan, execute each step, and produce a pass/fail report.

    Workflow:
    1. Use update_plan to create a checklist — one step per URL to verify
    2. Run curl -sSL -o /dev/null -w "%{http_code} %{time_total}s" for each URL
    3. Mark each step passed (2xx) or failed (anything else)
    4. If a check fails, adapt your plan — add a retry or investigation step
    5. When done, send a Slack summary with pass/fail results per URL
    6. Call finish_task with the overall status

    Keep each plan step concise. Mark steps completed/failed as you go.
  model:
    provider: openai
    name: gpt-4o-mini
    temperature: 0.0
  tools:
    - type: shell
      allowed_commands:
        - curl
      require_confirmation: false
      timeout_seconds: 30
    - type: slack
      webhook_url: "${SLACK_WEBHOOK_URL}"
      default_channel: "#deployments"
      username: Deploy Checker
      icon_emoji: ":white_check_mark:"
  autonomy:
    max_plan_steps: 6
    max_history_messages: 20
    iteration_delay_seconds: 1
    max_scheduled_per_run: 1
  guardrails:
    max_iterations: 6
    autonomous_token_budget: 30000
    max_tokens_per_run: 10000
    max_tool_calls: 15
    session_token_budget: 100000

initrunner run deployment-checker.yaml -a \
  -p "Verify https://api.example.com/health and https://api.example.com/ready"

Configuration

The spec.autonomy section controls planning behavior:

Guardrails

Autonomous agents need spending limits since they run without human oversight. These fields in spec.guardrails control resource usage:

When any limit is hit, the agent stops and reports its progress. See Guardrails for full enforcement behavior, daemon budgets, and all available limits.

Scheduling Tools

When autonomy is combined with daemon mode, two additional tools are auto-registered for scheduling follow-up tasks:

Both tools are limited by max_scheduled_per_run and max_scheduled_total from the autonomy config. Scheduled follow-ups always run in autonomous mode.

Note: Scheduled tasks are in-memory only and are lost on daemon restart.

autonomy:
  max_scheduled_per_run: 3
  max_scheduled_total: 50
  max_schedule_delay_seconds: 86400  # max 24 hours

Trigger Autonomous Flag

Each trigger type (cron, file_watch, webhook) supports an autonomous: true flag. When set, that trigger fires in autonomous mode — the agent plans, executes, and finishes without human input.

triggers:
  - type: cron
    schedule: "0 */6 * * *"
    prompt: "Check system health and remediate issues."
    autonomous: true   # this trigger runs in autonomous mode
  - type: file_watch
    paths: ["./reports"]
    extensions: [".csv"]
    prompt_template: "Process new report: {path}"
    autonomous: true

Scheduled follow-ups (via schedule_followup / schedule_followup_at) always run in autonomous mode regardless of this flag.

CLI Flags

# Enable autonomous mode
initrunner run role.yaml -a -p "Check all endpoints"

# Override max iterations
initrunner run role.yaml -a --max-iterations 3 -p "Quick check"

Reflection State

At each iteration, the agent's current state is captured as a ReflectionState and injected into the continuation prompt. This gives the agent awareness of what it has accomplished and what remains.

ReflectionState contains:

Each PlanStep has:

The reflection state is rendered as a summary and appended to the continuation_prompt at the start of each iteration, so the agent always has context about its progress.

Terminal Statuses

When an autonomous run ends, it produces a final_status indicating how it concluded:

completed and max_iterations are considered successful outcomes. All others indicate the run did not finish its intended work.

When to Use Autonomous Mode

Good fit:

• Verification tasks (deployment checks, health audits)
• Batch processing (process a list of items with per-item steps)
• Multi-step investigations (diagnose an issue, try fixes)
• Tasks with clear completion criteria

Consider alternatives:

• Recurring tasks → use Triggers with daemon mode instead
• Multi-agent workflows → use Compose for coordination
• Interactive exploration → use REPL mode (-i) for human-in-the-loop