# AI instructions and templates

Maintain local or external AI instructions and use supported templates to include visitor and conversation information.

*Release 3.3 · admin, developer*

**Settings › AI › Features** · **Settings › AI › Skills** · **Settings › AI › Connections**

## What it is

Instructions tell an AI feature how to respond or assess a conversation. Supported instruction sections can use local text or a prompt from an external connection. Templates and macros can fill instructions with information available when the feature runs.

## Who uses it and why

Administrators maintain response guidance, metrics instructions and scoring prompts. Developers help with supported templates and website customisations.

## Where to find it

Open **Settings › AI › Features** and edit a feature. Depending on its type, headings include **Instructions**, **Summary Instructions**, **Translate Instructions** and **Metrics Instructions**. Reusable skill instructions are under **Settings › AI › Skills**.

Use the **Settings** role with the **AI** permission, or the **Developer** role. Powerfront manages **Settings › AI › Connections**. Ask Powerfront to add or change an external connection.

## How it works

For supported instruction sections, choose **Local** to maintain text in INSIDE. Choose **External** to select a **Connection** and **Prompt**, then a **Label** or **Version**. **External Instructions Preview** shows the retrieved prompt; **Fallback Instructions** keeps local text available.

Where the shared instruction selection applies, a configured website customisation gets the first opportunity to supply instructions. INSIDE then tries the external prompt, followed by local instructions or the feature's supplied default. Empty or failed external retrieval falls back. Execution diagnostics record the instruction source, owning feature or skill, instruction section and returned external version.

**Enable Template Engine** processes supported prompts before macros. **Enable Macros** enables substitutions using the available context and **AI Macro Fields**.

**Metrics Instructions** and **Scoring Prompt Override** also support templates containing available visitor and conversation information. Their template syntax is separate from the general AI template option. Leaving these fields empty uses the service defaults.

## Configure it

Choose the appropriate instruction section and source, then save the feature. For an external prompt, select either a label or a specific version. Setting one clears the other. The editor starts with **Cache** on and **TTL** at 300 seconds.

Keep useful **Fallback Instructions**. Review **External Instructions Preview** after changing a prompt selection. This preview shows external text, not a complete simulation of every runtime substitution.

Ask Powerfront for the supported syntax before adding custom template expressions. Check examples with missing visitor details and short conversations as well as complete records.

### Settings

| Setting | Where | Applies to | Default | Who can change it | What it does |
|---|---|---|---|---|---|
| Instructions | Settings › AI › Features | website | Not set: no local instruction override | Settings role, Developer role | Supplies local instructions for the selected feature; the exact instruction heading depends on its type. |
| Cache | Settings › AI › Features | website | On | Settings role, Developer role | Caches the selected external instructions. |
| TTL | Settings › AI › Features | website | 300 seconds (5 minutes) | Settings role, Developer role | Sets how long external instructions remain cached before refresh. |
| Enable Template Engine | Settings › AI › Features | website | Off | Settings role, Developer role | Processes supported AI prompts as templates before macro substitution. |
| Enable Macros | Settings › AI › Features | website | Off | Settings role, Developer role | Enables macro substitution in supported AI prompts. |
| Metrics Instructions | Settings › AI › Features | website | Not set; uses the service default | Settings role, Developer role | Supplies instructions for Metrics, with supported conversation and visitor templates. |
| Scoring Prompt Override | Settings › AI › Features | website | Not set; uses the service default | Settings role, Developer role | Replaces the default scoring prompt with supported template text. |
| Connection | Settings › AI › Features | website | Not set: no external prompt connection | Settings role, Developer role | Chooses the available external prompt connection for this instruction section. |
| Prompt | Settings › AI › Features | website | Not set: local or service instructions apply | Settings role, Developer role | Chooses the external prompt to retrieve. |
| Label | Settings › AI › Features | website | Not set: no external label override | Settings role, Developer role | Selects an external prompt label; choosing a label clears a pinned version. |
| Version | Settings › AI › Features | website | Latest: no pinned version | Settings role, Developer role | Pins an external prompt version instead of a label; Latest leaves the version unpinned. |

### Fields

| Field | Where | Required | What it is for |
|---|---|---|---|
| Key | Settings › AI › Features | No | Names a value in AI Macro Fields. |
| Value | Settings › AI › Features | No | Supplies the corresponding value in AI Macro Fields. |

### Permissions

| Permission | Lets you |
|---|---|
| Settings | Edit AI instructions when the AI Settings permission is allowed. |
| AI | Allows AI configuration under Settings Permissions. |
| Developer | Edit AI instructions and supported templates. |

## Limits and good to know

- Instruction sections can have separate sources. Changing summary instructions does not automatically change disposition instructions.
- Available template information depends on the request. A conversation may have no summary or complete visitor details.
- Do not assume all instruction fields use the same template syntax or external selection process.
- A syntax error can prevent a template from rendering. The consuming feature determines the fallback or failure behaviour.
- External instruction changes and INSIDE feature versions are separate histories.

## Depends on and works with

### This feature uses

- **Configured in** [Roles and permissions](ADM-008.md): Roles control access to instruction editing.
- **Configured in** [AI feature settings and change history](AI-001.md): Instructions are saved within versioned AI features.
- **Configured in** [Shared AI service connections](AIP-013.md): Powerfront configures the connections available for external instructions.
- **Works better with** [Reusable AI skills and instructions](AI-020.md): Skills can own their own instructions and external prompt selection.
- **Works better with** [External AI prompts and versions](AIP-014.md): Managed external prompts can replace local instructions with cached fallback.
- **Works better with** [Custom scripts managed by Powerfront](EXT-015.md): A website customisation can supply instructions before external or local instructions.

### Used by

- **Configures** [AI feature settings and change history](AI-001.md): Instruction sources and templates define what the feature is told to do.
- **Configures** [Autopilot for live chat](AI-003.md): Instructions guide the automated replies.
- **Configures** [Copilot reply suggestions](AI-006.md): Instructions and supported prompt sources guide suggestions.
- **Configures** [Fix and Re-Phrase for operator drafts](AI-007.md): Instructions guide the correction or rewrite.
- **Configures** [Ask AI beside a visitor conversation](AI-008.md): Instructions and prompt sources guide the assistant.
- **Configures** [AI conversation summaries](AI-009.md): Summary, disposition and sentiment instructions have separate supported sections.
- **Configures** [Chat Translate and language detection](AI-010.md): Supported translation and detection instruction sections can use prompt sources.
- **Configures** [AI spam checks for incoming conversations](AI-011.md): Instruction sources define the classification rules.
- **Configures** [Email Autopilot for tickets](AI-012.md): Prompt configuration supplies the decision instructions.
- **Configures** [Reusable AI skills and instructions](AI-020.md): Feature macros and templates affect skill instructions.
- **Configures** [Specialist sub-agents for AI tasks](AI-023.md): The specialist uses its target feature's instructions.
- **Configures** [AI conversation quality scoring](AI-029.md): Scoring instructions can use the configured prompt and template handling.
- **Configures** [AI resolution and first-contact metrics](AI-030.md): Metrics Instructions, shared defaults and prompt configuration define the evaluation rules.
- **Configures** [External AI prompts and versions](AIP-014.md): Prompt ownership and instructions sections determine where the external prompt is used.

## FAQ and troubleshooting

### Why are my local changes not affecting replies?

Check whether that instruction section uses **External**. A website customisation may also supply instructions first. Ask Powerfront to check that customisation if needed.

### Why did an external change take time to appear?

The prompt may be cached, pinned to a **Version**, or selected through a **Label** that points to a different version. Check those selections and **TTL**.

### Why is part of a template empty?

The request may lack the information used by the template. Allow for missing values and check the supported syntax.

### Where do I edit metrics and scoring instructions?

Edit the **Metrics** or **Conversation Scoring** feature under **Settings › AI › Features**. Use **Metrics Instructions** or **Scoring Prompt Override** respectively.