​
Overview

Messages are the building blocks of PromptL prompts. They define the flow of conversations between the user, the assistant, and other entities like tools. Each message is associated with a role that determines its purpose in the conversation.

PromptL supports the following message roles:

  • System: Sets the context and rules for the assistant.
  • User: Represents user input in the conversation.
  • Assistant: Captures assistant responses or provides context for the LLM’s output.
  • Tool: Represents interactions with external tools or APIs.

​
Roles

​
System Messages

System messages provide high-level instructions and context for the assistant.

<system>
  You are a personal finance advisor. Provide actionable insights in a friendly tone.
</system>

​
User Messages

User messages simulate user input in the conversation.

<user>
  How can I save more money each month?
</user>

​
Assistant Messages

Assistant messages represent LLM responses or “fake” previous outputs to guide the conversation.

<user>
  What's your name?
</user>

<assistant>
  I’m BudgetBot, your personal finance assistant. How can I help you today?
</assistant>

​
Tool Messages

Tool messages represent the output of external tools or APIs called by the assistant during the conversation. They require a unique id attribute to match the tool call.

<assistant>
  <tool-call id="123" name="get-weather" arguments={{ { location: "Barcelona" } }} />
</assistant>

<tool id="123">
  It's 17ºC in Barcelona.
</tool>

​
Tags

​
The <message> Tag

Messages can be defined using the <message> tag with a role attribute:

<message role="system">
  This is a system message.
</message>

​
Shortcut Tags

For convenience, you can use specific tags for each role:

  • <system>: Equivalent to <message role="system">.
  • <user>: Equivalent to <message role="user">.
  • <assistant>: Equivalent to <message role="assistant">.
  • <tool>: Equivalent to <message role="tool">.
<system>
  You are a friendly chatbot.
</system>
<user>
  What’s the weather today in Barcelona?
</user>
<assistant>
  Let me check for you!
  <tool-call id="123" name="get-weather" arguments={{ { location: "Barcelona" } }} />
</assistant>
<tool id="123">
  23ºC, sunny.
</tool>

​
Content Types

Messages can contain different types of content. By default, all plain text is considered text content, but you can specify other types using the <content> tag or its shorthand equivalents.

  • Text (default): <content type="text"> or <content-text>.
  • Image: <content type="image"> or <content-image>. Add the image URL or base64-encoded string – depending on your provider’s requirements – as the content inside the tag.
  • File: <content type="file"> or <content-file>. Add the file URL or base64-encoded string – depending on your provider’s requirements – as the content inside the tag. Requires a MIME type mime attribute to specify the file type.
  • Tool Call: <content type="tool-call"> or <tool-call>. Represents a tool invocation with attributes like id, name, and arguments (optional). Only allowed inside assistant messages.

Not all providers and all models will support all content types. Your provider may support files but not all types of files. Check your provider’s documentation for compatibility.

​
Examples

<user>
  Take a look at this image:
  <content-image>[image url]</content-image>

  And this PDF:
  <content-file mime="application/pdf">[file url]</content-file>
</user>

<assistant>
  <tool-call id="123" name="get-weather" arguments={{ { location: "Barcelona" } }} />
</assistant>

​
Best Practices

  • Use System Messages for Context: Define clear rules for the assistant to guide its behavior.
  • Leverage User Messages for Dynamic Input: Use uncontrolled user variables inside user messages to define a clear difference authority between the user and the system rules.

​
Advanced Examples

Here’s how multiple message roles and content types can work together:

<system>
  You are a helpful assistant for travel planning.
</system>

<user>
  Find me a good restaurant in {{ city }}.
</user>

<assistant>
  Let me check for you.
  <tool-call id="456" name="find-restaurant" arguments={{ { location: city } }} />
</assistant>

<tool id="456">
  The best-rated restaurant in {{ city }} is Gourmet Central.
</tool>