State-Based Next Action Recommendation Prompt

This prompt is designed for agent runtimes that must decide what to do next when multiple actions are possible. It takes a structured representation of the agent's current state, including completed tasks, in-progress work, pending subtasks, available tools, and known constraints, and returns a ranked list of candidate next actions with rationale, expected state changes, and risk flags. Use this prompt when your agent reaches a decision point and needs to select among competing actions rather than following a static execution plan. The ideal user is an agent developer or platform engineer building an autonomous or semi-autonomous agent loop where the next step is not predetermined by a script or DAG.

This is not a planning prompt for generating new subtasks from scratch. It assumes a set of candidate actions already exists and the job is prioritization and selection. The prompt works best when the state representation is machine-generated and structured, not free-text narrative. Provide the state as a JSON object with explicit fields for completed, in-progress, and pending items, each carrying status, timestamps, and blocker flags. The prompt expects tool definitions with clear contracts so it can reason about preconditions and side effects. If your agent lacks a reliable state snapshot or the candidate actions are vague, this prompt will produce plausible-sounding but incorrect rankings.

Do not use this prompt for generating new task decompositions, for open-ended brainstorming, or when the agent has only one available action. It is also unsuitable when the state representation is a long, unstructured chat history—the model will struggle to extract the structured signals needed for reliable prioritization. For high-risk domains such as healthcare, finance, or legal workflows, always route the ranked output through a human approval step before execution. The prompt includes risk flags for each candidate action, which your harness should use to gate autonomous execution.

Before deploying, test the prompt against a golden dataset of state snapshots paired with ground-truth priority rankings. Common failure modes include over-prioritizing recently mentioned tasks, ignoring blocker dependencies, and failing to account for tool availability constraints. The implementation harness section covers validation, retry logic, and human-in-the-loop integration. If your agent frequently produces incorrect rankings, revisit the quality and structure of your state representation before tuning the prompt itself.

This prompt is the core decision module for an agent that must select its next action based on a structured representation of its current state. It is designed to be dropped into an agent loop where the application layer feeds in the state snapshot, candidate actions, and constraints, then parses the JSON output to drive execution. The prompt forces the model to reason about priority, dependencies, and risk before acting, which reduces impulsive tool calls and out-of-order execution in autonomous workflows.

textCopy
You are an agent decision module. Your task is to analyze the current agent state and recommend the single highest-priority next action. You must also provide a ranked list of alternatives with rationale.

## CURRENT STATE
[STATE_JSON]

## CANDIDATE ACTIONS
For each candidate action, the following fields are provided:
- action_id: unique identifier
- description: what the action does
- preconditions: conditions that must be true before this action can execute
- estimated_cost: relative cost (low, medium, high) or token estimate
- dependencies: list of action_ids that must complete first

[CANDIDATE_ACTIONS]

## CONSTRAINTS
- [CONSTRAINT_1]
- [CONSTRAINT_2]
- [CONSTRAINT_3]

## OUTPUT REQUIREMENTS
Return a valid JSON object with this exact structure:
{
  "recommended_action": {
    "action_id": "string",
    "rationale": "string explaining why this action is the highest priority right now",
    "expected_state_change": {
      "fields_updated": ["field_name"],
      "new_values": { "field_name": "expected value or type" }
    },
    "risk_flags": ["flag1", "flag2"],
    "confidence": 0.0_to_1.0
  },
  "ranked_alternatives": [
    {
      "action_id": "string",
      "rank": 1,
      "rationale": "string",
      "why_not_recommended": "string explaining why this was not chosen as the top action"
    }
  ],
  "unexecutable_actions": [
    {
      "action_id": "string",
      "blocking_reason": "string explaining which precondition or dependency is not met"
    }
  ],
  "state_issues": [
    "any inconsistencies, missing fields, or stale data detected in the current state"
  ]
}

## RULES
1. Only recommend an action if all its preconditions are met and all dependencies are satisfied.
2. If no action is executable, set recommended_action to null and explain why in state_issues.
3. Prefer actions that unblock other high-value actions.
4. Flag any action that could cause irreversible side effects.
5. If confidence is below 0.7, include a specific uncertainty in the rationale.
6. Do not invent actions not present in the candidate list.
7. If the state contains contradictory information, flag it in state_issues and reduce confidence.

Adaptation guidance: Replace [STATE_JSON] with your application's serialized state object—this should include completed tasks, in-progress items, pending subtasks, resource availability, and any session metadata. Replace [CANDIDATE_ACTIONS] with the list of actions your agent can take, each annotated with preconditions and dependencies. The [CONSTRAINT] placeholders should capture hard rules like rate limits, budget caps, mandatory human approval gates, or domain-specific safety policies. If your model supports JSON mode or structured outputs, enable it and pass the output schema from the Expected Output Contract section to guarantee valid JSON. For high-risk domains, add a constraint requiring confidence above 0.9 before taking irreversible actions, and route low-confidence recommendations to a human review queue.

This prompt is a decision module, not a standalone application. It should be called at specific decision points within an agent execution loop—typically after a tool call completes, when a subtask finishes, or when the agent's internal state changes. The prompt expects a structured state snapshot as input and returns a ranked list of candidate actions. The calling runtime is responsible for assembling the state snapshot, invoking the prompt, validating the output, and executing the top-ranked action. Do not treat this prompt as a free-form reasoning step; it must be called with a consistent state schema and its output must be machine-validated before any action is taken.

Integration pattern: Wrap the prompt in a function with a strict input contract. The function signature should accept a state object matching the [CURRENT_STATE] schema and return a parsed action list. Implement a JSON schema validator for the output before the agent acts on any recommendation. If validation fails, retry once with the validation error injected into the [CONSTRAINTS] block. If the retry also fails, fall back to a deterministic priority rule (e.g., execute the oldest pending task) and log the failure for review. Model selection: Use a model with strong instruction-following and structured output capabilities. For high-throughput loops, consider a smaller, fine-tuned model if action patterns are stable. For high-stakes domains, route to a more capable model and add a human approval gate for actions flagged with risk_level: high. Logging: Record every invocation with the input state hash, the recommended actions, the selected action, and the validation result. This trace is essential for debugging priority inversions and stale-state recommendations.

Tool integration: The recommended actions should map directly to tool names or function calls available in the agent runtime. The prompt's [AVAILABLE_TOOLS] block must be kept in sync with the actual tool registry. If a recommended action references a tool that is unavailable or has changed signature, the runtime must reject the recommendation and re-invoke the prompt with the corrected tool list. Retry and escalation: If the same action is recommended repeatedly without progress, the runtime should detect the loop (e.g., three identical recommendations with no state change), invoke a loop-detection prompt, and escalate to a human operator if the loop persists. Human review gate: For domains where incorrect actions carry material risk, insert a human approval step before executing any action with risk_level: high or confidence < 0.8. The approval UI should display the current state summary, the recommended action with rationale, and the expected state change.

What to avoid: Do not call this prompt on every tick of the agent loop without a state change—it wastes tokens and increases latency. Do not skip output validation; malformed action recommendations will crash the agent or cause silent failures. Do not use this prompt as a substitute for a proper planning module; it selects the next action from a known task set, it does not decompose new goals. Wire it as a narrow, well-tested decision point, and build the surrounding harness to catch its failures before they become agent failures.