Prompt Templates and Task Instructions

1. Purpose

Prompt templates are reusable configuration assets for assistants and agents. They should be managed like versioned executable configuration rather than copied as free-form text into application code.

2. Prompt Template Responsibilities

A prompt template can define:

• role/purpose;
• task-specific instructions;
• variable placeholders;
• grounding requirements;
• tool-use policy;
• output-format/schema requirements;
• safety and approval rules;
• response style;
• failure/insufficient-context behavior.

3. Example

id: summarize-business-document
version: 3
name: Summarize Business Document
type: assistant-task
variables:
  - document_context
  - user_question
instructions: |
  Use only the supplied document context for document-specific claims.
  Summarize the material relevant to the user's question.
  State when the supplied context does not contain the requested information.
grounding:
  required: true
  citation_mode: source-reference
output:
  format: markdown

4. Variables

Variables must be explicitly declared and validated.

Examples:

Variable	Purpose
user_query	Current user request
document_context	Retrieved source context
business_object	Current object context
site_context	Site/application context
tool_result	Previous tool result
language	Output language

Do not allow arbitrary user text to overwrite system-level policy sections.

5. Grounded Assistant Pattern

Document-based summarization and grounded Q&A use the following pattern:

flowchart TD
    Q(["User Query"]):::actor --> T["Assistant Task Template"]:::process
    T --> R["Retrieve allowed document context"]:::store
    R --> P["Prompt Assembly"]:::process
    P --> M[["Model"]]:::model
    M --> O(["Grounded Response + Source References"]):::output

    classDef actor fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1px,color:#0B1220
    classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
    classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
    classDef store fill:#CCFBF1,stroke:#0F766E,stroke-width:1px,color:#0B1220
    classDef output fill:#DCFCE7,stroke:#15803D,stroke-width:1px,color:#0B1220

The assistant should not invent document details when retrieval returns insufficient evidence.

6. Assistant vs Agent Prompting

Assistant Template

Usually emphasizes:

• task instructions;
• knowledge grounding;
• response constraints;
• user interaction.

Agent Template

Usually adds:

• goal definition;
• tool-use rules;
• stopping conditions;
• planning/iteration policy;
• approval requirements;
• failure/escalation behavior.

7. Prompt Registry

flowchart TD
    P[("Prompt Template")]:::store --> V["Version"]:::process
    P --> X["Variables"]:::process
    P --> O["Owner"]:::govern
    P --> S["Status"]:::process
    P --> A["Allowed Capability Types"]:::govern
    P --> M["Model Compatibility"]:::model
    P --> E["Evaluation Results"]:::output

    classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
    classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
    classDef store fill:#CCFBF1,stroke:#0F766E,stroke-width:1px,color:#0B1220
    classDef govern fill:#FFE4E6,stroke:#BE123C,stroke-width:1px,color:#0B1220
    classDef output fill:#DCFCE7,stroke:#15803D,stroke-width:1px,color:#0B1220

Recommended lifecycle:

stateDiagram-v2
    [*] --> Draft
    Draft --> Review
    Review --> Test
    Test --> Publish
    Publish --> Use
    Use --> Evaluate
    Evaluate --> Revise
    Revise --> Review
    Publish --> Retire
    Retire --> [*]

    class Draft,Revise process
    class Review,Test,Evaluate gate
    class Publish,Use output
    class Retire govern

    classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
    classDef gate fill:#FEF3C7,stroke:#B45309,stroke-width:1px,color:#0B1220
    classDef govern fill:#FFE4E6,stroke:#BE123C,stroke-width:1px,color:#0B1220
    classDef output fill:#DCFCE7,stroke:#15803D,stroke-width:1px,color:#0B1220

8. Versioning

Execution records should capture the exact prompt-template version used. Updating a template must not silently rewrite historical execution context.

Recommended identifiers:

prompt_template_id: summarize-business-document
prompt_template_version: 3

9. Output Schemas

Where downstream code consumes a response, use structured outputs rather than relying on prose parsing.

{
  "summary": "string",
  "key_points": ["string"],
  "source_refs": ["string"],
  "insufficient_context": false
}

10. Security

Templates must not contain:

• API keys;
• passwords;
• bearer tokens;
• private client secrets;
• hard-coded user credentials.

Retrieved context must still pass authorization checks before prompt assembly.

11. Evaluation

Prompt changes should be tested against a versioned evaluation set for:

• grounding;
• correctness;
• tool selection;
• instruction following;
• refusal/insufficient-data behavior;
• output-schema validity;
• latency/cost regression.