Prompts

This reference describes the FoundationaLLM prompt resource and how to manage prompts with the Management API.

Overview

A prompt resource holds the text instructions used to build completion requests. Agents and tools reference prompts by role, for example:

The agent's main workflow prompt (main_prompt role) defines the agent's persona and instructional guardrails.
Workflow prompts with the router_prompt, files_prompt, escalation_prompt, and final_prompt roles guide tool selection, file use, tool escalation, and the final answer.
Tool prompts (for example, main_prompt and router_prompt on a tool) describe a tool to the workflow or instruct the tool's internal logic.

Prompts are resources of the FoundationaLLM.Prompt resource provider (prompts resource type). In the Management Portal, manage them under Agents > Prompts. The agent editor also creates or updates the agent's main workflow prompt when you save the agent. For step-by-step instructions, see Managing Prompts.

Prompt Structure

{
  "type": "multipart",
  "name": "my-agent",
  "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts/my-agent",
  "display_name": null,
  "description": "System prompt for the my-agent agent",
  "category": "Workflow",
  "cost_center": "",
  "prefix": "You are a helpful assistant named Khalil. Provide concise answers that are polite and professional.",
  "suffix": ""
}

Property	Description
`type`	The prompt type. Must be `multipart`, which is the only prompt type the resource provider accepts. `type` must be the first property in the request body.
`name`	The prompt name. Shown as Prompt name in the editor.
`object_id`	The object ID of the prompt. You can omit it when creating a prompt; the Management API populates it.
`display_name`	Optional display name.
`description`	A description of the purpose of the prompt. Shown as Description in the editor.
`category`	`Workflow`, `Tool`, `DataPipeline`, or `Agent`. The editor offers Agent Workflow (`Workflow`), Agent Tool (`Tool`), and Data Pipeline (`DataPipeline`).
`cost_center`	Optional cost center used for chargeback.
`prefix`	The main prompt text. Shown as Prompt Prefix in the editor.
`suffix`	Optional text appended after the prefix. The Management Portal prompt editor does not edit the suffix.

Prompt text can include prompt variables, such as {{foundationallm:current_datetime_utc:yyyy-MM-dd}}, that are resolved when a completion request is built. See Prompt Variables.

Platform Prompts

The platform prompts package provides well-known prompts that agents and tools reference by name. They include:

Prompt	Purpose
`Platform-Agent-Workflow-Router`	Tool selection instructions for single-round workflows.
`Platform-Agent-Workflow-Router-Multi-Round`	Tool selection instructions for multi-round workflows (uses `{{max_rounds}}` and `{{current_round}}`).
`Platform-Agent-Workflow-Files`	Instructions for using conversation files and attachments.
`Platform-Agent-Workflow-Escalation`	Instructions for the tool escalation pass. Used by default when the workflow does not reference its own escalation prompt.
`Platform-Agent-Workflow-Final`	Instructions for building the final response from tool results.
`Platform-Agent-Workflow-Rewrite`	Instructions for rewriting the user question.
`Platform-Agent-Tool-{ToolName}-Main` and `Platform-Agent-Tool-{ToolName}-Router`	Main and router prompts for platform tools such as Knowledge, Code, MCP, GeminiImageGen, GeminiWebGrounding, GPTImageGen, and ProgrammableToolCalling.

Managing Prompts with the Management API

{baseUrl} is the Management API base URL and {instanceId} is the FoundationaLLM instance ID. All requests require ?api-version=2024-02-16.

List

GET {baseUrl}/instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts?api-version=2024-02-16

Get

GET {baseUrl}/instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts/{promptName}?api-version=2024-02-16

Check Name Availability

POST {baseUrl}/instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts/checkname?api-version=2024-02-16
Content-Type: application/json

{
  "type": "multipart",
  "name": "{promptName}"
}

Create or Update

POST {baseUrl}/instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts/{promptName}?api-version=2024-02-16
Content-Type: application/json

{prompt JSON}

The request body is the prompt structure described above.

Delete

DELETE {baseUrl}/instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts/{promptName}?api-version=2024-02-16

Note

Delete is a logical delete. To permanently remove the prompt, call the purge action after deleting it.

Purge

POST {baseUrl}/instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts/{promptName}/purge?api-version=2024-02-16
Content-Type: application/json

{}

Table of Contents