Long-Running Tool Status Polling Prompt Template

This prompt is for agent developers who need to manage tool calls with unknown or variable completion times. Instead of blocking the agent loop, this prompt instructs the model to decide when to poll for status, how to interpret progress signals, when to escalate a stalled tool, and when to terminate the polling loop. Use this when your agent orchestrates long-running operations such as report generation, model training jobs, batch data processing, or any external API that returns a job ID and requires status checks. This prompt assumes you have a check_tool_status function available and that the agent operates in a loop where it can act on the polling decision.

Do not use this prompt for synchronous tool calls that return results within a single request cycle, or for streaming tools that push incremental results without polling. It is also inappropriate when the agent has no ability to store state across loop iterations, or when the tool's status endpoint does not provide structured progress information. If the long-running operation requires human approval at specific checkpoints, pair this prompt with a human-in-the-loop approval prompt rather than embedding approval logic directly into the polling loop. For tools that return partial results during execution, use the Streaming Tool Partial-Result Handling Prompt Template instead.

Before implementing this prompt, ensure you have defined the polling tool's contract: the input parameters (such as job ID), the expected status schema (including terminal states like completed, failed, cancelled), and any rate limits. The prompt works best when the agent has access to a check_tool_status function that returns structured JSON with at minimum a status field and optionally progress_percentage, error_message, and result fields. Wire this prompt into your agent loop so that the model's polling decision—whether to continue polling, escalate, or terminate—directly controls the next iteration's behavior.

This prompt template gives an agent explicit rules for managing tool calls with unknown completion times. Instead of assuming a synchronous response, the agent learns to inspect status payloads, respect polling intervals, detect stalls, and terminate loops cleanly. Replace the square-bracket placeholders with your specific tool names, status schemas, timeout values, and escalation policies before deploying.

textCopy
You are an agent that invokes long-running tools and polls their status until completion or timeout.

Available tools:
- [TOOL_NAME]: initiates the long-running operation. Accepts [INPUT_SCHEMA]. Returns a tracking ID.
- [STATUS_TOOL_NAME]: checks the status of a running operation. Accepts a tracking ID. Returns a JSON object matching [STATUS_SCHEMA].

When you call [TOOL_NAME], follow these rules:

1. POLLING INTERVAL
   - Start with an initial poll delay of [INITIAL_DELAY_SECONDS] seconds.
   - If the status is [PENDING_STATUS_VALUE], wait [POLL_INTERVAL_SECONDS] seconds before polling again.
   - If the tool returns a [RETRY_AFTER_HEADER], use that value as the next delay.
   - Never poll more frequently than [MIN_POLL_INTERVAL_SECONDS] seconds.

2. STATUS INTERPRETATION
   - [COMPLETED_STATUS_VALUE]: extract the result from [RESULT_FIELD_PATH] and present it to the user.
   - [FAILED_STATUS_VALUE]: extract the error from [ERROR_FIELD_PATH], classify it as retryable or fatal, and act according to [ERROR_CLASSIFICATION_RULES].
   - [PROGRESS_STATUS_VALUE]: report progress to the user using [PROGRESS_MESSAGE_TEMPLATE]. Continue polling.
   - [STALLED_STATUS_VALUE]: if the status hasn't changed for [STALL_THRESHOLD_SECONDS] seconds, escalate according to [ESCALATION_POLICY].

3. TERMINATION CONDITIONS
   - Stop polling after [MAX_POLL_ATTEMPTS] attempts and report a timeout to the user.
   - Stop polling if total elapsed time exceeds [MAX_TOTAL_SECONDS] seconds.
   - If the user sends an interrupt command ([INTERRUPT_COMMAND]), cancel the operation by calling [CANCEL_TOOL_NAME] and report the cancellation.

4. OUTPUT FORMAT
   - On completion, return the result in [OUTPUT_SCHEMA] format.
   - On failure, return an error object with { "error_type": "...", "message": "...", "retryable": true/false, "tracking_id": "..." }.
   - On timeout, return { "error_type": "timeout", "message": "Operation did not complete within [MAX_TOTAL_SECONDS]s", "tracking_id": "..." }.

5. RESOURCE CLEANUP
   - After completion, failure, timeout, or cancellation, call [CLEANUP_TOOL_NAME] if defined in [CLEANUP_POLICY].
   - Log the final state to [LOGGING_CHANNEL] with the tracking ID, total attempts, and total elapsed time.

To adapt this template, start by mapping your tool's real status values into the placeholder slots. If your tool returns RUNNING instead of PENDING, replace [PENDING_STATUS_VALUE] with "RUNNING". Define [STALL_THRESHOLD_SECONDS] based on your tool's observed behavior—set it to 3x the normal progress interval. For high-risk operations, wire [ESCALATION_POLICY] to a human approval queue rather than an automated retry. Test the prompt with status payloads that include unexpected fields, missing fields, and malformed JSON to verify the agent doesn't hallucinate completion. Before production, add an eval that asserts the agent stops polling after exactly [MAX_POLL_ATTEMPTS] attempts and never exceeds [MAX_TOTAL_SECONDS].

This prompt is not a standalone chat interaction; it is a decision module inside a polling loop. The agent invokes a long-running tool, receives an initial status handle or job ID, and then enters a loop where this prompt is called on each tick. The prompt's job is to interpret the raw tool status response, decide the next polling interval, detect completion or failure, and produce a structured decision object that the surrounding harness can act on. The harness owns the actual sleep/delay, the tool invocation, and the loop termination logic. The prompt owns the interpretation and recommendation.

The implementation harness should wrap this prompt in a function with a strict contract: input: { tool_name, job_id, status_payload, elapsed_time_ms, max_timeout_ms, previous_attempts } and output: { decision: 'poll' | 'complete' | 'escalate' | 'abandon', next_poll_ms: number | null, progress_summary: string, confidence: 0-1, escalation_reason: string | null }. Validate the output schema before acting on it. If the model returns decision: 'poll' but next_poll_ms is missing or zero, default to a configured floor (e.g., 2000ms). If decision: 'complete' but the status payload indicates an error state, flag a schema-semantic mismatch and re-prompt with the contradiction highlighted. Log every decision with the raw status payload, the model's reasoning, and the harness action taken. This trace is essential for debugging polling loops that spin forever or terminate early.

The harness must enforce hard loop boundaries that the prompt cannot override. Maintain a max_total_polls cap (e.g., 60 attempts) and a wall-clock max_timeout_ms. If either is exceeded, force decision: 'escalate' regardless of the model's output. Similarly, implement exponential backoff clamping: if the model requests next_poll_ms: 100 but the tool's documented rate limit is 1000ms, the harness should clamp to the safe minimum. The prompt can recommend aggressive polling, but the harness enforces the contract. For high-stakes workflows where a false completion signal could cause downstream data loss, insert a human review gate when confidence < 0.85 or when the status payload contains error codes the model has not seen before.

Wire this into an agent framework as a tool-call post-processor. After the agent invokes start_long_running_job, the framework spawns a polling coroutine that calls this prompt module on a timer. The coroutine yields structured status updates back to the agent's context so the agent can communicate progress to the user. When the polling loop terminates with decision: 'complete', return the final result to the agent. On escalate, surface the escalation_reason and the full polling trace to a human operator or a supervisor agent. On abandon, clean up any resources associated with the job ID and log the abandonment reason. Never let the polling loop block the agent's main turn loop; use async/await or background threads so the agent remains responsive to user interrupts and cancellation signals.