Roles & Messages

Structure prompts as multi-turn conversations with system, user, and assistant roles

Roles & Messages

Echo DSL lets you structure prompts as multi-turn conversations using [#ROLE] blocks. Each block becomes a separate message in the output array.

Basic Syntax

roles-basic.echo

[#ROLE system]
You are a helpful customer support agent for {{company}}.
[END ROLE]

[#ROLE user]
My name is {{customer.name}} and I need help with {{issue}}.
[END ROLE]

Valid Roles

system — System instructions for the LLM
user — User messages
assistant — Previous assistant responses (for few-shot examples or conversation history)

Content without any [#ROLE] block is treated as a single user message.

Conditional Messages

Conditionals can wrap entire role blocks, allowing you to include or exclude messages dynamically:

conditional-roles.echo

[#ROLE system]
You are a support agent.
[END ROLE]

[#IF {{includeHistory}} #exists]
[#ROLE assistant]
I previously helped you with {{lastIssue}}.
[END ROLE]
[END IF]

[#ROLE user]
{{currentQuestion}}
[END ROLE]

renderMessages() API

import { createEcho } from "@goreal-ai/echo-pdk"

const echo = createEcho()
const result = await echo.renderMessages(template, {
  company: "Acme Inc",
  customer: { name: "Alice" },
  issue: "billing question"
})

// result.messages = [
//   { role: "system", content: [{ type: "text", text: "You are a helpful..." }] },
//   { role: "user", content: [{ type: "text", text: "My name is Alice..." }] }
// ]

Key Points

Each role block becomes a message in the output array
Variables are resolved within each role block
Conditionals can wrap entire role blocks
The render output follows the OpenAI message format