Streaming Agent Thought and Action Reassembly Prompt Template

This prompt is for agent observability engineers and platform developers who need to reconstruct a coherent, chronological execution trace from a raw, interleaved stream of agent events. The job-to-be-done is to transform a noisy sequence of thought, action, and observation blocks—often arriving out of order or with causal ambiguity—into a single, causally-linked timeline suitable for debugging, logging, or audit. The ideal user is building an agent debugging UI, an execution log store, or a compliance trail for autonomous agent runs. They already have a captured event stream and need a deterministic, model-assisted reassembly step to resolve ambiguities that pure regex or timestamp sorting cannot fix, such as linking a specific thought to the action it triggered.

You should use this prompt when the raw stream contains interleaved or overlapping event types and simple chronological sorting fails to establish causality. For example, an agent might emit a thought, then an action, then another thought before the first action's observation arrives. A pure timestamp sort would interleave these incorrectly, breaking the logical thought -> action -> observation loop. This prompt instructs the model to act as a trace reassembler: it groups events into causal units, resolves which thought preceded which action, and aligns delayed observations with their originating actions. It is particularly valuable when streaming traces from frameworks like LangGraph, AutoGen, or custom agent loops where the event bus does not guarantee causal ordering. Do not use this prompt for simple, single-turn function calls or for streams that are already perfectly ordered and annotated with explicit parent_event_id fields; in those cases, a deterministic script is cheaper and more reliable.

Before applying this prompt, ensure your input stream includes minimally sufficient fields for each event: a unique event ID, a timestamp, an event type (thought, action, observation), and the event payload. The prompt works best when the model is given explicit constraints to never invent missing causal links and to flag ambiguous segments for human review. After reassembly, the output trace should be validated by checking that every action has a preceding thought and that every observation is linked to exactly one action. For high-stakes debugging or compliance workflows, always log the raw stream alongside the reassembled trace and route any model-flagged ambiguities to a human for final resolution.

This prompt template is designed for agent observability engineers who need to reconstruct a coherent execution trace from fragmented, interleaved streaming events. The model receives raw event lines—each tagged with a type (THOUGHT, ACTION, OBSERVATION) and a timestamp—and produces a structured JSON trace that preserves causal links, deduplicates repeated content, and flags gaps or ordering anomalies. Use this template when your agent framework emits real-time debug streams that must be reassembled for logging, debugging, or compliance review.

textCopy
You are an agent trace reassembler. Your job is to convert a raw, interleaved stream of agent events into a chronological, causally-linked execution trace.

## INPUT
You will receive a list of event objects. Each event has:
- `type`: one of "THOUGHT", "ACTION", "OBSERVATION"
- `timestamp`: ISO-8601 string
- `content`: the raw text of the event
- `id`: a unique event identifier

Raw events:
[RAW_EVENTS]

## TASK
1. Sort all events by `timestamp` ascending.
2. Group events into logical "steps." A step begins with a THOUGHT, may contain an ACTION, and ends with an OBSERVATION. If an ACTION has no preceding THOUGHT, create a step with a `thought` field set to null. If an OBSERVATION has no preceding ACTION, attach it to the most recent open step.
3. For each step, produce an object with:
   - `step_number`: integer, starting at 1
   - `thought`: the THOUGHT content, or null
   - `action`: the ACTION content, or null
   - `observation`: the OBSERVATION content, or null
   - `event_ids`: array of event IDs included in this step
   - `timestamp_start`: earliest timestamp in the step
   - `timestamp_end`: latest timestamp in the step
4. Detect and flag anomalies:
   - `duplicate_events`: array of event IDs that appear more than once
   - `orphan_actions`: actions with no matching observation
   - `orphan_observations`: observations with no matching action
   - `timestamp_gaps`: steps where the gap from the previous step exceeds [GAP_THRESHOLD_SECONDS] seconds
5. If the stream appears truncated (e.g., an ACTION with no following OBSERVATION and the last event is not an OBSERVATION), set `truncated: true` and add a `truncation_note` string describing what is missing.

## OUTPUT SCHEMA
Return a single JSON object with this exact structure:
{
  "trace_id": "[TRACE_ID]",
  "assembled_at": "ISO-8601 timestamp of assembly",
  "total_events_received": integer,
  "total_steps_produced": integer,
  "truncated": boolean,
  "truncation_note": string or null,
  "anomalies": {
    "duplicate_events": [string],
    "orphan_actions": [string],
    "orphan_observations": [string],
    "timestamp_gaps": [
      {
        "after_step": integer,
        "gap_seconds": number
      }
    ]
  },
  "steps": [
    {
      "step_number": integer,
      "thought": string or null,
      "action": string or null,
      "observation": string or null,
      "event_ids": [string],
      "timestamp_start": "ISO-8601",
      "timestamp_end": "ISO-8601"
    }
  ]
}

## CONSTRAINTS
- Do not invent events. Only use the provided `[RAW_EVENTS]`.
- Preserve original `content` text verbatim inside each step field.
- If an event cannot be placed in any step, list its ID in a `unplaced_events` array inside `anomalies`.
- The output must be valid, parseable JSON with no trailing commas and no markdown fences.

To adapt this template, replace the square-bracket placeholders with your runtime values. [RAW_EVENTS] should be the serialized JSON array of event objects from your agent stream. [TRACE_ID] is a correlation ID from your observability system. [GAP_THRESHOLD_SECONDS] should be set to a value that makes sense for your agent's expected step latency—commonly 30 to 120 seconds. If your agent emits additional event types beyond the three standard ones, extend the step-grouping logic and the output schema to accommodate them. Before deploying, validate the assembled output against the schema using a JSON Schema validator in your application harness, and log any anomalies for later diagnosis. For high-risk agent workflows where trace correctness affects auditability, route traces with truncated: true or non-empty anomalies to a human review queue before they are written to your immutable log.

This prompt is designed to sit at the boundary between raw streaming agent events and your observability store. It receives a batch of interleaved thought, action, and observation chunks—typically collected from an SSE or WebSocket stream—and produces a chronologically ordered, causally linked execution trace. The harness should call this prompt only after a terminal event (e.g., agent_finish, tool_end, or a timeout) signals that the trace segment is complete. Calling it mid-stream on partial data will produce fragmented traces with dangling causal links.

Input assembly: Before invoking the prompt, collect all events from the agent run into a single array of objects, each with at minimum timestamp, type (one of thought, action, observation), and content. If your agent framework emits events with causal IDs (e.g., parent_id or in_response_to), include those fields. Sort the array by timestamp ascending before passing it as [EVENT_STREAM]. The prompt template expects this array serialized as a JSON string. Validation layer: After the model returns the reassembled trace, validate the output against a JSON Schema that enforces: (1) trace is a non-empty array, (2) each trace entry has step, timestamp, type, content, and optional caused_by referencing a prior step number, (3) step numbers are sequential integers starting from 1, and (4) caused_by values, if present, reference valid earlier step numbers. Reject traces that contain forward references or missing causal links.

Retry and repair logic: If validation fails, do not blindly retry with the same input. Classify the failure: for schema violations (missing fields, wrong types), invoke the prompt again with the validation error message appended to [CONSTRAINTS]. For causal link breakage (a caused_by pointing to a nonexistent step), truncate the event stream to the point of breakage and request a partial trace, then stitch manually. For duplicate or missing steps, re-sort the input events and retry once. Model choice: Use a model with strong JSON-following capability and a context window large enough to hold your maximum trace length plus the prompt. GPT-4o, Claude 3.5 Sonnet, and Gemini 1.5 Pro are suitable defaults. For very long traces (>100 events), consider chunking the event stream into overlapping windows of 50 events, reassembling each window, then running a secondary merge prompt to resolve boundary overlaps.

Logging and audit: Store the raw event stream, the prompt template version, the model response, and the validated trace as an immutable record. This triad is essential for debugging trace assembly failures and for demonstrating observability integrity to auditors. If the trace will be used for compliance or incident review, flag any trace where the model inserted a caused_by link that was not explicitly present in the raw event stream's causal IDs—this indicates the model inferred causality rather than deriving it from evidence. Human review gate: For high-risk agent runs (e.g., financial transactions, clinical decisions, production infrastructure changes), route assembled traces with validation warnings or inferred causal links to a human reviewer before the trace is committed to the permanent observability store. The reviewer should confirm that the reconstructed sequence matches their understanding of the agent's execution.