> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/AllianceBioversityCIAT/alliance-risk-analysis-tool/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing AI Prompts

> Configure AI prompts, manage versions, add comments, and preview prompt outputs before deployment

# Managing AI Prompts

This guide covers how administrators configure and manage the AI prompts that power the risk assessment pipeline. Prompt management is restricted to users with **Admin** role.

<Note>
  **Admin Access Required**: All prompt management features require administrator privileges. Regular users cannot view or edit prompts.
</Note>

## Overview

AI prompts define how the system analyzes business documents and generates risk assessments. The platform uses prompts across 7 risk analysis sections:

* **Parser** - Extracts structured data from PDFs
* **Gap Detection** - Identifies missing information
* **Risk Analysis** - Evaluates risks for each category
* **Recommendations** - Generates actionable advice
* **Report Generation** - Creates final assessment reports
* **Quality Assurance** - Validates analysis outputs
* **Summarization** - Produces executive summaries

## Accessing Prompt Manager

<Steps>
  ### Navigate to Admin Area

  1. Click your profile menu in the top-right corner
  2. Select **"Admin Panel"** from the dropdown
  3. Click **"Prompt Manager"** in the admin navigation

  <Screenshot>
    **Admin Navigation**
    Show: Top navigation bar with user dropdown menu expanded, highlighting "Admin Panel" option. Side navigation showing "Prompt Manager" tab active.
  </Screenshot>

  ### Prompt List View

  The main prompt manager displays all prompts in a grid of cards. Each card shows:

  * **Name**: Prompt identifier
  * **Section**: Which analysis stage it belongs to
  * **Version**: Current version number (e.g., v3)
  * **Active/Inactive badge**: Deployment status
  * **Tags**: Categorization labels
  * **Last updated**: Timestamp of most recent edit

  <Screenshot>
    **Prompt Manager Grid**
    Show: Grid layout with 6-8 prompt cards, each displaying name, section badge, version, active status (green badge), tags, and edit/preview action buttons.
  </Screenshot>
</Steps>

## Filtering and Searching Prompts

Use the toolbar filters to find specific prompts:

### Available Filters

| Filter      | Options                                    | Purpose                             |
| ----------- | ------------------------------------------ | ----------------------------------- |
| **Section** | Parser, Gap Detection, Risk Analysis, etc. | Filter by analysis stage            |
| **Status**  | Active, Inactive, All                      | Show only deployed or draft prompts |
| **Tags**    | Multiple selection                         | Filter by category tags             |
| **Search**  | Text input                                 | Search by name or content           |
| **Route**   | API endpoint paths                         | Filter by routing configuration     |

<Screenshot>
  **Filter Toolbar**
  Show: Horizontal filter bar with Section dropdown (showing "Risk Analysis" selected), Status toggle ("Active" selected), Tags multi-select, and Search input field with magnifying glass icon.
</Screenshot>

## Creating a New Prompt

<Steps>
  ### Open Prompt Editor

  Click **"Create New Prompt"** in the top-right corner of the Prompt Manager.

  ### Enter Basic Information

  Fill in the required fields:

  **Required Fields**:

  * **Name**: Descriptive identifier (e.g., "Financial Risk Analysis - Detailed")
  * **Section**: Select from dropdown (determines when this prompt runs)
  * **System Prompt**: Base instructions for the AI model
  * **User Prompt Template**: Dynamic template with variable placeholders

  **Optional Fields**:

  * **Route**: API endpoint path (for custom routing)
  * **Sub-Section**: Additional categorization
  * **Tone**: Desired output style (e.g., "Professional and informative")
  * **Output Format**: Structure requirements (e.g., JSON schema)

  <Screenshot>
    **Prompt Editor - Basic Info**
    Show: Form with Name input filled "Market Risk Analyzer", Section dropdown showing "Risk Analysis" selected, and large textarea for System Prompt.
  </Screenshot>

  ### Configure System Prompt

  The system prompt sets the AI's role and base instructions.

  **Example**:

  ```text theme={null}
  You are an expert agricultural risk analyst specializing in 
  evaluating market risks for small and medium enterprises in 
  East Africa. Your analysis should be thorough, data-driven, 
  and actionable for non-technical stakeholders.
  ```

  **Best Practices**:

  * Define the AI's expertise area
  * Specify the target audience
  * Set expectations for output quality
  * Include relevant context about CGIAR's focus

  ### Build User Prompt Template

  The user prompt template is sent with each analysis request and supports variable injection.

  **Available Variables**:

  * `{{category_1}}`, `{{category_2}}`, etc. - Individual category names
  * `{{categories}}` - Comma-separated list of all categories
  * Custom variables defined in your integration

  **Example**:

  ```text theme={null}
  Analyze the following {{category_1}} risks for this agricultural 
  business. Consider:

  1. Historical market volatility
  2. Supply chain dependencies  
  3. Price fluctuation patterns
  4. Competition landscape

  Provide a risk score (0-100) and detailed evidence for your assessment.
  ```

  <Note>
    **Variable Replacement**: Variables are automatically replaced at runtime with actual category names and data from the current assessment.
  </Note>

  ### Add Categories and Tags

  Organize your prompt with metadata:

  **Categories**: Risk categories this prompt applies to

  * Click the category input field
  * Type a category name (e.g., "Market Risk", "Financial Risk")
  * Press Enter to add
  * Click × to remove

  **Tags**: Searchable labels for filtering

  * Enter tag text (converted to lowercase with hyphens)
  * Press Enter to add
  * Use tags like: `agriculture`, `sme`, `detailed-analysis`

  <Screenshot>
    **Categories and Tags**
    Show: Two sections - Categories showing badges for "Market Risk", "Financial Risk", "Operational Risk" each with × button. Tags section showing #agriculture #kenya #detailed tags with trash icons.
  </Screenshot>

  ### Set Tone and Output Format

  Optional fields for fine-tuning:

  **Tone**: Describe the desired writing style

  * Professional and informative
  * Conversational and accessible
  * Technical and detailed
  * Concise and action-oriented

  **Output Format**: Specify structure requirements

  ```json theme={null}
  {
    "riskScore": 0-100,
    "level": "LOW|MODERATE|HIGH|CRITICAL",
    "evidence": "string",
    "recommendations": ["string"]
  }
  ```

  ### Toggle Active Status

  Use the **Active/Inactive** switch at the bottom:

  * **Active** (green): Prompt is live and used in production
  * **Inactive** (gray): Prompt is saved but not deployed

  <Warning>
    **Single Active Prompt Rule**: Only one prompt per section should be active at a time. Activating a new prompt may automatically deactivate others in the same section.
  </Warning>

  ### Save the Prompt

  Click **"Create Prompt"** to save. The system:

  1. Creates version 1 (v1) of the prompt
  2. Stores a complete snapshot
  3. Redirects you to the prompt list
</Steps>

## Editing Existing Prompts

<Steps>
  ### Open Prompt for Editing

  From the prompt list:

  1. Click the **pencil icon** (✏️) on any prompt card, or
  2. Click the prompt card itself to open the editor

  ### Make Your Changes

  Update any field as needed. The editor pre-fills with current values.

  ### Preview Before Saving

  Click the **"Preview"** tab in the right sidebar to test your prompt with AI.

  <Screenshot>
    **Prompt Editor with Preview**
    Show: Split view - left side showing prompt form, right side showing Preview tab active with "Generate Preview" button and sample AI output below.
  </Screenshot>

  ### Save Changes

  Click **"Save Changes"** at the bottom. The system:

  1. Increments version number (v2, v3, etc.)
  2. Creates a new version snapshot
  3. Records change history with diff
  4. Preserves all previous versions

  <Note>
    **Version History**: Every save creates a new version. You can view and compare all historical versions from the History tab.
  </Note>
</Steps>

## Preview Prompt Outputs

The Preview panel lets you test prompts with real AI before deploying.

<Steps>
  ### Access Preview Panel

  In the prompt editor, click the **"Preview"** tab in the right sidebar.

  ### Generate AI Response

  1. Click **"Generate Preview"**
  2. The system creates an asynchronous AI job
  3. Progress indicator shows "Processing..."
  4. Results appear in 5-15 seconds

  ### Review Output

  The preview shows:

  * Full AI response based on your prompt
  * Generated with actual Bedrock model
  * Uses sample data for variable substitution

  <Screenshot>
    **AI Preview Output**
    Show: Preview panel with "Generate Preview" button at top, loading spinner, then sample AI output below showing risk analysis text with score and recommendations.
  </Screenshot>

  ### Iterate and Refine

  1. Review the AI output quality
  2. Switch back to prompt editor
  3. Adjust system prompt or user template
  4. Generate a new preview
  5. Repeat until satisfied

  <Warning>
    **Preview Limitations**: Previews use sample data, not real assessments. Final outputs may vary based on actual business documents.
  </Warning>
</Steps>

## Version Control and History

### Viewing Change History

Click the **"History"** tab in the prompt editor to see:

* **Version timeline**: Chronological list of all versions
* **Author**: Who made each change
* **Timestamp**: When the change was made
* **Change summary**: Auto-generated diff highlights

<Screenshot>
  **Change History Timeline**
  Show: Vertical timeline with 4-5 version entries, each showing version number (v5, v4, v3...), user avatar, timestamp, and expandable diff section.
</Screenshot>

### Comparing Versions

Expand any version to see:

**Field-level diffs**:

* Added content in green
* Removed content in red
* Unchanged fields collapsed

**Changed fields**:

* System prompt modifications
* User template updates
* Category/tag additions or removals
* Status changes (active ↔ inactive)

### Reverting to Previous Version

1. Navigate to the History tab
2. Find the desired version
3. Click **"View This Version"**
4. Review the historical prompt content
5. Copy content to current version if needed

<Note>
  **No Direct Rollback**: The system doesn't support automatic rollback. To restore an old version, copy its content into the current editor and save as a new version.
</Note>

## Commenting and Collaboration

### Adding Comments

Click the **"Comments"** tab in the prompt editor:

1. Type your comment in the text box
2. Mention specific concerns or suggestions
3. Click **"Add Comment"**
4. Comment appears with your email and timestamp

### Threaded Discussions

Comments support threading:

* Click **"Reply"** on any comment to create a thread
* Replies are indented under parent comments
* Track decision rationale and team discussions

<Screenshot>
  **Comments Panel**
  Show: Comments tab with 2-3 comments, one with a threaded reply. Each comment shows user avatar, email, timestamp, content, and "Reply" button.
</Screenshot>

### Use Cases for Comments

* **Review requests**: "@team please review this market risk prompt"
* **Change rationale**: "Updated tone to be less technical per user feedback"
* **TODO tracking**: "Need to add climate considerations to categories"
* **Version notes**: "v4: Fixed JSON output format to match API spec"

## Import and Export

### Exporting Prompts

1. Click **"Export"** in the top toolbar
2. Choose format:
   * **JSON**: Full prompt data with metadata
   * **CSV**: Spreadsheet format for bulk review
3. File downloads with timestamp: `prompts-2026-03-04.json`

Exported data includes:

* All prompt fields
* Current version only
* Active/inactive status
* Categories and tags

### Importing Prompts

1. Click **"Import"** in the toolbar
2. Upload a JSON file (exported from this system)
3. Select import mode:
   * **Create New**: Skip existing prompts, create new ones only
   * **Upsert**: Update existing prompts, create new ones
4. Review import summary
5. Confirm to proceed

<Warning>
  **Upsert Behavior**: In upsert mode, matching prompts (by ID) are updated and version-bumped. Use with caution in production.
</Warning>

## Toggling Active Status

Quickly enable or disable prompts:

### From the Prompt List

1. Locate the prompt card
2. Click the **toggle icon** (⚡)
3. Status badge updates immediately
4. Active prompts show green "Active" badge
5. Inactive prompts show gray "Inactive" badge

### From the Editor

Use the **Active/Inactive** switch at the bottom of the form.

### Best Practices

<AccordionGroup>
  <Accordion title="When to Deactivate">
    * Testing new prompts before production deployment
    * Temporarily disabling problematic prompts
    * Archiving outdated prompts without deleting
    * A/B testing different prompt versions
  </Accordion>

  <Accordion title="Single Active Prompt">
    Ensure only one prompt per section is active:

    * Prevents conflicting analysis logic
    * Maintains consistent user experience
    * System may auto-deactivate others when you activate a new one
  </Accordion>
</AccordionGroup>

## Best Practices

<Accordion title="Writing Effective Prompts">
  **System Prompts**:

  * Be specific about expertise domain
  * Define output expectations clearly
  * Include relevant context about CGIAR mission
  * Set appropriate tone for target audience

  **User Templates**:

  * Use clear, structured questions
  * Leverage variable injection for dynamic content
  * Specify output format requirements
  * Include evaluation criteria
</Accordion>

<Accordion title="Version Management">
  * Save frequently to create restore points
  * Use comments to document why changes were made
  * Test with Preview before activating
  * Keep descriptive prompt names
  * Review change history before major updates
</Accordion>

<Accordion title="Collaboration Workflow">
  1. Draft new prompt as Inactive
  2. Share prompt ID with team via comments
  3. Collect feedback in comment threads
  4. Iterate based on preview outputs
  5. Activate only after team approval
  6. Monitor assessment results post-deployment
</Accordion>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Preview Keeps Failing">
    * Check that both System and User prompts are filled
    * Verify variable syntax: `{{category_1}}` not `{category_1}`
    * Ensure no special characters in JSON output format
    * Try shorter prompts - very long prompts may timeout
    * Check admin console for error messages
  </Accordion>

  <Accordion title="Prompt Not Appearing in Analysis">
    * Verify the prompt is marked Active (green badge)
    * Check that Section matches the analysis stage
    * Ensure no other prompt in same section is active
    * Wait 1-2 minutes for cache refresh
    * Try creating a new test assessment
  </Accordion>

  <Accordion title="Can't Save Changes">
    * Check for validation errors in red text
    * Ensure required fields (Name, Section, System/User prompts) are filled
    * Verify you have admin permissions
    * Try refreshing the page if session expired
    * Check browser console for JavaScript errors
  </Accordion>
</AccordionGroup>

## Next Steps

* [Understand how prompts affect risk scoring →](/technical/ai-pipeline)
* [View API documentation for runtime prompt usage →](/api-reference/prompts)
* [Learn about model configuration and Bedrock integration →](/technical/bedrock-models)