Session Metadata Extraction Prompt for State Keys

This prompt is designed for platform engineers and infrastructure developers who need to automatically index and catalog agent sessions for later retrieval. The core job-to-be-done is extracting structured, queryable metadata—such as tenant IDs, session boundaries, and access scopes—from raw session transcripts or logs. This metadata serves as the primary keys and filter predicates in a state store, enabling efficient lookup, multi-tenancy isolation, and compliance auditing. The ideal user is someone integrating this prompt into a state management pipeline, not an end-user manually tagging sessions.

Use this prompt when you have a stream of completed or in-progress agent sessions and you need to populate a key-value store, relational database, or vector metadata index. It is appropriate when the session content contains explicit or inferable identifiers for the tenant, user, and workflow. Do not use this prompt for real-time, in-session state mutation; it is a post-hoc or inter-session indexing tool. It is also unsuitable for extracting the full conversational payload or for making authorization decisions—it only extracts metadata about the session, not the sensitive content within it. The prompt assumes the session data has already been redacted or is being processed in a secure environment.

Before wiring this into a production pipeline, ensure you have a defined schema for your state store keys. The prompt's output must be validated against uniqueness constraints (e.g., no duplicate session IDs) and queryability requirements (e.g., composite keys for tenant+date range queries). If the extraction fails for a critical field like tenant_id, the system should reject the metadata payload and route the session for human review, not silently write a malformed key. The next section provides the copy-ready template you will adapt to enforce these constraints.

This prompt template is designed to be dropped into a state management pipeline where raw agent session data—such as conversation logs, tool call traces, or blackboard postings—needs to be indexed for later retrieval. It instructs the model to extract a fixed set of metadata fields that serve as primary and secondary keys in a shared state store. The output is a single JSON object with tenant identifiers, session boundaries, access scopes, and a uniqueness-validated key. Use this template when you need every agent session to produce a queryable, conflict-free state record without manual tagging.

textCopy
You are a session metadata extraction agent. Your task is to analyze the provided agent session data and extract a structured metadata record for state store indexing.

## INPUT
[SESSION_DATA]

## OUTPUT_SCHEMA
Return a single JSON object with the following fields. Do not include any other text, markdown fences, or commentary.

{
  "tenant_id": "string (required) - the organization or account identifier extracted from the session context",
  "session_id": "string (required) - a unique identifier for this session, derived from the session start timestamp and a short hash of the initial user intent",
  "session_start_iso": "string (required) - ISO 8601 timestamp of session initiation",
  "session_end_iso": "string or null - ISO 8601 timestamp of session termination, or null if still active",
  "agent_roster": ["string"] - list of agent identifiers that participated in this session",
  "primary_intent": "string (required) - the top-level user goal classified from [INTENT_TAXONOMY]",
  "access_scope": "string (required) - one of: 'internal', 'customer', 'vendor', 'admin'",
  "state_key": "string (required) - a compound key formatted as '{tenant_id}:{session_id}' that must be unique across the state store",
  "tags": ["string"] - zero or more labels from [TAG_TAXONOMY] that apply to this session",
  "data_sensitivity": "string (required) - one of: 'public', 'internal', 'confidential', 'restricted'"
}

## CONSTRAINTS
- The `state_key` must be globally unique. If the derived key collides with an existing key in [EXISTING_KEYS], append a monotonically increasing suffix (e.g., '-2', '-3') until uniqueness is achieved.
- The `session_id` must be deterministic: given the same session data, always produce the same ID.
- If any required field cannot be extracted with confidence, set its value to null and add an entry to a top-level `"extraction_warnings": ["string"]` array explaining the gap.
- Do not hallucinate tenant IDs. If no tenant context is present, use 'unknown-tenant' and flag in warnings.
- The `access_scope` must be inferred from the user's role or authentication context, not from the content of the conversation.

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## EXISTING KEYS (for uniqueness check)
[EXISTING_KEYS]

## INTENT TAXONOMY
[INTENT_TAXONOMY]

## TAG TAXONOMY
[TAG_TAXONOMY]

## RISK_LEVEL
[RISK_LEVEL]

To adapt this template, replace each square-bracket placeholder with the actual data or configuration for your deployment. [SESSION_DATA] should contain the raw agent trace—this could be a full conversation transcript, a structured log of tool calls, or a blackboard event stream. [INTENT_TAXONOMY] and [TAG_TAXONOMY] should be flat lists of allowed values that match your downstream routing and analytics systems. [EXISTING_KEYS] is critical for uniqueness validation: provide the current set of active state keys so the model can detect and resolve collisions. If you are running this prompt in a high-throughput pipeline, consider pre-computing the session_id and state_key in application code and passing them as override fields to reduce model variance. For regulated environments, always log the raw extraction output alongside the session data and route any record with non-empty extraction_warnings to a human review queue before it lands in the state store.

The Session Metadata Extraction prompt is designed to sit at the boundary between an agent session and a shared state store. It transforms raw session context into a structured, queryable metadata object that downstream agents and orchestration logic use to locate the correct state partition. In practice, this prompt runs at session initialization and again whenever the session's scope changes—such as when a tenant boundary shifts, an access scope narrows, or a new agent joins the workflow. The output is not the state itself; it is the indexing metadata that tells the state store which partition, tenant, and session keys to read or write.

Wire this prompt into your application as a pre-fetch hook before any state store operation. The caller provides the raw session context—typically a JSON object containing the user identity, agent roster, active goals, and any existing session tags—and the prompt returns a metadata payload with tenant_id, session_id, access_scopes, session_boundaries (start and expected end), and a queryable_keys array. Validate the output before use: confirm that tenant_id is non-null and matches your tenant registry, that session_id is unique within the tenant scope, and that access_scopes contains only permitted values from your policy engine. If validation fails, retry once with the validation error injected into the prompt's [CONSTRAINTS] block, then escalate to a human operator if the second attempt also fails. Log every extraction attempt—including the raw session context hash, the extracted metadata, validation results, and the model version—so that state store lookup failures can be traced back to extraction errors.

Choose a model with strong JSON schema adherence for this task. The extraction is deterministic in structure but requires reasoning about tenant boundaries and scope inference from messy session data, so prefer a capable instruction-following model (e.g., Claude 3.5 Sonnet or GPT-4o) over a smaller, faster model unless you have fine-tuned it on your exact metadata schema. Set temperature=0 to minimize variance in key generation. If your state store uses a strict schema, provide the exact JSON Schema in the [OUTPUT_SCHEMA] placeholder and add a post-extraction schema validator (such as jsonschema in Python) as a hard gate before any state store call. For high-throughput systems, cache the extraction result keyed by a hash of the session context so that repeated lookups within the same session do not re-invoke the model.

The most common production failure mode is non-unique session IDs when multiple sessions share similar context. Mitigate this by appending a short random suffix or a timestamp to the extracted session_id in your application code, rather than relying on the model to guarantee uniqueness. A secondary failure mode is scope creep: the model infers broader access scopes than the session actually warrants. Defend against this by intersecting the extracted access_scopes with a hard-coded allowlist from your policy engine before any state store operation. Never pass extracted scopes directly to the store without this intersection check. If your system handles regulated data, require human approval on any extraction where the inferred scopes differ from the previous session's scopes by more than a configurable threshold.