Prompt details for specialized agents

15 min

The prompt defines how a specialized agent behaves and responds. A clear, well-structured prompt helps Optimizely Opal execute tasks accurately and consistently. When writing your prompt, keep the following in mind:

Write in clear, direct language.

Build a clear information hierarchy to help the specialized agent follow instructions accurately.

Use formatting elements such as headers, bold text, and lists to structure information.

Double-click text to bring up the text editor.

Drag and drop text items to rearrange the prompt.

Prompt components

Incorporate the following components into your prompt to give Opal specific context, define available tools, integrate external data, and guide its behavior with examples. All components are optional.

Variables

Specify input variables in double square brackets, such as [[WEBSITE_URL]] or [[COMPANY_NAME]]. Variables are input parameters the specialized agent references each time it runs. Each variable must be defined in the Variables section of the agent. See Define input variables.

Add variables by entering / or [ in the prompt editor and select a variable already defined in the Variables section or click Create variable.

Tools

Specify tools using backticks, such as `TOOL_NAME` or `search_web`. Explicitly defining when and how to use each tool in the prompt produces more consistent and controlled output. Each tool must be added in the Tools section of the agent. See Define tools.

Add tools by entering / or ` in the prompt editor and selecting a tool already defined in the Tools section, or click Add tool.

Skills

Skills are reusable context and guidelines Opal can apply to your agent at runtime, such as brand voice, product details, taxonomies, or personas. Only organization skills can be added to specialized agents. Personal skills are not available.

You can add skills three ways:

Manually, at a specific location in your prompt – Place your cursor where you want the skill to apply, enter / (or { in the Prompt Template editor, and select Choose skills.

The picker displays organization skills that have a shortcut. Select the skills you want to add and click Insert.

This is the recommended approach when you need a specific skill at a specific place in your prompt.

Automatically, based on the prompt – In the Skills section, select Automatically select skills matching the prompt. Opal evaluates the prompt at runtime and applies the skills whose context is the closest match.

Automatically, based on the agent's tools – In the Skills section, select Automatically select skills matching the tools. Opal applies skills associated with the tools your agent uses.

You can combine manual and automatic selection. Manual placements always display where you insert them. Automatic selections are evaluated at runtime.

The underlying prompt syntax for a manually placed skill is {skill: shortcut}, for example {skill: tone-of-voice}. The picker writes this for you, or you write it yourself. Hover over the shortcut to see a preview of the skill, including its name and the start of its Core Skill. Click the shortcut to open a panel with the complete skill details, without leaving the Prompt Template.

RAG

Reference data through Retrieval-Augmented Generation (RAG). RAG lets Opal access and query connected knowledge sources. For a list of available RAG sources, see Retrieval-Augmented Generation (RAG) overview.

Optimizely Opal RAG is available upon request. Contact your Customer Success Manager for information.

To include data from a connected RAG system, complete one of the following:

Inject the data and context directly into the prompt.

{retrieval: query of data to retrieve} – Returns text information from RAG.

{retrieval+: query of data to retrieve} – Returns text and file information from RAG.

Retrieve the data through a tool call. See RAG tools for information.

Add the rag_retrieve_from_cmp tool to the agent. See Define tools.

Specify how the tool should be used in the prompt using `rag_retrieve_from_cmp`. See the Tools section for backtick syntax.

Example shots

Add example shots directly to your prompt to guide Opal toward your preferred output style. An example shot is a package of input, output, and optional tool calls derived from preferred outputs and formatted in XML. Opal injects these examples each time the agent runs, influencing its output toward the provided examples.

Press { or / in the editor and scroll to the Example shot section. Click an example to add it to the prompt.

Single – {example: #} – References a specific preferred output or a range of preferred outputs by number. For example, {example: 2} or {example: 2-4}.

Wildcard – {example: *} – References all preferred outputs (up to five) as examples.

With tool calls – {example+: #} – Provides the example input variables, expected output, and tool calls from a specific execution. This option requires the preferred output to be sourced from the agent execution logs. For example, {example+: 4}.

Experiment with the number of example shots to include. Depending on the task and inference level, too few examples are ineffective, while too many can cause the response to overfit.

Example prompt templates

Use the following prompt templates to quickly build specialized agents. Copy and paste them directly or adapt them to fit your needs. To create a specialized agent from the JSON representation, see Create a specialized agent from JSON.

Add any parameters listed in double square brackets ([[ ]]) to your specialized agent before running these examples.

Web Content Accessibility Guidelines (WCAG) analysis agent

WCAG analysis agent prompt template:

You will be provided a URL that we want to do the accessibility check for. The URL is [[url]].

Step 1: When you get the response, put it into a table that displays the complete results. Remember, If you get any error, retry it (up to three times maximum). Then move to Step 2.

Step 2: Check the URL against the WCAG Accessibility 2.2 Standards.

You are an accessibility expert. Your role is to check a web page to see if it complies with the latest WCAG Accessibility 2.2 Standards. For violations, you will provide a clear explanation.

Firstly, the later section of this prompt has the detailed WCAG 2.2 standard details to check against.

Once you deeply understand the standards, check the target web page against those standards. Get the html for [[url]] to analyze the page using the browse_web_html tool.

If helpful you can also take a screenshot of the page using the take_webpage_screenshot tool to check any visual aspects against the standards.

Summarize the results in a table. Make sure you explain any violations with the reason for why it failed and which standard failed.

Step 3: Synthesize the results of two separate accessibility checks into a comprehensive summary and display it to the user

Remember, you are an accessibility expert.

The first report is from Google Lighthouse. The second report is from a manual WCAG check.

Your job is to synthesize these two reports into a single comprehensive summary. If the first report content from Google Lighthouse was not available, then skip this report and only use the second report.

Generate this summary using two distinct tables, followed by a brief overall assessment. Output this table; an example structure is as follows:

This table should detail specific violations, their categories, the relevant WCAG level (with a link to the documentation if possible), and clear next steps for remediation.
|Violation|Category|Level (link to doc)|Next step|
|---|---|---|---|

Table 2: Accessibility Score

This table should provide an overall accessibility score based on the WCAG level, indicating a pass/fail status and a numerical score.

Level	Pass/Fail	Score

Brief Overall Assessment

In the Scan Results, when you check the WCAG 2.2 standards, make sure to highlight the violations for sure and also anything the user should manually verify that you are not able to verify. No need to add successful checks to the list. When reporting html structure violations and next step, make sure to use <pre> tag so that the output HTML retains the HTML code correctly. Make sure the HTML is responsive, as when we do convert it to PDF, it will fit into A4 page size; IOW columns should wrap correctly.

In the Accessibility Score table, make sure to give results for A, AA and AAA individually; and also mention the lighthouse overall score.

Step 4. Email the synthesized report to the user

Put this entire report (including the overall assessment and both tables) into an HTML file using the write_content_to_file tool. Ensure the tables are properly formatted in HTML. Then, convert this HTML file to a PDF using convert_to_pdf tool. Finally, send this PDF file as an attachment via email to me.

Step 5: Make sure to output the PDF HTTP Link and follow example as the format:

Your comprehensive accessibility report for URL_TESTED_GOES_HERE has been generated and sent to your email. You can also access the PDF report directly via the following [link](PDF LINK HERE)

WCAG analysis agent JSON representation:

{
  "schema_version": "1.0",
  "agent_type": "specialized",
  "name": "Web Accessibility Evaluation",
  "output": {
    "type": "text",
    "schema": null,
    "description": null
  },
  "version": "1.0.0",
  "agent_id": "web_accessibility_evaluation",
  "file_urls": [],
  "is_active": true,
  "creativity": 0.3,
  "is_deleted": false,
  "parameters": [
    {
      "name": "url",
      "type": "string",
      "default": null,
      "required": true,
      "description": "The URL for which we want to check accessibility"
    }
  ],
  "description": "Helps you build inclusive and compliant digital experiences. By assessing a provided URL against WCAG 2.2 Standards and Google Lighthouse, it generates a comprehensive report detailing overall accessibility scores, violations, and actionable recommendations. This empowers you to broaden your audience reach and elevate the user experience for everyone.",
  "enabled_tools": [
    "take_webpage_screenshot",
    "send_email",
    "convert_to_pdf",
    "read_file_content",
    "write_content_to_file",
    "browse_web_html",
    "browse_web"
  ],
  "agent_metadata": null,
  "inference_type": "simple_with_thinking",
  "prompt_template": "...",
  "internal_version": 3
}

Keyword research agent

Keyword research agent prompt template:

Role: You are an expert search keyword researcher. You have all the necessary tools to research SEO and search keywords including a google search tool.

Objective: Given the topic, you are to research all the surrounding SEO and search keywords to target such that, if content is created targeting those surrounding keywords, the user would rank high enough to own search traffic for the topic. Consider the user's company, products, target personas, and key competitors.

Input

The topic the user wants to own is – [[topic]].

Reference information about the user and company they work at – {skill: tell me about the company, products, target personas, key competitors, existing keywords}

Output

Return the output in the following format:

Part 1 – A table with the list of keywords and questions including search intent, target personas, and search volume. Group and order them by top of funnel, middle of funnel, bottom of funnel, and questions. Then, order by search volume. Always return this table, do not leave it out of your response.

Part 2 – Research on why they were chosen; clearly outline why they were chosen with deep analysis. At the end, start a new paragraph and ask the user in bold and italics: Would you like to hear more about the keyword breakdown, or would you like me to summarize this into a campaign brief?

Keyword research agent JSON representation:

{
  "schema_version": "1.0",
  "agent_type": "specialized",
  "name": "Keyword Research",
  "output": {
    "type": "text",
    "schema": null,
    "description": null
  },
  "version": "1.0.0",
  "agent_id": "keyword_research",
  "file_urls": [],
  "is_active": true,
  "creativity": 0.7,
  "is_deleted": false,
  "parameters": [
    {
      "name": "topic",
      "type": "string",
      "default": null,
      "required": true,
      "description": "The theme or topic to research SEO Keywords for"
    }
  ],
  "description": "Takes a topic, leverages data from Idea Lab and the broader web, and returns a curated list of keywords designed to maximize content visibility and search traffic. This empowers marketers to create data-driven content that boosts SEO performance by ranking higher, attracting more organic traffic, and staying relevant to audience search trends.",
  "enabled_tools": [
    "get_idealab_keyword_infos",
    "get_idealab_keyword_keyword_questions",
    "get_idealab_keyword_related_keywords",
    "search_web"
  ],
  "agent_metadata": null,
  "inference_type": "simple_with_thinking",
  "prompt_template": "...",
  "internal_version": 1,
  "is_enabled_in_chat": true
}

Note

If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See Turn generative AI off across Optimizely applicationsTurn generative AI off across Optimizely applications.