Agent Action Reference Resolution Prompt

This prompt is for developers building coding agents, tool-use agents, or multi-step automation systems where the model must resolve a user's natural language reference to a specific previous action, its output, or a generated artifact. The core job-to-be-done is converting a follow-up instruction like 'run a linter on the file I just created' or 'debug its result' into a concrete, machine-readable target—a tool call argument, an artifact ID, or a file path—by grounding the reference in the agent's recent action history. The ideal user is an AI engineer or product developer integrating an LLM into an agent loop that maintains a structured action log. You need a well-formed action history with unique action IDs, timestamps, output summaries, and statuses (success, failure, in-progress) for this prompt to work. Without that structured context, the model has nothing to resolve against and will hallucinate references.

Do not use this prompt when the agent has no action history to reference, when the user's instruction is fully self-contained with explicit file paths or IDs, or when the referenced action failed or was rolled back and its artifacts are no longer available. In that last case, the prompt's failure mode check is designed to detect the invalid reference and return a status: 'invalid_reference' instead of guessing. This prompt is also inappropriate for simple single-turn tool calls where no prior context exists. If your system allows users to refer to entities outside the action log—such as files in a repository or knowledge base articles—you need a separate entity-linking step before this prompt, or you must extend the [CONTEXT] to include those external candidates. For high-stakes actions like database migrations, production deployments, or destructive file operations, always route the resolved action through a human approval step before execution, regardless of the model's confidence.

Before implementing this prompt, ensure your agent harness captures and persists a structured action log. Each entry should include at minimum an action_id, a human-readable description of what was done, the status, and any output_artifacts with their IDs or paths. This log becomes the [ACTION_HISTORY] input to the prompt. The prompt is designed to be stateless per call—it does not modify the log—so you can run it safely as a pre-processing step before tool execution. Start by testing it against a golden set of reference patterns: direct pronouns ('it', 'that file'), definite descriptions ('the config I just generated'), and ordinal references ('the second test'). Measure precision and recall on resolved action IDs before integrating it into your agent's critical path.

This prompt template is designed to be dropped into an agent loop immediately after a user turn that contains an ambiguous reference to a prior action. It forces the model to ground the reference in the actual execution history—tool call IDs, output artifacts, file paths, or error states—rather than guessing. The template uses square-bracket placeholders so you can wire it into your agent harness with the current session state, available tool schemas, and the specific reference that needs resolution.

textCopy
You are an action reference resolver for an agent that has already executed tool calls.
Your job is to resolve the user's reference to a previous action, output, or artifact
into a concrete, machine-readable identifier.

## RESOLUTION RULES
1. Map the user's reference to exactly one prior action from the execution history.
2. If the referenced action failed, was rolled back, or produced an error, you MUST
   flag it as UNRESOLVABLE with the failure reason.
3. If multiple candidates match, return the most recent one that satisfies all
   explicit constraints (temporal, type, status).
4. If no candidate matches, return UNRESOLVABLE with a suggested clarification question.
5. Never invent an action ID or artifact path that does not appear in the history.

## INPUTS
**User Reference:** [USER_REFERENCE]
**Execution History (most recent first):**
[EXECUTION_HISTORY]
**Current Working Context:** [WORKING_CONTEXT]

## OUTPUT SCHEMA
Return ONLY valid JSON matching this schema:
{
  "status": "RESOLVED" | "UNRESOLVABLE" | "MULTIPLE_CANDIDATES",
  "resolved_action_id": "string | null",
  "resolved_artifact": {
    "type": "tool_call_id" | "file_path" | "output_id" | "error_id",
    "value": "string | null"
  },
  "candidate_actions": ["string (action IDs)"],
  "failure_reason": "string | null (required if UNRESOLVABLE)",
  "clarification_question": "string | null (required if UNRESOLVABLE or MULTIPLE_CANDIDATES)",
  "confidence": 0.0-1.0
}

## CONSTRAINTS
[CONSTRAINTS]

## EXAMPLES
[EXAMPLES]

To adapt this template, replace each placeholder with live data from your agent runtime. [USER_REFERENCE] is the raw user utterance containing the reference, such as "run the linter on the file I just created" or "retry its output." [EXECUTION_HISTORY] should be a structured dump of recent tool calls with their IDs, arguments, outputs, status codes, and timestamps—ordered most recent first. [WORKING_CONTEXT] includes the current working directory, open files, or active session artifacts that the user might implicitly reference. [CONSTRAINTS] is where you inject domain-specific rules, such as "never resolve to a tool call that modified a production database" or "require human confirmation for any resolved action that deletes data." [EXAMPLES] should include 2-4 few-shot demonstrations covering a successful resolution, an unresolvable reference due to a failed action, and a multiple-candidate disambiguation case. Before deploying, validate that the output JSON parses correctly and that the resolved_action_id actually exists in the execution history you provided—this is the most common silent failure mode.

After integrating this prompt into your agent loop, add a post-resolution validator that checks whether the resolved action ID is still valid at execution time. Actions that completed successfully may have had their side effects overwritten by subsequent steps, and actions that failed may have left partial state. Wire the UNRESOLVABLE path to a clarification prompt that asks the user a single targeted question, not a generic "I didn't understand." For high-risk domains where the agent can modify files, run commands, or change configuration, route all MULTIPLE_CANDIDATES resolutions to a human approval queue before the agent acts on the resolved reference.

The Agent Action Reference Resolution Prompt is designed to sit between the user's natural-language instruction and the agent's tool execution layer. When a user says 'run the test I just wrote' or 'deploy its output', the application must resolve those references into concrete tool call arguments—file paths, artifact IDs, or command parameters—before the agent can act. This prompt is not a standalone chatbot; it is a resolution step in a pipeline. The typical wiring pattern is: receive user input, retrieve recent agent action history from the session store, assemble the prompt with the user utterance and action log, call the model, validate the resolved output, and then pass the resolved arguments to the downstream tool executor.

Input Assembly: The prompt requires two primary inputs: the current user utterance and a structured action history. The action history should be a JSON array of recent agent actions, each containing at minimum an action_id, action_type (e.g., file_create, tool_call, deploy), status (success, failed, rolled_back), timestamp, and a summary field describing what the action produced. Do not pass raw tool output logs; summarize them into concise, referenceable descriptions. For example, instead of dumping a full compiler output, store "Compiled main.go with no errors, produced binary at ./bin/app". This summarization step is critical—the model needs enough detail to disambiguate references but not so much that it overwhelms the context window or introduces noise.

Validation and Failure Modes: After the model returns a resolved reference, validate the output against the action history before executing any tool call. Check that the resolved action_id or artifact_id actually exists in the history and that its status is not failed or rolled_back. If the model resolves a reference to a failed action, the harness must intercept this and either prompt the user for clarification or return a structured error. Implement a retry loop with a maximum of two attempts: if the first resolution produces an invalid or missing reference, append the validation error to the prompt context and retry. If the second attempt also fails, escalate to the user with a clear message like 'I couldn't find the file you're referring to. The last file I created was ./src/utils_test.go. Did you mean that?' Never silently execute a tool call with an unresolved or guessed reference in production.

Model Choice and Latency: This prompt is a classification-plus-resolution task, not a generation task. Use a fast, instruction-tuned model such as GPT-4o-mini, Claude 3.5 Haiku, or Gemini 1.5 Flash. The prompt is designed to work with a single model call per resolution; avoid chaining multiple models for this step. If your agent already maintains a structured action log, the resolution step should add under 500ms of latency. Cache the action history summary in the session store and update it after each agent action to avoid recomputing summaries on every turn. For high-throughput coding agents, consider batching resolution requests when a user utterance contains multiple references, but always validate each resolved reference independently.

Logging and Observability: Log every resolution attempt with the user utterance, the action history snippet used, the model's raw output, the validated result, and whether the resolution succeeded or escalated. This trace is essential for debugging reference resolution failures in production. Common failure patterns to monitor include: the model resolving to an action that was rolled back, the model hallucinating an action ID that never existed, and the model defaulting to the most recent action when the user intended an earlier one. Set up an eval harness that runs a golden set of reference-resolution test cases—including ambiguous references, references to failed actions, and references across long action histories—against every prompt change before deployment.