Skip to content

autonomous_agent_guide.md

Latest commit

 

History

History
138 lines (97 loc) · 5.39 KB

autonomous_agent_guide.md

File metadata and controls

138 lines (97 loc) · 5.39 KB

Autonomous Agent Guide for PlanExe

This guide is for AI agents (Claude, GPT, Codex, etc.) that consume PlanExe via MCP. It covers the end-to-end workflow for autonomous plan creation without human intervention.

When to use PlanExe

Use PlanExe when an agent needs to plan a multi-phase project with real-world constraints — the kind of thing that takes weeks to months. Examples:

  • Launching a product or service
  • Setting up infrastructure (factory, clinic, data center)
  • Organizational change (governance, team restructuring)
  • Policy implementation at scale

Do not use PlanExe for simple tasks (checklists, single-step operations, code generation). Use a normal LLM response for those.

Autonomous workflow

Step 1: Discover capabilities

Call: example_prompts

Read the returned examples to understand what a good prompt looks like. PlanExe prompts are flowing prose (~300-800 words), not structured markdown.

Step 2: Draft a strong prompt

Before calling plan_create, draft a prompt that covers:

Dimension What to include
Objective What the project achieves. Be specific.
Scope What's included and excluded. Geographic/temporal bounds.
Constraints Budget range, timeline, regulatory requirements, technical limits.
Stakeholders Who's involved — team, beneficiaries, regulators, funders.
Resources Available budget, team size, existing infrastructure.
Success criteria Measurable outcomes. How do you know the project succeeded?

Write as flowing prose. Weave specs, constraints, and targets naturally into sentences. Do not use markdown headers or bullet lists in the prompt itself.

Step 3: Select model profile (optional)

Call: model_profiles

Choose a profile based on quality/speed tradeoff:

  • baseline — Fast, good for most projects (~10-15 min)
  • premium — Higher quality, slower (~15-25 min)
  • frontier — Best quality, slowest

Step 4: Create the plan

Call: plan_create(prompt="...", model_profile="baseline")

Returns a plan_id (UUID). Store this — you'll need it for all subsequent calls.

Step 5: Monitor progress

Call: plan_status(plan_id="...")

Poll every 5 minutes. State transitions:

  • pending → Plan is queued
  • processing → Pipeline is running
  • completed → Report is ready
  • failed → Terminal error (use plan_resume or plan_retry)
  • stopped → User called plan_stop (use plan_resume to continue or plan_retry to restart)

Step 6: Handle failures

When plan_status returns state: "failed", check the error dict for failure diagnostics:

Field Meaning
error.failure_reason Category: generation_error, worker_error, inactivity_timeout, internal_error, version_mismatch
error.failed_step Pipeline step that was active when the failure occurred
error.message Human-readable error message
error.recoverable true → try plan_resume; false → use plan_retry

If recoverable is true, resume first (preserves progress):

Call: plan_resume(plan_id="...")  # Continue from where it stopped

If recoverable is false or resume fails, do a full restart:

Call: plan_retry(plan_id="...")   # Discard all progress, start fresh

If diagnostics are null (legacy plan), default to trying plan_resume first, then plan_retry.

Step 7: Retrieve output

Call: plan_file_info(plan_id="...", artifact="report")

The download_url points to the self-contained HTML report. The zip artifact contains all intermediary files (markdown, JSON, CSV).

Error handling for agents

Scenario Action
plan_status returns failed Check recoverable field: if true, call plan_resume (preserves progress); if false, call plan_retry. If diagnostics are null, try plan_resume first, then plan_retry.
plan_status stays pending > 5 min Worker may be down. Report to user.
plan_status timing.last_progress_at unchanged > 10 min Plan likely stalled. Call plan_stop, then plan_retry. Fall back to file updated_at timestamps if last_progress_at is null.
Lost plan_id Call plan_list to recover recent plans.
Invalid API key Error code INVALID_USER_API_KEY. Prompt user to check their key.

Agent self-planning pattern

An advanced pattern: use PlanExe to plan the agent's own work.

  1. Agent receives a complex task from the user
  2. Agent calls PlanExe to generate a strategic plan
  3. Agent reads the plan's WBS (work breakdown structure) from the zip
  4. Agent executes the plan step by step, tracking progress against the WBS

Key files in the zip for agent consumption:

  • wbs_level1.json — High-level work packages
  • wbs_level2.json — Detailed tasks within each package
  • wbs_level3.json — Sub-tasks with effort estimates
  • pre_project_assessment.json — Feasibility assessment
  • distill_assumptions_raw.json — Key assumptions to validate

Prompt writing tips for agents

  1. Be specific about geography — "Copenhagen, Denmark" not "a city"
  2. Include budget ranges — "EUR 500K-1M" not "reasonable budget"
  3. Set a timeline — "18-month implementation" not "as soon as possible"
  4. Name the team — "5-person core team with 3 contractors" not "a team"
  5. Define success — "500 active users within 6 months" not "good adoption"