Specialized agents fundamentals and best practices

Specialized agents in Optimizely Opal are purpose-built AI agents you create that complete a single, well-defined task. They operate in a single-shot model. You provide inputs, the agent runs once, and it returns a result. There is no multi-turn conversation. Each agent can use targeted tools, adjustable reasoning, and defined inputs to finish its task accurately and efficiently. 

If you want to follow a step-by-step walkthrough to create an example specialized agent that reviews website content against established financial promotion regulations guidelines, see Create an example specialized agent walkthrough.

AI strategy, agent scope, and plan

Before creating a specialized agent in Optimizely Opal, you should understand how AI fits into your wider organization, plan what kind of specialized agent you want to create, comprehend the steps needed to create a specialized agent, and design a plan to create your specialized agent.

Identify high-impact use cases

When developing a portfolio of high-impact use cases, it is essential to gather input from multiple organizational perspectives. This includes top-down strategic direction from leadership and bottom-up practical insights from practitioners executing business-critical tasks. You can use a Creative Matrix framework to create an effective approach to collaboration. 

Structure the matrix with AI capabilities along one axis and business-relevant categories along the other, such as strategic objectives, departmental functions, or major initiatives. The following image is an example of a Creative Matrix:

Specialized agent scope

While it may be tempting to design multi-functional specialized agents that execute complex sequential processes, best practice for initial development is to decompose tasks into discrete, manageable components. Each component represents an individual specialized agent that can subsequently be orchestrated into larger workflows to fulfill more complex operational roles. See Workflow agents overview for information on linking multiple agents together to create a workflow agent. 

Specialized agent plan

Define the operational strategy your specialized agent executes. When creating your plan, consider the following questions:

• Data sources
  • What external systems or platforms will the specialized agent need to access for information (for example, public websites, internal databases, third-party APIs)?
  • What specific types of data will the agent retrieve (for instance, text content, numerical data, images, structured records, user input)?
  • Will the agent utilize information from Optimizely products, such as recent experiments in Optimizely Web Experimentation or Optimizely Feature Experimentation, Content Marketing Platform (CMP) tasks, or Content Management System (CMS) content?
  • What format is the input data in (raw HTML, JSON, CSV, plain text), and does it require any preprocessing or transformation by the agent?
  • Are there any access restrictions, authentication requirements, or rate limits for these data sources that the agent must adhere to?
• Actions and outputs
  • What specific actions will the specialized agent perform with the retrieved data (for instance, generate text, summarize content, analyze data, compare information, create reports)?
  • Will the specialized agent initiate tasks or update records in other systems, such as creating CMP tasks, modifying CMS content, or sending emails?
  • Will the agent execute specific queries, such as Optimizely Graph queries or other API calls, as part of its operation?
  • What is the expected format and structure of the agent's final output (for example, plain text, Markdown, HTML, JSON, a specific file type)?
  • How will the output be delivered or presented to the user (directly in chat, as a downloadable file, updated in an external system, or integrated into a canvas)?
  • What is the primary purpose or desired outcome of the agent's output for the user or downstream processes?
• System integration
  • Which specific Opal tools (system or custom) will the specialized agent need to interact with to perform its tasks?
  • Are there any dependencies or a required sequence for how the specialized agent uses these tools or interacts with different systems?
  • How will the specialized agent handle potential errors, timeouts, or unexpected responses when interacting with external systems or tools?
  • What are the performance implications of the specialized agent's integrations, and how will it ensure efficient operation?

Specialized agents in the wider Opal agent ecosystem

Agents are like intelligent assistants within Opal. They use natural language prompts and tools to complete tasks on your behalf. Each agent has a specific purpose, whether that is generating content, analyzing data, or automating workflows. With agents, you can make simple requests like, "Draft a social post for our product launch" or "Summarize experiment results", and Opal selects the right tools and follow the right prompt to get it done. 

There are multiple types of agents in Opal, including default, workflow, and specialized agents. 

Default agents are pre-built agents available in the Agent Directory. You can use these agents to understand existing capabilities and structural patterns. When you activate an agent in an Opal instance, it displays in the Your Agents tab.

Workflow agents combine specialized agents to automate multi-step processes. They streamline operations across the Optimizely platform and external systems by using tools.

You can examine any agent's structure, including its operational logic and execution strategy by clicking on an agent on the Agents page. Each agent (whether pre-built or custom-developed) must have a specific task context, information sources (either embedded or user-provided through variables), and the tools it uses to accomplish its objectives. See Agent overview for more information.

Specialized agents

Specialized agents contain the following parts:

• Details – Includes name, id, and description.
• Input – Includes the prompt template, variables, and tools.
• Output – Includes the output type and output evals.

Before building your first specialized agent, familiarize yourself with the specialized agent ecosystem and how each piece fits together to run your specialized agent. 

Details

The details section includes basic information about your specialized agent. Here, you can give your agent a Name, Id, and Description. Additionally, you can toggle your agent on or off and enable or disable it in Opal Chat. 

See the Details section in the Create an example specialized agent walkthrough documentation for guidance on configuring this component.

Input

The input section defines the core functionality of the specialized agent. The Input section includes the following components:

• Prompt template
• Instructions
• Variables
• Tools
• Inference level
• Files

Prompt template

The prompt template is where you add the directions to tell the specialized agent what it should do and how to respond to requests. 

When writing your prompt template, you can reference instructions, variables, and tools. You can write your prompt template any way you want, including using popular prompting frameworks, such as the CLEAR framework. The CLEAR framework includes the following:

• Context – The Who, What, and Why of the task.
• Logic – The mental model and reasoning rules the agent should apply. This includes frameworks, constraints, sequencing, and strategic decision-making approaches.
• Examples – Illustrations of desired outputs and outputs to avoid.
• Action – The specific actions required to achieve the objective. This should include references to variables and tools, and any uploaded files.
• Result – The format specifications for the output and delivery method.

See the following documentation for more information on prompt templates:

• Prompt template examples – A list of ideal samples you can add to your Opal instance.
• Configure the prompt template – Guidance for configuring the prompt template.
• Create an example specialized agent walkthrough – Example specialized agent you can create.

Instructions

Instructions are the foundational context, rules, and behavioral guidelines that shape how Opal creates output and tailors it to your unique needs. A simple form of instructions could have your company's brand guidelines, ensuring Opal generates on-brand content. Other common instructions include details about your company's products and services, target personas, user journey funnel, term-bases, and so on.

A key differentiator for Opal is its ability to dynamically pull and apply these instructions based on their When to use criteria. This ensures Opal always applies the most relevant and intelligently tailored guidelines, so Opal adapts its responses and actions precisely to the current context and your specific requirements.

Keep the following in mind when adding instructions to your specialized agent:

• In the Prompt Template, variables must be identified using curly braces and a description of which instructions Opal should call. For example,
  • {instruction: description of which instruction to use}
  • {instruction: tell me about the company, its products, target personas, key competitors, existing keywords}
• The specialized agent leverages the corresponding instructions that have a matching When to Use field.

See Instructions overview for information.

Variables

Variables are placeholders that let your specialized agent store and manage dynamic data such as user input, information from external systems, or configuration settings.

Keep the following in mind when adding variables to your specialized agent:

• In the Prompt Template, variable must be identified using double square brackets, [[example]], and are case-sensitive.
• In the variables section, click Add Variable and provide a concise name and a clear description.
• Variables are unique to each agent.

Example variables

• [[industry]] – Description – Business sector classification, for example, technology, retail, or healthcare.
• [[test_idea]] – Description – The concept or hypothesis provided by the user.
• [[url]] – Description – Request the user to provide a URL for content review.
• [[email_addresses]] – Description – Email addresses for report distribution.

See Define input variables for more information or the Create an example specialized agent walkthrough for a demonstration of adding variables.

Tools

Tools let specialized agents execute specific functions such as scanning URLs, uploading documents, updating CMS content, creating CMP tasks, or executing Optimizely Graph commands. There are many tools available by default in Opal. See System tools overview for a complete list.

Example tools

• browse_web – Concurrently browses multiple webpages and returns content. This tool enables information extraction from multiple webpages simultaneously. Each URL can specify its own output format (markdown or raw) and information query.
• create_canvas – Creates an interactive AI canvas. A canvas is a collaborative document letting you and Opal edit in real-time. Canvases are dynamic, editable workspaces where users and AI can iteratively develop content together. Ideal for iterative content creation and refinement.
• send_email – Composes and sends emails as a notification tool.

 Keep the following in mind when adding tools to your specialized agent:

• In the Prompt Template, tools must be identified using backticks `example` and are not case-sensitive. 
• In the tools section, click Add Tool.
• Unlike variables, tools can be shared across multiple agents.

An agent is specialized and only uses the tools you explicitly specify.

See the Create an example specialized agent walkthrough for a demonstration of adding tools.

Inference level

Inference level controls the depth of reasoning Opal applies. Higher levels require more processing time but yield more thoroughly reasoned outputs.

See Select the inference level in the Create specialized agents documentation or the Create an example specialized agent walkthrough for a demonstration of selecting the Inference level.

Files

You can also upload any reference files your agent should access during execution, such as templates, guidelines, or reference documents.

See Add files in the Create specialized agents documentation or Create an example specialized agent walkthrough for a demonstration of adding files.

Output

The output section is where you can add the expected output of the specialized agent after saving it. You can set the Data Type, which specifies the format of the output after the agent executes, along with a description, which explains the expected output of the prompt. 

You can also add up to five examples of preferred outputs that Opal can use to evaluate its responses against. The preferred output is used to create an evaluation score. Adding preferred outputs is optional. If you do not add examples, Opal does not create a quality score.

See the Configure output section and the Add Output Evals section in the Create specialized agent documentation. Or see the Output section and the Test your specialized agent section in the Create an example specialized agent walkthrough.

Test, refine, and deploy

Test your agent

You can use Test run in the agent details page to validate the functionality of the specialized agent. When testing your agent, you are prompted to enter any variables your agent requires for execution, such as URLs and email addresses. See Test a specialized agent.

Refinement strategies

If the agent's performance is unsatisfactory, consider the following refinement approaches:

Output format refinement

If the response format does not meet your requirements (for example, plain text in chat when you need structured HTML), add specific guidance directing the agent to output in your desired format.

Example prompt: If you are unable to access the website listed in [[url]], immediately inform the user of the issue and stop the process instead of continuing.

Uncertain about achieving your desired output format? Consult Opal directly.

1. Copy and paste the agent's output into Opal chat and request that Opal convert it to a visually appealing format.
2. When satisfied with the format or layout, ask Opal to remove the content and convert it into a template (for example, .html) and save it to your computer.
3. Upload the .html template file to your agent and reference it by name using backticks, ``, just as you would reference a tool.
4. Conduct another Test Run to evaluate whether the agent's output meets your requirements.

Logic and consistency refinement

If results are inconsistent,

• Add more specific constraints in the Prompt Template.
• Use if-then statements to handle multiple scenarios.
• Provide more detailed examples of desired outputs..

Accuracy refinement

If the agent produces inaccurate results, complete the following:

• Verify that all necessary tools are included.
• Ensure variables are clearly described.
• Add more context in the Prompt Template.
• Include specific examples of correct outputs.

Deploy

After testing confirms consistent, high-quality outputs, you can deploy your agent.

1. Document your agent – Add comprehensive descriptions so other users understand its purpose and capabilities.
2. Activate and enable in chat – Configure your agent so it is activated and enabled in chat. 
3. Create usage guidelines – Document any specific input requirements or limitations.
4. Monitor performance – Review outputs periodically to ensure continued quality after deployment.
5. Iterate – Based on user feedback, continue refining the agent to improve its effectiveness.

Create a specialized agent

Now that you have an understanding of how specialized agents work, you can create one for your organization. See the following documentation for steps:

• Create an example specialized agent walkthrough
• Create specialized agents