Skip to main content
Version: v5.2

Prompt templates

Overview#

A prompt template is a pre-defined prompt instruction which is defined once, then stored centrally in the AI Service, and is then reused across both MCP clients and agent workflows.

Types of prompt template#

There are two types of prompt template:

  • Fixed - A static prompt that runs as defined and requires no user input
  • Dynamic - A prompt which contains placeholder variables such as {{fileName}} or {{parentId}} whose values are filled at run-time. These arguments can be filled by the user via a MCP client or automatically by an agent from prior conversation context.

Why use prompt templates?#

The main advantages of using prompt templates are:

  • Ensures more consistent results from prompts

  • Facilitates structured agent hand-off

  • Provides a single source of truth for a prompt

Ensures more consistent results from prompts#

The main advantage of using a prompt template is that it will result in more consistent and accurate results being returned by the AI Service. With normal prompts, similar agents might produce different results due to slightly different prompt text being used.

Facilitates structured agent hand-off#

Previously, there had been no structured agent handoff and agents were free to pass raw text to each other. Now the resolver/router step fills placeholders from prior agent output and injects a fully resolved, deterministic SystemMessage. This improves accuracy across the entire team execution​

Provides a single source of truth for a prompt#

Using a prompt template avoids the situations were various prompts are scattered across a range of storage locations. Previously prompts were hard-coded per client or agent, with no single source of truth and no centralized management.

How to create a prompt template#

Using the API#

Javascript API#

You can create a prompt template using the Javascript API call IafAISvc.createPromptTemplates.

For more information, see the IafAISvc.createPromptTemplates page.

REST API#

You can also create a prompt template using the AI Service REST API endpoint below:

POST:/aisvc/ap/v1/prompttemplates

For more information, see the Prompt Templates API page.

Creating a fixed prompt template#

You can set up a fixed prompt template with no arguments. This will result in a prompt that works as is, and does not require user input.

Refer to the example below. 

[​ {​  "_name": "GetAllFiles”,​  "_userType": "get_all_files",​  "_description": "Lists all files and returns only JSON.",​  "_namespaces": [”ns"],​  "_template": "Use the `getFiles_IafFileSvc` tool to retrieve all files.   Fetch up to 50 files starting from offset 0.Return the result only in this structure:1. fileId- 2.fileName"​ }​]​

Creating a dynamic prompt template with arguments#

You can also easily set up a dynamic prompt template which requires user input before it can run.

Refer to the example below which defines an agent that searches for files within a given folder, and provides an argument called parentId which sets the ID of the folder in which to search. 

[​ {​ "_name": "GetAllFilesByParentId",​ "_userType": "get_all_files_parentid",​ "_description": "Lists files from a folder and returns only JSON.",​ "_namespaces": [”ns"],​ "_arguments": [ {​   "_name": "parentId",​   "_description": "Folder id to search in. Use root for top level.",​   "_required": true​ }],​ "_template": "Use the `getFiles_IafFileSvc` tool to retrieve files from the  folder specified by {{parentId}} .Search only within the provided folder.  Use "root" if the user wants files from the top-level folder.Return the  result only in this structure:1. fileId- 2.fileName"​ }​]​

AI Service REST API calls for prompt templates#

Refer to the list below for a summary of the REST API calls available for prompt templates.

MethodEndpointDescriptionAuth Required
POST/aisvc/ap/v1/prompttemplatesCreate prompt templates (array body)Yes
GET/aisvc/ap/v1/prompttemplatesList available prompt templates (paginated)Yes
GET/aisvc/ap/v1/prompttemplates/{id}List prompt templates by IDYes
PUT/aisvc/ap/v1/prompttemplates/{id}Update prompt template by IDYes
DELETE/aisvc/ap/v1/prompttemplates/{id}Delete prompt template by IDYes

Using prompt templates with MCP#

When using MCP, you can retrieve a list of all prompt templates which are available in the user's namespace in the MCP client. This allows prompts to be searched, selected and re-used as needed.

This process works as follows:

  1. The user opens the MCP enabled-client (for example, Claude).

  2. The user optains a list of the available prompt templates.

  3. The user selects a prompt amd the MCP client will run that prompt. When running a prompt, the MCP client will request any required inputs (prompt arguments) from the user to complete the prompt, and will then render the final completed prompt.

Using prompt templates with agents#

In agentic flow, you need to attach a prompt template to an agent using the agent's _promptTemplate field. When the team runs, the AI Service loads the prompt template from the database using the template’s _userType field and injects it into the agent before execution.​

This process works as follows:

  1. The team starts executing.
  2. The AI Service loads the agent definition.
  3. If _promptTemplate is present, the AI Service looks up the prompt template by using the _userType​ field.
  4. If the template has no arguments then the template text is injected directly as a SystemMessage​.
  5. If the template has arguments then the AI Service builds a PromptTemplate tool from the argument schema. The arguments are then filled by looking at prior converstations states. The rendered template is then injected as a SystemMessage.
  6. The agent runs with a clear, structured instruction​.

How to attach a prompt template to an agent#

A prompt template is attached at the agent level, not directly on the team.

See example below which attaches a prompt template "find_file_id_by_name" to an agent. This tells the agent which saved prompt template to use. The AI Service loads it at runtime and injects the resolved prompt before the agent executes. 

{​  "_name": "FindFileIdAgent",  "_description": "Find exactly one fileId by fileName",   "_background": "Follow the resolved prompt template strictly.",     "_userType": "find_file_id_agent",    "_type": "user_agent",    "_namespaces": ["building_1234"],   "_config": { "_provider": "openai", "_model": "gpt-4o", "_temperature": 0 },   "_tools": ["getFiles_IafFileSvc"],    "_promptTemplate": "find_file_id_by_name" }