Agent Task Progress Tracker Prompt Template

This prompt is designed for an agent orchestrator or a long-running autonomous agent that needs a machine-readable, structured snapshot of its current execution state. The primary job-to-be-done is to prevent context-window pollution, repeated work, and dropped subtasks by generating a canonical progress record. The ideal user is an AI engineer or technical decision maker building a multi-step agent harness where the orchestrator must make routing, retry, or escalation decisions based on a reliable state summary, not a raw, verbose chat log.

Use this prompt when an agent has more than three active or pending subtasks, when the context window is at risk of overflowing with stale tool outputs, or before a handoff to another agent or a human reviewer. It is most effective when the agent's execution loop can call it at defined checkpoints—such as after every N tool calls or when a subtask status changes. The prompt requires a structured input of the original plan, a list of subtasks with their current statuses, and any recent tool outputs or error messages. It is not a replacement for a durable state store or a transactional database; it is a stateless summarization step that should be followed by persisting the output to a state object.

Do not use this prompt for simple, single-turn tasks or for agents with only one active subtask, as the overhead of structured summarization outweighs the benefit. It is also inappropriate for real-time, sub-second control loops where the latency of an LLM call is unacceptable. In high-risk domains—such as healthcare, finance, or infrastructure automation—the output must be treated as an advisory summary, not a system of record. Always validate the generated progress record against the raw execution log and flag any discrepancies for human review before taking a destructive action based on the summary. The next step after reading this section is to copy the prompt template, adapt the placeholders to your agent's task schema, and wire it into your agent loop with a validation step that checks for stale or missing subtasks.

This template produces a machine-readable progress snapshot for an agent orchestrator. It accepts the original task plan, the execution log, and the current state, then outputs a structured record of completed, in-progress, and pending subtasks with status, timestamps, and blocker flags. Use this when your agent runtime needs a single source of truth for progress before deciding the next action, handing off to another agent, or presenting status to a human operator.

textCopy
You are an agent state tracker. Your job is to produce a structured progress record from the provided task plan and execution history.

## INPUTS
- Task Plan: [TASK_PLAN]
- Execution Log: [EXECUTION_LOG]
- Current State Snapshot: [CURRENT_STATE]
- Previously Reported Progress (if any): [PREVIOUS_PROGRESS]

## OUTPUT SCHEMA
Return a single JSON object with this structure:
{
  "progress_id": "string, unique identifier for this progress record",
  "generated_at": "ISO 8601 timestamp",
  "overall_status": "one of: not_started | in_progress | blocked | completed | failed",
  "completion_estimate": {
    "percentage": "number 0-100",
    "confidence": "low | medium | high",
    "rationale": "string, brief explanation of the estimate"
  },
  "subtasks": [
    {
      "subtask_id": "string, from the task plan",
      "description": "string, what this subtask does",
      "status": "pending | in_progress | completed | failed | blocked | skipped",
      "started_at": "ISO 8601 or null",
      "completed_at": "ISO 8601 or null",
      "attempts": "number, count of execution attempts",
      "last_error": "string or null, most recent error message",
      "output_summary": "string or null, brief summary of what was produced",
      "blocker_flag": "boolean, true if this subtask is actively blocking progress",
      "blocker_description": "string or null, what is blocked and why",
      "depends_on": ["list of subtask_ids this subtask waits for"],
      "evidence": ["list of specific log entries or state fields supporting this status"]
    }
  ],
  "blockers": [
    {
      "blocker_id": "string",
      "type": "tool_failure | missing_input | permission_denied | dependency_not_met | timeout | unknown",
      "affected_subtasks": ["list of subtask_ids"],
      "description": "string, what is blocked and why",
      "detected_at": "ISO 8601",
      "resolution_hint": "string, suggested next step to resolve"
    }
  ],
  "stale_state_warnings": [
    {
      "field": "string, which state field may be stale",
      "believed_value": "string, what the current state says",
      "conflicting_evidence": "string, what the log suggests instead",
      "severity": "low | medium | high"
    }
  ],
  "notes": "string, any additional observations about progress, risks, or anomalies"
}

## CONSTRAINTS
[CONSTRAINTS]

## INSTRUCTIONS
1. Compare the execution log against the task plan. Every subtask in the plan must appear in the output.
2. For each subtask, determine status by examining log entries, tool call results, and state changes.
3. If a subtask was attempted multiple times, record the attempt count and the last error.
4. Flag a subtask as blocked only when it cannot proceed due to an unresolved dependency, error, or missing input.
5. Detect stale state by comparing [CURRENT_STATE] against [EXECUTION_LOG]. If the log shows a state change not reflected in the current state snapshot, add a stale_state_warning.
6. If [PREVIOUS_PROGRESS] is provided, note any discrepancies between the previous record and what you observe now.
7. Set overall_status to "blocked" if any blocker exists, "failed" if a non-retryable failure occurred, "completed" if all subtasks are done, "in_progress" otherwise.
8. Do not invent evidence. Every status must be traceable to a specific log entry or state field.

Adapt this template by replacing the square-bracket placeholders with your runtime's actual data structures. [TASK_PLAN] should contain the full decomposed task with subtask IDs, descriptions, and dependency declarations. [EXECUTION_LOG] should be the raw sequence of tool calls, observations, and state mutations. [CURRENT_STATE] is the agent's internal state object at the moment of progress evaluation. [PREVIOUS_PROGRESS] is optional—include it when you want the model to detect drift from the last reported status. [CONSTRAINTS] is where you inject domain-specific rules, such as maximum attempt counts before escalation, required evidence standards, or output length limits. Test this prompt with both complete and partial execution logs to verify that the model correctly distinguishes between subtasks that haven't started, those that are genuinely in progress, and those that are silently stalled.

The Agent Task Progress Tracker prompt is designed to be called at regular intervals during agent execution, typically after each tool call or at the completion of a logical subtask. It should not be called on every token or minor action, as the overhead of generating a full progress record outweighs the benefit for granular steps. Instead, integrate it into your agent loop as a state-snapshot step that runs when the agent completes a unit of work, encounters a blocker, or approaches a context-window threshold. The prompt expects a structured input containing the original plan, the action log, and the current believed state, and it returns a machine-readable progress record that your orchestrator can parse and use to update its internal state representation.

Input Assembly and Validation: Before calling the model, construct the [CURRENT_STATE], [ACTION_LOG], and [ORIGINAL_PLAN] inputs from your agent's runtime data structures. Validate that the action log is not empty and that timestamps are monotonically increasing; a reversed or missing timestamp will cause the model to produce a progress record with incorrect ordering. The [CURRENT_STATE] should be a JSON object matching the schema your agent uses internally, with fields for completed_tasks, in_progress_tasks, pending_tasks, and any domain-specific state. If your agent uses a vector store or RAG for long-term memory, retrieve the most recent state snapshot and include it as [PREVIOUS_STATE_SNAPSHOT] to help the model detect drift. Output Validation: Parse the model's response as JSON and validate it against a strict schema before updating your agent's state. Required fields include completed (array of task objects with task_id, status, completed_at), in_progress (array with task_id, status, started_at, blocker_flag), pending (array with task_id, status, estimated_start), and state_summary (a string). Reject any response where blocker_flag is true but no blocker_description is provided. If validation fails, retry once with the validation error message appended to the prompt as [PREVIOUS_ERROR]; if the retry also fails, log the raw output and escalate to a human operator rather than silently proceeding with a corrupted state.

Model Choice and Latency Budget: This prompt works well with models that have strong JSON-mode support and instruction-following capability, such as Claude 3.5 Sonnet, GPT-4o, or Gemini 1.5 Pro. Avoid using smaller models (below ~70B parameters) for this task unless you have fine-tuned them specifically on your task schema, as they tend to drop required fields or hallucinate task IDs. Set a latency budget of 3-5 seconds for this call; if the model exceeds this, consider reducing the [ACTION_LOG] length by summarizing older entries before passing them in. Retry and Error Handling: Implement a retry policy with a maximum of two attempts. On the first validation failure, include the schema violation details in the retry prompt. On the second failure, do not retry further—log the failure, preserve the previous valid state snapshot, and trigger a state_corruption alert. The agent should pause execution until the state is manually reviewed or a fallback state-repair prompt is invoked. Logging and Observability: Log every progress-tracker call with the input hash, output hash, validation status, latency, and token usage. Store the raw prompt and response for at least 30 days to enable debugging of state corruption incidents. If your observability stack supports it, emit a metric for progress_tracker_validation_failure_rate and set an alert threshold at 5% over a rolling 10-minute window.

Integration with the Agent Loop: Wire the progress tracker into your agent's main execution loop as a post-action hook. After each tool call returns, append the result to the action log and check whether the number of unsummarized actions exceeds a threshold (e.g., 10 actions) or whether a blocker flag was raised. If either condition is true, call the progress tracker, update the agent's state from the validated output, and reset the unsummarized action counter. Do not call the progress tracker inside a retry loop for a single failed tool call; wait until the retry logic resolves or exhausts before taking a state snapshot. Human-in-the-Loop Integration: When the progress tracker returns a blocker_flag: true, route the blocker_description and affected task IDs to your human review queue. The agent should pause execution on the blocked task and continue with other independent pending tasks if the dependency graph allows it. If the blocker affects all remaining tasks, the agent should enter a waiting state and surface the full progress record to the operator. Avoid Common Pitfalls: Do not use the progress tracker as a replacement for structured logging; it is a state-summarization tool, not an audit trail. Do not call it before the agent has taken any actions, as an empty action log produces a vacuous progress record that wastes tokens. Finally, never update your agent's state from an unvalidated progress-tracker response—a hallucinated completed status on an actually-failed task will corrupt downstream execution and is difficult to detect without a full replay.