Blog posts by My Blog2026-07-23T14:48:00.0000000Zhttps://world.optimizely.com/blogs/my-blog/Optimizely WorldFrom AI Agents to AI Workflow with Opal<h2 class="article-editor-heading article-editor-content__has-focus">Introduction</h2>
<p class="article-editor-paragraph">In the <a class="article-editor-link article-editor-link" href="/link/b31bb7d003754244a5a025412aca0edd.aspx">first article in this series</a>, we talked about AI agents in Optimizely Opal and walked through the process of creating a specialised agent. In this article we will take the next step and build a workflow agent.</p>
<p class="article-editor-paragraph">As in the first article, we will go through a step–by–step process of creating a workflow agent using a practical example of creating a workflow that performs automated initial review of content draft for brand and tone of voice alignment.</p>
<h2 class="article-editor-heading">Standalone agent vs workflow agent</h2>
<p class="article-editor-paragraph">Before we dive into building a workflow agent, let’s first look at how it differs from a Standalone Agent. “Standalone agent” is not an official term used in Optimizely documentation, but in this article, we will use it to refer to either an existing agent from the Optimizely Agent Directory or a specialised agent you build yourself.</p>
<p class="article-editor-paragraph">A standalone agent already uses context (prompt template, variables, attached files, instructions and the conversation it is in). It can already take actions on its own using tools. What it cannot do is start on its own, coordinate other agents, or run the same workflow on a schedule or every time an event happens. That is what a workflow agent adds: it uses triggers, steps sequence, conditions and loops to combine multiple standalone agents into a multi–step process.</p>
<p class="article-editor-paragraph">Can you just create a specialised agent with a prompt that will make it do the same multi-step process? In theory – yes, but in practice such a complex agent will be very difficult (if not impossible) and expensive (in terms of Opal credits and time spent) to test, debug and maintain. You can refer to the first article – it explains this in more detail.</p>
<p class="article-editor-paragraph">An important consideration to keep in mind: workflow agents typically operate with greater autonomy and less human involvement. A standalone agent is usually invoked by a person, who then reviews its output. A workflow agent, by contrast, often starts automatically and runs unattended, with human review taking place only after the workflow is complete. For this reason, workflow agents (and any standalone agents they use as part of the workflow) need stricter guardrails defining what they can do, what outputs they must produce, and how they should handle errors and edge cases.</p>
<h2 class="article-editor-heading">Building Blocks of a Workflow Agent</h2>
<p class="article-editor-paragraph">A workflow agent consists of 3 building blocks: a trigger that decides when it starts, a series of agents that each perform one step, and the logic that determines how those steps are sequenced.</p>
<p class="article-editor-paragraph is-empty"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQFAGVo8yhATAQ/article-inline_image-shrink_1000_1488/B56Z.KYG2mH4AI-/0/1784733003415?e=1786579200&v=beta&t=hCqpg6pXSyvFyieIdqE7wDKGi6OHElqbitKq8XYHZsM" /></p>
<h3 class="article-editor-heading">Trigger</h3>
<p class="article-editor-paragraph"><a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/39865892823693-Workflow-agent-triggers">Trigger</a> is what starts the workflow agent. It can be one of the following:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Chat</strong> – agent is called from a chat, just like a standalone agent.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Scheduler</strong> – agent is executed on a schedule (every hour, every day at 9AM, etc.).</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Webhook</strong> – Opal listens for an incoming webhook and starts the workflow when an external. system sends an event.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Email</strong> – agent is called when email is sent to the email address that you set as the Trigger Recipient. You can configure additional conditions for sender and subject to avoid accidental email or spam to result in workflow execution</p>
</li>
</ul>
<h3 class="article-editor-heading">Logic</h3>
<p class="article-editor-paragraph">Workflow agent logic is defined using conditions and loops.</p>
<p class="article-editor-paragraph"><a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/43620929090829-Workflow-agent-conditions#h_01KHS15TF8A8X5ZW0N9HKT1GYE">Conditions</a> allow the workflow to follow different paths based on defined criteria. This is your typical “if-then-else” condition that can have multiple “then” parts. Below is an example of having different processing steps for blog article, email or social post.</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="/link/cb0c40f167984ffd99605a2f8abe0263.aspx" /></p>
<p class="article-editor-paragraph"> </p>
<p class="article-editor-paragraph">Consider the following best practices when using conditions in workflow:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Use clear criteria and structured data</strong> – base conditions on specific, predictable values. Prefer numeric or pre-defined values such as High, Medium or Low over free-form text.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Keep conditions simple</strong> – split complex logic into smaller decisions.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Avoid overlapping or duplicate rules </strong>– make it clear which path takes priority.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Cover every outcome </strong>– include both matching and fallback paths.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Test edge cases </strong>– check missing, unexpected and boundary values.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Add a safe fallback </strong>– route uncertain cases for human review or end the workflow safely.</p>
</li>
</ul>
<p class="article-editor-paragraph"><a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/43590976293389-Workflow-agent-loops">Loop</a> is handy when you need to perform same step (or set of steps) over multiple items. Below is an example of using loop to do AEO/GEO analysis and provide summary and improvement recommendations for all child pages of a specified page.</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQGrafRs4viSMQ/article-inline_image-shrink_1000_1488/B56Z.KYwDcJoAM-/0/1784733172179?e=1786579200&v=beta&t=dt_NwalvU39iQTgUKbkqBTq0zdJH-pOxJKSNXjyCjks" /></p>
<p class="article-editor-paragraph">Some best practices when using loops:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Keep the loop focused</strong> – include only the steps required for each item inside the loop, all other steps should be outside of the loop.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Handle individual failures</strong> – define what should happen when one or more items in the loop cannot be processed.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Test with different list sizes</strong> – plan/check for empty lists, single-item lists and larger collections.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Limit the number of iterations</strong> – large lists can increase workflow execution time and credits consumption.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Avoid excessive nesting</strong> – Optimizely supports up to three nested loops, but simpler workflows are easier to maintain so avoid nested loops unless it’s really necessary.</p>
</li>
</ul>
<h3 class="article-editor-heading">Agents</h3>
<p class="article-editor-paragraph">Each step in the workflow is executed by an agent – it can be out-of-the-box agent from Optimizely Agent Directory or a specialised agent you or someone else from your team created.</p>
<h2 class="article-editor-heading">Creating Workflow Agent</h2>
<p class="article-editor-paragraph">Let’s now create a workflow agent that performs an automated initial review of a content draft for brand and tone-of-voice alignment.</p>
<p class="article-editor-paragraph">In this example we will use combination of Optimizely CMP + Opal. There is a reason this is a very powerful combination – CMP provides the structure, governance and visibility to the process, while Opal adds the creativity, reasoning and judgement needed to accelerate complex tasks that cannot be done by conventional tools, such as creating content briefs and drafts, reviewing and proofreading content.</p>
<p class="article-editor-paragraph">Here is the scenario we will build. A content team is working on content production. Every content production task follows a set of steps, and one of these steps is <strong>Brand review</strong>. Today, a copywriter picks up this step, opens the content, opens the brand guidelines, and checks one against the other. It is necessary work, but most of it is mechanical.</p>
<p class="article-editor-paragraph">With the workflow we will build, when a task reaches the Brand review step, Opal picks it up automatically. It reads the content, fetches the latest brand and tone of voice guidelines, reviews the content against them, and leaves a comment on the task listing any issues it found and suggesting improvements. The task is then assigned to the copywriter, who now starts from a prepared initial review instead of a blank page.</p>
<p class="article-editor-paragraph">Looks simple but even such a simple workflow can save lots of time for a team that has to produce lots of content and is short on resources. Or imagine a situation where a new version of brand guidelines is released and someone needs to re-check 20 most recent articles against updated guidelines. How long would that take if done manually from scratch? As a copywriter, is this a kind of task you’d be excited to work on? As a team manager, is this where you’d want to spend your copywriters’ time?</p>
<h3 class="article-editor-heading">Planning the Workflow</h3>
<p class="article-editor-paragraph">Before jumping into building the agent, it’s first important to understand and plan what exactly you want to the workflow to do, how do you want it to do it.</p>
<p class="article-editor-paragraph">A simple way to do this is to write down workflow steps or (if you’re a visual person) draw it as a sequence diagram. Then look at the workflow and ask yourself these questions:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Is it only covering the happy path, what could go unexpectedly and how should we handle it.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Do you have human review steps at the right place? It’s tempting to have a workflow where AI does just everything and human only reviews the final result but in a complex multi-step workflow you will likely need few human review checkpoints.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">If workflow has a loop in it – is there a risk of it becoming an endless loop or having too many iterations, do you want to put a limit on number of iterations to avoid it from consuming too many credits?</p>
</li>
</ul>
<p class="article-editor-paragraph">Here are the high-level steps in our example workflow:</p>
<ol class="article-editor-ordered-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Content creation task reaches the AI Assisted Brand review step.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Opal gets the task details and extracts the content to be reviewed.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Opal fetches the latest brand and tone of voice guidelines.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">For each content item in the task, Opal identifies the content type, reviews it against the relevant guidelines, and leaves a comment on the task with identified issues and suggested improvements.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Opal moves the task to the next step, Final Brand Review and Approval.</p>
</li>
</ol>
<p class="article-editor-paragraph">Next, we look at these initial steps and ask the questions:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">What should happen if we cannot get the task details on step 2?</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">What if task status is Completed instead of instead of In Progress – do we still do the review or skip it?</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">What if we get an error fetching latest brand guidelines?</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">On step 4, what content type should be reviewed and what content type should be skipped?</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Do we want to have a limit of content types to review within 1 task?</p>
</li>
</ul>
<p class="article-editor-paragraph">Now we adjust our workflow with these considerations in mind:</p>
<ol class="article-editor-ordered-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Content creation task reaches the AI Assisted Brand review step.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Get task details. If there is an error when getting task details – notify support/ops team via email. If task status is Completed – skip processing and exit.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Get the latest brand and tone of voice guidelines. If there is an error getting them – skip processing, leave comment about this in the task and notify support/ops team via email</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Get content items with content type “article” or “social media post” from the task – these are the only ones we want to cover with the review. If there are no matching content items – skip processing, leave comment about this in the task. If there are more than 5 matching content items found – leave comment that only first 5 will be processed, the rest will be skipped</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Loop over found content items: Review content item against brand guidelines, leave comment in the task with findings and recommendations. Stop after reviewing 5 content items.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Move the task to the next step – Final Brand Review and Approval.</p>
</li>
</ol>
<h3 class="article-editor-heading">Configuring the Workflow</h3>
<h3 class="article-editor-heading">CMP Configuration</h3>
<p class="article-editor-paragraph">CMP will control the overall content production steps. We will not get into the details of CMP configuration in this article but if you’re starting with CMP, you can read about how to <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/8186091022093-Manage-workflows">configure task workflows</a>.</p>
<h3 class="article-editor-heading">Workflow</h3>
<p class="article-editor-paragraph">Here is how our CMP Task Workflow looks like</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQHQ38iuMYP90Q/article-inline_image-shrink_1500_2232/B56Z.KaC6TJoAQ-/0/1784733511531?e=1786579200&v=beta&t=Xxqod8dnRdkMlW4aHhw29eyliyLY88thxtBkO30X7DI" /></p>
<p class="article-editor-paragraph">Note that AI Brand Review has the icon that indicates that it is an external step – this is required to trigger Opal workflow agent from this step.</p>
<p class="article-editor-paragraph">When converting this step to external step you will be required to select external system:</p>
<p class="article-editor-paragraph">We will later use this in Opal agent configuration to distinguish webhook for external step in “Content Production with AI-Assisted Brand Review” CMP workflow vs external step in another CMP workflow.</p>
<h3 class="article-editor-heading"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQFKzpGPJOtgNA/article-inline_image-shrink_1500_2232/B56Z.KaGknKcAQ-/0/1784733526572?e=1786579200&v=beta&t=J6mE4K_5A8cCCa9M79L-j91-VF5-_X08CUipZqoTxD0" /></h3>
<h3 class="article-editor-heading">Configuring webhook to trigger Opal workflow agent</h3>
<p class="article-editor-paragraph">We already have workflow with external step – now we need to create webhook in CMP to notify Opal when our external step “AI Brand Review” is started.</p>
<p class="article-editor-paragraph">This process is describe in details here: <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/43289384478989-How-to-trigger-workflow-agents-with-Content-Marketing-Platform-webhooks">https://support.optimizely.com/hc/en-us/articles/43289384478989-How-to-trigger-workflow-agents-with-Content-Marketing-Platform-webhooks</a></p>
<p class="article-editor-paragraph">We will only select 1 event for our webhook: <strong>external_sub_step_started</strong></p>
<p class="article-editor-paragraph">Note that when creating webhook you will need to provide callback URL and secret – you get those when you create trigger in Opal – once you get them copy them to webhook settings.</p>
<h3 class="article-editor-heading">Opal Configuration</h3>
<p class="article-editor-paragraph">Here is how our workflow will look like when we’re done</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="/link/d7e550844e6e4483a0aeb8ff530e086e.aspx" width="1267" height="693" /></p>
<p class="article-editor-paragraph">Let’s see how we create it step by step.</p>
<h3 class="article-editor-heading">Connect Opal to CMP instance</h3>
<p class="article-editor-paragraph">For Opal agents to be able to use existing CMP tools to get task details, it must be given access to this CMP instance by connecting to it.</p>
<p class="article-editor-paragraph">Note that this connection can only be added by Opal Administrator in your organisation: <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/36359944449805-Get-started-with-Optimizely-Opal-for-administrators#h_01JTGSVJJ6VYDVXSYEK8MZTQWX">https://support.optimizely.com/hc/en-us/articles/36359944449805-Get-started-with-Optimizely-Opal-for-administrators#h_01JTGSVJJ6VYDVXSYEK8MZTQWX</a></p>
<p class="article-editor-paragraph">As a user, you can check what Optimizely products and instances Opal is connected to by creating a workflow agent, adding a trigger step, clicking on the trigger step and see what products and instances are available in Product Instance drop-down.</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQEljT6VHAuhmg/article-inline_image-shrink_1500_2232/B56Z.Kanc7JoAQ-/0/1784733661280?e=1786579200&v=beta&t=C4uJBmOl5wc5HxohrbUycJDDkBrDdOXBTj4SfO2WteQ" /></p>
<h3 class="article-editor-heading">Add Trigger</h3>
<p class="article-editor-paragraph">Once you add a trigger by dragging it from the components section to working area, make sure to select the right product instance and configure auth header as described in the documentation:</p>
<p class="article-editor-paragraph"><a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/43289384478989-How-to-trigger-workflow-agents-with-Content-Marketing-Platform-webhooks">https://support.optimizely.com/hc/en-us/articles/43289384478989-How-to-trigger-workflow-agents-with-Content-Marketing-Platform-webhooks</a></p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQEqTVINacL5Fg/article-inline_image-shrink_1500_2232/B56Z.KarpOKMAU-/0/1784733678399?e=1786579200&v=beta&t=Ev8Qto4m7v3RD3bRpIg5f-lVXOoXphwjLKOOvS9tLAM" /></p>
<p class="article-editor-paragraph">Copy webhook URL and secret and put them in webhook configuration on CMP side.</p>
<p class="article-editor-paragraph is-empty"> </p>
<h3 class="article-editor-heading">Add check for external system passed in webhook</h3>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQH1HuRYeQjiaA/article-inline_image-shrink_1500_2232/B56Z.KWnOVGQAQ-/0/1784732611703?e=1786579200&v=beta&t=G4z3BvhoHgxHG6vLDrM1bOMEh8E4Wg4UtW8-vyjzLq0" /></p>
<p class="article-editor-paragraph">This is similar to External Step Routing Agent described here: <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/43289384478989-How-to-trigger-workflow-agents-with-Content-Marketing-Platform-webhooks">https://support.optimizely.com/hc/en-us/articles/43289384478989-How-to-trigger-workflow-agents-with-Content-Marketing-Platform-webhooks</a></p>
<p class="article-editor-paragraph">But instead of agent with external step name specified in prompt, we use an agent that gets value of external step + a condition that checks it. You can re-use this combination in other workflows initiated by a webhook trigger without having to create separate step routing agent with different external system name in prompt.</p>
<p class="article-editor-paragraph">We need to add this check because CMP will call the webhook any time an external sub step of a task is started. It could be an external step of a task in a completely different workflow unrelated to content production.</p>
<h3 class="article-editor-heading">Add agents to get task and step details and check if it’s ready for processing</h3>
<p class="article-editor-paragraph">Next, we need agents that will get task details and check if task is at the right step in the workflow (AI Brand Review).</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQGMeGKuGmFOrw/article-inline_image-shrink_1000_1488/B56Z.KbhxNHUAM-/0/1784733900139?e=1786579200&v=beta&t=bgemiz65ENgvYWlT_D7e9GEaz1z1fuVaBWYujVGVkRY" width="815" height="469" /></p>
<p class="article-editor-paragraph">All this could be done with 1 specialised agent, but as we covered before, smaller agents are easier to create and maintain.</p>
<p class="article-editor-paragraph">We already covered details on creating specialised agents in the previous article, so here we’ll focus on what each of these agents will do rather than how they are built.</p>
<p class="article-editor-paragraph"><strong>Get CMP Task Details from Webhook </strong>agent does exactly what the name suggests</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Gets CMP task ID from webhook</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Uses <strong>get_cmp_resource</strong> tool to get task details</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Returns task details</p>
</li>
</ul>
<p class="article-editor-paragraph">You can re-use agent in any other workflow that is initiated by a webhook from CMP Task.</p>
<p class="article-editor-paragraph"><strong> Verify CMP Task and Step </strong>agent gets task details from the previous agent, check the status of the task (should be <strong>In Progress</strong>), and the current step of the task (should be AI Brand Review). If task has the right status and is at the right step – it will return <strong>READY_TO_PROCEED</strong>.</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQGgl0LzgLwbxw/article-inline_image-shrink_1000_1488/B56Z.KbrIwG8AI-/0/1784733938544?e=1786579200&v=beta&t=yVsJ8MJg3CRJ7st2edSfPvmJzWIuGE7_FgdWEl01kiM" width="629" height="362" /></p>
<p class="article-editor-paragraph">We then have a condition step that moves workflow to next step (Brand Guardrails retrieval) or stops processing if the CMP task has wrong status or is not at “AI Brand Review” step.</p>
<p class="article-editor-paragraph">We also added a condition to notify Ops team in case Opal fails to get task details from CMP. This is an optional condition and we’re using it as example of how you can make the workflow more robust.</p>
<p class="article-editor-paragraph"> </p>
<h3 class="article-editor-heading">Add agent to get latest brand and tone of voice guidelines</h3>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQFn528yInFL1g/article-inline_image-shrink_1500_2232/B56Z.KbvejGQAU-/0/1784733956347?e=1786579200&v=beta&t=LgddnHyWZI5LG5RzDcu4tIFwit5JydWnt831Th0l39Y" width="617" height="478" /></p>
<p class="article-editor-paragraph">This agent gets the latest version of brand and tone of voice guidelines. Depending on how and where you store these guidelines, it can use tools like browse_web or read_file or a custom tool (if you keep brand guidelines in a system that must be access in a specific way).</p>
<p class="article-editor-paragraph">This agent should also return the status of guidelines retrieval. In this example we return <strong>BRAND_GUIDELINES_READY</strong> if all went well.</p>
<p class="article-editor-paragraph">Here we also have a contingency step to notify Ops team if brand retrieval was not successful.</p>
<h3 class="article-editor-heading">Add agent to get content items from the task</h3>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQGPPfxb9RPhAQ/article-inline_image-shrink_400_744/B56Z.Kb3vRG4AQ-/0/1784733990158?e=1786579200&v=beta&t=jFrVd66DRu1KoFyJClSPFD-Soc1OZ7Gr_ZC9UXs1lxE" /></p>
<p class="article-editor-paragraph">Now that we have the brand guidelines, we need to get content items from the task. This agent goes over list of content items created in the task and filters one with the appropriate type (article, social post, etc). It can get list of content items in task from “Get CMP task details” agent or use tool <strong>get_cmp_resource</strong> to get this information. We can also instruct this agent to:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">leave comment in the task if there are no content items found in the task and there is nothing to review;</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">only choose first 5 content items from the task if it has too many (to avoid workflow taking forever and consuming too many credits) and leave comment about this in the task.</p>
</li>
</ul>
<p class="article-editor-paragraph"> </p>
<h3 class="article-editor-heading">Use loop to call Brand Review Agent for each content item</h3>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="https://media.licdn.com/dms/image/v2/D5612AQG6a48UEsVXgQ/article-inline_image-shrink_400_744/B56Z.Kb._XGgAM-/0/1784734019933?e=1786579200&v=beta&t=IQOS6DiuDgUwMsCDM2LQCW3EWa2NahECSkWgfiFSZ10" /></p>
<p class="article-editor-paragraph">Since a task can have multiple content items in it, we use loop to iterate over these content items and call Brand Review Agent for each of them.</p>
<p class="article-editor-paragraph">Brand Review Agent already has access to brand guidelines (passed from “Retrieve Latest Brand Guidelines” agent), uses tool <strong>cmp_retrieve_asset_from_library </strong>to get asset contents, and uses tool <strong>add_comment_on_task_substep </strong>to leave comment with review details.</p>
<h3 class="article-editor-heading">Mark step in task as Completed</h3>
<p class="article-editor-paragraph">To make CMP workflow progress to the next step, we have an agent that uses tool <strong>update_task_substep </strong>to complete the current step (AI Brand Review).</p>
<h3 class="article-editor-heading">Testing and Troubleshooting the Workflow</h3>
<p class="article-editor-paragraph">Just as specialised agents, workflow agents in Opal keep execution log that show details of each step in the workflow, including input, output and processing status.</p>
<figure class="article-editor-figure-image">
<div class="article-editor-inline-image__container article-editor-inline-image__container--resize">
<div class="article-editor-content__element-overlay">
<div class="article-editor-inline-image__buttons">
<div class="resize-image-control-button-tooltip resize-image-control-button-tooltip--hidden">Maximize image</div>
<div class="resize-image-control-button-tooltip resize-image-control-button-tooltip--hidden">Edit image</div>
<div class="resize-image-control-button-tooltip resize-image-control-button-tooltip--hidden">Delete image</div>
</div>
</div>
<img class="article-editor-inline-image__image" src="https://media.licdn.com/dms/image/v2/D5612AQEo6FmSPoucnw/article-inline_image-shrink_1000_1488/B56Z.KcJ_SKAAI-/0/1784734064904?e=1786579200&v=beta&t=jKUmmqtJitOsWqLG2jnV62CqgBRZKqf1og14CvxjxvE" alt="" /></div>
<figcaption class="is-empty"></figcaption>
</figure>
<p class="article-editor-paragraph">To see details of an execution – click on the flow icon</p>
<p class="article-editor-paragraph"><img style="display: block; margin-left: auto; margin-right: auto;" src="/link/ff060a4fea194b54a3a6fce1d2812278.aspx" width="1725" height="262" /></p>
<p class="article-editor-paragraph">And from there you can click on each step in the workflow to see its input, output and execution memory.</p>
<p class="article-editor-paragraph">I recommend that you do this testing early in the process and repeat every time you add a new step to the workflow, especially if you are creating a workflow for the first time. Otherwise, it will be difficult to find where it went wrong when you need to troubleshoot across 5-10 steps.</p>
<p class="article-editor-paragraph">As a starting point – make sure CMP trigger actually works:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Create CMP task based on the workflow that includes external step that will trigger the webhook</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Make sure you saved you workflow agent and it’s in Active status</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Move task to the step that triggers the Opal workflow and make sure step is in In Progress state</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Go to Opal agent > View logs – you should see agent execution in the log</p>
</li>
</ul>
<p class="article-editor-paragraph"> </p>
<h3 class="article-editor-heading">Lessons learned</h3>
<p class="article-editor-paragraph">A few principles I would carry into building any workflow like this:</p>
<p class="article-editor-paragraph"><strong>Start small. </strong>One trigger, one review, one comment. A first version that also fixes the content, reassigns the task, and updates three external systems in the process is harder to test and debug. Get one path working end to end before you add the next.</p>
<p class="article-editor-paragraph"><strong>Use a clear trigger. </strong>It should be clear what starts the workflow. If you find yourself adding too many conditions right after the trigger, the trigger is probably too broad.</p>
<p class="article-editor-paragraph"><strong>Keep each agent focused.</strong> The same rule as in the first article applies: an agent should do one thing well. This matters even more inside a workflow than in chat, because agents in a workflow run unattended in a single pass - there is nobody there to answer a clarifying question, so the prompt has to carry everything the agent needs.</p>
<p class="article-editor-paragraph"><strong>Keep a human approval step. </strong>No matter how good the results may look, leave the final step assigned to a person. The workflow's job is to make that person faster, not to replace their decision.</p>
<p class="article-editor-paragraph"><strong>Do not automate irreversible actions early.</strong> Leaving a comment is easy to ignore if it is wrong. Un-publishing content or rejecting a task is not as easy. Keep the workflow on the safe side of that line until you trust it.</p>
<p class="article-editor-paragraph"><strong>Measure the result.</strong> The point of this workflow is less manual effort and better review coverage. Check whether that is actually happening by looking at the measurements available in agent execution log, CMP reports on tasks throughput and most importantly, by talking to people who use the workflow.</p>
<h2 class="article-editor-heading">Wrapping up</h2>
<p class="article-editor-paragraph">In the first article, we built a specialised agent that focuses on one task. In this one, we connected several agents to create to a real content process: a trigger from CMP, context gathered at run time, a loop over content items, an action written back into the task, and a human making the final call.</p>
<p class="article-editor-paragraph">Standalone agents are already valuable, but workflows are where the efficiency gains can multiply. When applied to the right process and designed well, workflows can run consistently whenever they are needed, without relying on someone to initiate each step. As this example shows, that does not mean removing the human from the process. The goal is to reduce the time spent on repetitive, time-consuming tasks so people can focus on review, judgement and final decisions. AI simply expands the range of work that can be treated as routine and automated.</p>2026-07-23T14:48:00.0000000ZBlog postBuilding Your First Optimizely Opal AI Agent: a Hands-On Walkthrough<h2 class="article-editor-heading article-editor-content__has-focus">Introduction</h2>
<p class="article-editor-paragraph">There's a common assumption that building an AI agent is something only engineers or developers can do. It isn't. At the Optimizely ANZ Ai-ccelerate Opal Workshop in Melbourne this May, a room full of marketeers built their own working Opal agents in a single 2-hour session. For some of them it was the first time they’ve seen Optimizely Opal.</p>
<p class="article-editor-paragraph">A specialised agent in Optimizely Opal is, at its core, a set of written instructions and a few settings – there’s no code writing required. The main skill is being able to describe a task clearly: if you can write a clear brief for a colleague, you have most of what you need. Of course, understanding the subject matter is also very important. The rest is understanding few key concepts and some best practices – this is what this article covers.</p>
<p class="article-editor-paragraph">This article is for anyone who has started using Opal and wants to understand how specialised agents are built. You don't need to be technical, and you don't need a developer's background. It's written with marketing managers, content managers, and CRO specialists in mind, but it's just as useful if you're still getting familiar with Opal and want a clear picture of what's going on under the hood before you build anything yourself.</p>
<p class="article-editor-paragraph">To keep it practical, we will use example of building <strong>Answer Readiness Reviewer</strong> agent: you give it a page URL and a question, and it tells you whether an AI assistant (ChatGPT, Claude, Perplexity, and the like) could actually pull the answer to that question off that page. It reads the content, decides whether the answer is explicit, buried, fragmented, or missing, and then suggests what to change so the page is more likely to be the one an AI quotes. Deciding whether a page actually answers a question well enough for an AI assistant to use it is a judgement call, not a straightforward check that can be done by a script, and that's exactly the kind of work an agent is good at. We'll use it as our running example so that every concept has something solid attached to it.</p>
<h2 class="article-editor-heading">What an agent actually is</h2>
<p class="article-editor-paragraph">Let’s start with understanding key concepts used in Opal: <strong>agents</strong>, <strong>tools</strong>, and <strong>skills</strong>.</p>
<p class="article-editor-paragraph">An <strong>agent</strong> is the assistant that completes the task. It follows a set of written instructions to complete it, and it can call on tools to take action along the way. Opal describes agents as intelligent assistants that use natural language prompts and tools to complete tasks on your behalf, with each agent having a specific purpose – generating content, analysing data, or automating a step in a workflow.</p>
<p class="article-editor-paragraph">A <strong>tool</strong> is a single action the agent can take. Opal's own analogy is an attachment on a Swiss Army knife – each one does one specific thing. Examples of tools include searching the web, creating a campaign, generating an image, or fetching the HTML of a web page. The agent decides which tools it needs and calls them; you don't run them by hand. Our example agent will use a tool called browse_web_html. This tool fetches the raw contents of a web page. Agent will use it to read the actual page it's been asked to review, exactly as a browser would see it. Opal has an rich catalogue of tools available out of the box – you can find it here <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/39340107628429-System-tools-overview">https://support.optimizely.com/hc/en-us/articles/39340107628429-System-tools-overview</a></p>
<p class="article-editor-paragraph">The relationship between the two is simple: the <strong>agent is the worker, the tools are its equipment</strong>. An agent with no tools can only think and write. An agent with the right tools can also do things – read a page, send an email, update a record. You give an agent access to a tool by naming it in the agent's instructions and adding it in the agent's Tools section.</p>
<p class="article-editor-paragraph"><strong>Skills</strong> (which Opal used to call "instructions") are the third piece. Skills are reusable context and guidelines that shape how Opal behaves, like your brand voice, your product descriptions, your target personas, or your formatting rules. The point of skills is that you write them once and reuse them everywhere, instead of repeating "here's our tone of voice" in every single agent. One thing worth knowing: a specialized agent does not automatically pull in your skills. If you want an agent to use one, you reference it explicitly in the agent's instructions. So skills are the shared knowledge your agents use if needed.</p>
<p class="article-editor-paragraph">Put together: an <strong>agent</strong> does a job by following its prompt, using shared <strong>skills</strong> for context, and calling <strong>tools</strong> to take actions.</p>
<h3 class="article-editor-heading">The three types of agents</h3>
<p class="article-editor-paragraph">Opal has three kinds of agents, and knowing the difference saves you from building something that already exists.</p>
<p class="article-editor-paragraph"><strong>Out-of-the-box agents</strong> (also called default agents) live in the <strong>Agent Directory</strong>. Optimizely builds and maintains these, and they're ready to run without any setup. They cover common jobs like reviewing content for tone and style, generating competitive insights, or drafting support responses. Each listing tells you what the agent does, which tools it includes, and what you can configure. If one of these already does what you need – try using it first. They're also worth checking out even when you plan to build your own, because they show you working examples of how an agent is structured. You can see list of available agents if you select Agents from the left frame menu in Opal and then select Agent Directory.</p>
<p class="article-editor-paragraph"><img src="/link/34a8a928b5fe47d7bb163326c549dd1f.aspx" /></p>
<p class="article-editor-paragraph">If you don’t yet have access to Opal, you can find agent directory here: <a class="article-editor-link article-editor-link" href="https://www.optimizely.com/agents/">https://www.optimizely.com/agents/</a></p>
<p class="article-editor-paragraph"><strong>Specialised agents</strong> are the custom agents you build. Specialised agents are the right choice when no default agent covers your task and you want precise control over the inputs, the output, and the behaviour.</p>
<p class="article-editor-paragraph"><strong>Workflow agents</strong> are the third type, and they're more advanced. A workflow agent chains several default and specialised agents together into a multi-step process, with the output of one feeding into the next. Think of it as assembling a small team where each member does their part and hands off to the next.</p>
<p class="article-editor-paragraph">This article focuses on building Specialised agents, we’ll cover Workflow agents in another article.</p>
<h3 class="article-editor-heading">Before you start: the prerequisites</h3>
<p class="article-editor-paragraph">A few things need to be in place before you can create a specialised agent.</p>
<p class="article-editor-paragraph"><strong>Opal license that supports creating specialised agents.</strong> If you're unsure what your Opal license covers, your Customer Success Manager can confirm.</p>
<p class="article-editor-paragraph"><strong>The right role assigned to your user.</strong> The roles that can create agents are <em>Agent Builder</em>, <em>Opal Administrator</em> or any custom role that's been given the "<em>Add, edit, and install specialized agents</em>" permission. If you can see the Agents page but the Add Agent button isn't there, you most likely have Opal User role that lets you use Opal but does not allow to create or edit agents.</p>
<p class="article-editor-paragraph"><img src="/link/f15f4e13f7eb4e479f7bc75a2a23252d.aspx" /></p>
<h3 class="article-editor-heading">Best practices: keep each agent small</h3>
<p class="article-editor-paragraph">Before proceed with agent configuration, you need to plan what you want this agent to do and what part of the overall workflow it will handle. There is an important best practice worth remembering when doing the planning: give each agent one job, keep agents simple.</p>
<p class="article-editor-paragraph">You may be tempted to build one big agent that does everything – fetches the pages, analyses them, rewrites the content, and emails a report. Avoid doing this. Big agents are hard to maintain. They are slower and more expensive to test, because each run does more work and consumes more Opal credits. They are harder to troubleshoot, because when the result is wrong, it's not always obvious which part failed. And they are harder to improve, because any change you make carries a higher risk of breaking something that was working.</p>
<p class="article-editor-paragraph">Better approach is to break a process into individual steps and for each step decide who will handle it – a person, an external system, an existing tool, out-of-the-box Opal agent or a specialised Opal agent. Our example is a good illustration. The broad goal is "make our content perform well with AI assistants," which is a big task. But the Answer Readiness Reviewer doesn't try to own all of it. It does exactly one thing: given one page and one question, decide whether an AI could extract the answer, and suggest what would make it better. It doesn't crawl your whole site, it doesn't pick which questions matter, and it doesn't rewrite the page for you. Such agent is easy to describe, easy to test, and easy to reuse – including as one step inside a bigger workflow later.</p>
<p class="article-editor-paragraph">If this principle sounds familiar, it's because it isn't new. This is one of the things I liked about Linux when I started learning it: the idea that each program should do one thing well, and that you chain small programs together to do complex work.</p>
<p class="article-editor-paragraph">A few related habits that come from the same principle:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Define the job in 1-2 sentences before you build.</strong> If you can't, the scope could be too big and you may need to break it down further. Our example's sentence: "Given a page and a question, judge whether an AI could extract the answer, and suggest how to improve the page's chances of being cited."</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Be clear about the output.</strong> Decide upfront what the agent should return as result – plain text, a table, a file, or structured data like JSON (to pass to another agent or tool) and how that output will be used. Our example returns a short text summary a person can act on: a rating, the evidence behind it, and a list of suggested fixes.</p>
</li>
</ul>
<p class="article-editor-paragraph">Know which tools it will need. List only the tools required for that one job. Our example needs to read one web page, so it gets one tool: browse_web_html.</p>
<h2 class="article-editor-heading">Getting started</h2>
<p class="article-editor-paragraph">You can build a specialised agent completely from scratch. But there's usually a faster path, especially if you are new to this: find the existing agent that's closest to what you want and use it as a starting point. A close-enough agent already has a sensible structure – a prompt laid out in steps, the right kind of tools selected, an output format chosen. You can keep this structure and change the details, instead of trying to think of everything from scratch. The default agents in the Agent Directory are good candidates for this, and so is any agent your team has already built.</p>
<p class="article-editor-paragraph">In our example, we will use FAQ Creation agent as starting point.</p>
<p class="article-editor-paragraph">Use Duplicate Agent from the context menu to create a copy of an existing agent.</p>
<h3 class="article-editor-heading"><img src="/link/332e08be77b341c7ae715873dfa45673.aspx" /></h3>
<h3 class="article-editor-heading">Agent Configuration</h3>
<p class="article-editor-paragraph">Now that we've started creating the agent, let's look at what it's made up of.</p>
<h3 class="article-editor-heading">Name, Id, and Description</h3>
<p class="article-editor-paragraph"><strong><img src="/link/16bbe41dad80403d949075df0cb94106.aspx" width="1135" height="544" /></strong></p>
<p class="article-editor-paragraph"><strong>Name</strong> is for you and your team to understand what agent does and find it.</p>
<p class="article-editor-paragraph"><strong>Id</strong> is how the agent gets invoked — it's prefixed with @, so you'd call this one with something like <strong>@answer_readiness_reviewer</strong>. This Id must be unique, Opal checks that the Id is available and suggests alternatives if it's taken.</p>
<p class="article-editor-paragraph"><strong>Description</strong> explains what the agent does and when to use it. It's a required field. Treat it as documentation for the next person who has to maintain, troubleshoot, or reuse the agent - and this could be a future you who hasn't looked at it in six months :). A clear description also makes it easier to find the right agent when your library grows and someone needs to choose between several similar ones.</p>
<h3 class="article-editor-heading">Interaction mode</h3>
<p class="article-editor-paragraph"><strong><img src="/link/aa9afbc78ff34b0d8bf2d8f47b08fd9f.aspx" width="424" height="181" /></strong></p>
<p class="article-editor-paragraph"><strong>Support multi-turn conversation </strong>is off by default, which means the agent runs in single-shot mode: you provide the inputs, it runs once and returns a final result. There is no back-and-forth. This is the right choice for most specialised agents that handle tasks that are well-defined enough that a single run with clear inputs produces a usable output. It's also suitable for agents that are going to perform a step in a multi-step workflow. Multi-turn mode keeps the agent active in Opal Chat for continued conversation, which is better suited to tasks where you expect to refine the output through follow-up such as content draft you want to iterate on.</p>
<p class="article-editor-paragraph"><strong>Trigger from Chat</strong> controls whether people can invoke the agent directly in Opal Chat.</p>
<h3 class="article-editor-heading">Input</h3>
<p class="article-editor-paragraph"><strong>Variables.</strong> Variables are the inputs the agent collects before it runs, and they're what make an agent reusable instead of hard-coded. Each variable has a type, a name, a description, and a flag for whether it's required.</p>
<p class="article-editor-paragraph">In our example we have 2 variables – URL and Question and both are required.</p>
<p class="article-editor-paragraph is-empty"><img src="/link/ccb4b8e72cec43898f7848739ecb9edf.aspx" width="660" height="207" /></p>
<p class="article-editor-paragraph"><strong>Tools.</strong> This is where you give the agent its equipment. You can let Opal predict and add relevant tools automatically or add them manually by selecting from the tools available in your instance.</p>
<p class="article-editor-paragraph"><img src="/link/a9465742661c4650adb01ba608a46420.aspx" width="946" height="214" /></p>
<p class="article-editor-paragraph">In our example we only need one tool – <code>browse_web_html</code>. It will be used to fetch the page so agent can read page content.</p>
<p class="article-editor-paragraph"><strong>Inference level.</strong> This controls how hard Opal thinks before answering. Higher levels improve quality on complex, multi-step reasoning but take longer to run and cost more (in terms of Opal credits). You match the level to the task. In our example, I will set it to Complex, because deciding whether an answer is explicit, buried, fragmented, or missing is genuine reasoning as the agent has to understand the question, comprehend the page, and judge the relationship between them.</p>
<p class="article-editor-paragraph"><strong>Model Provider. </strong>As of June 2026, Opal allows selecting between Google Gemini or Antropic Claude as AI model provider for specialised agents. </p>
<p class="article-editor-paragraph"><strong>Files (optional).</strong> You can attach files the agent should reference every time it runs. This can be used when you have guidelines already documented in a file. Going to keep this empty for our example as all the instructions will be in the prompt.</p>
<h3 class="article-editor-heading">Writing the prompt</h3>
<p class="article-editor-paragraph">The prompt (Opal calls it the <strong>prompt template</strong>) is the agent's standing instructions, the brief it follows every single time it runs. This is where most of your effort goes, and what defines how good your agent will be.</p>
<p class="article-editor-paragraph">Optimizely guidance for prompts is very straightforward, and it matches how you'd brief a capable teammate:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Write in clear, direct language.</strong> Say what you want done, not what to "consider."</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Build a clear hierarchy.</strong> Use headers, bold text, and lists so the structure of the task is obvious.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Break the work into explicit steps.</strong> Number them. An agent following "Step 1, Step 2, Step 3" is better than unstructured wall of text.</p>
</li>
</ul>
<p class="article-editor-paragraph">A few additional prompt-writing techniques that are worth mentioning:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph">Reference variables and tools explicitly. In the prompt, variables are written in double square brackets like <code>[[PAGE_URL]]</code> and <code>[[QUESTION]]</code>, and tools are written in backticks like <code>browse_web_html</code>. This is how you wire the prompt to the inputs and equipment you configured in the other sections. <br />Spelling out when and how to use a tool rather than just making it available produces far more consistent results.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Define what to do when things go wrong.</strong> A robust prompt tells the agent how to handle not just the happy path, but also negative scenarios and edge cases. <br />In our example it could be some of these: a page that won't load (empty or returns an error), a page behind a login, content is presented as picture rather than text, a question that doesn't really relate to the page at all or a questions that is not a question but a statement.</p>
</li>
</ul>
<p class="article-editor-paragraph">If you want to get better at writing these prompts or just needs an inspiration, you can always check out prompts used in the out-of-the-box agents or check the recommendations here: <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/39300056376717-Prompts-for-specialized-agents">https://support.optimizely.com/hc/en-us/articles/39300056376717-Prompts-for-specialized-agents</a></p>
<p class="article-editor-paragraph">And another tip - you can use Opal or your favourite LLM (ChatGPT, Claude) to generate prompt for your agent or improve existing prompt - they are all quite good at writing and can give ideas for some instruction points or directions you didn't think about. Just make sure to always review the result before you use it.</p>
<p class="article-editor-paragraph">Prompt for our example agent is too big to put here but you can find it at <a class="article-editor-link article-editor-link" href="https://gist.github.com/igor-safonov/696c1a07e93e8e4f3aa446cc63348f60">https://gist.github.com/igor-safonov/696c1a07e93e8e4f3aa446cc63348f60</a></p>
<h3 class="article-editor-heading">Output</h3>
<p class="article-editor-paragraph">You select an <strong>Output Data Type</strong> from a list and you can optionally add a brief <strong>Description</strong> of what the output is.</p>
<p class="article-editor-paragraph"><img src="/link/1afe59a09e7c46e88c62a669995a720e.aspx" width="697" height="232" /></p>
<p class="article-editor-paragraph">Two important things to keep in mind:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>The detailed shape of the output is defined in the prompt, not here.</strong> Whether the response uses a table, what columns it has, what the four ratings are - all of that lives in your prompt template. The Output section just tells Opal what kind of data the response is and (optionally) describes it at a high level.</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>What the Description field is for.</strong> It's a short, plain-language summary of what the agent returns. It's most useful when the agent is later used as a step inside a workflow agent, because the next step in the workflow needs to know what shape of result it's getting. If the agent only ever runs on its own, the description is less critical, but it's still good documentation for your teammates.</p>
</li>
</ul>
<p class="article-editor-paragraph">The choice of data type usually comes down to who or what is going to consume the output. If the result will be passed to another agent or to an automated step in a workflow, <strong>JSON</strong> is the better choice - it's structured and machine-readable, and you can pin down the exact shape with an Output Schema. If the result is meant for a person to read and act on, <strong>Text</strong> is the right choice.</p>
<p class="article-editor-paragraph">In our example, the output is meant for a person, so we'll set:</p>
<ul class="article-editor-bullet-list">
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Output Data Type</strong>: Text</p>
</li>
<li class="article-editor-list-item">
<p class="article-editor-paragraph"><strong>Description</strong>: "A markdown response containing the answer-readiness rating (Explicit, Buried, Fragmented, or Missing), evidence from the page that supports the rating, and a short list of concrete suggested improvements. Returns an error template instead if the question is invalid, the page can't be read, or the question is off-topic for the page."</p>
</li>
</ul>
<p class="article-editor-paragraph">One more practice worth mentioning, even though it isn't part of the Output section itself: <strong>preferred outputs</strong>. After you've run the agent a few times, you can mark a particularly good result as a <em>preferred output</em>. Opal can then use it as an example to guide future runs, which helps tune the agent toward the style and quality you want. This is done from the agent's execution logs after the fact, not configured upfront - so you'll come back to it once the agent is built and you've seen a few real results. More details available at <a class="article-editor-link article-editor-link" href="https://support.optimizely.com/hc/en-us/articles/43244850788109-Preferred-output-examples">https://support.optimizely.com/hc/en-us/articles/43244850788109-Preferred-output-examples</a></p>
<h3 class="article-editor-heading">Testing and improving the agent</h3>
<p class="article-editor-paragraph">Building the agent is the first draft, not the finished product. You will then need to do a few rounds of testing and adjustment until you’re happy with the result.</p>
<p class="article-editor-paragraph"><strong>Run a test.</strong> Save the agent and use <strong>Test Run</strong> to try it with real inputs. For our example, that means a real page URL and a real question – ideally start with cases where you already know the answer, so you can tell whether the agent got it right.</p>
<p class="article-editor-paragraph"><strong>Build yourself a small set of known cases to test every time you make some big changes to the agent.</strong> This way you can check if baseline still works well or recent change made things worse.</p>
<p class="article-editor-paragraph"><strong>Look at what the agent did, not just what it returned.</strong> Opal keeps execution logs that show the steps the agent took and the tools it called. If the result is not what you expected, the log can help you see where it went wrong.</p>
<p class="article-editor-paragraph"><strong>Adjust one thing at a time.</strong> When something's off, the fix is usually adjusting the prompt: a rule that wasn't explicit enough, a step that needed splitting, an edge case you didn't mention. Change one thing, test it again, compare.</p>
<p class="article-editor-paragraph">Do not forget the settings can play a part too – if adjusting prompt gets you nowhere, check if inference level as well as output instructions and examples.</p>
<p class="article-editor-paragraph"><strong>Save versions as you go.</strong> Opal keeps versions of specialised agents, so you can make changes confidently and go back to a previous version anytime.</p>
<p class="article-editor-paragraph"><img src="/link/36774809d97a4a4ab7845b26e5197665.aspx" width="855" height="366" /></p>
<p class="article-editor-paragraph">Or you can just test it by calling it from Opal chat. Let's give our example agent a try and see how it goes:</p>
<p class="article-editor-paragraph"><img src="/link/0503efff9b324830a57ab9a2583afce8.aspx" width="853" height="793" /></p>
<p class="article-editor-paragraph">Looks pretty good to me :)</p>
<p class="article-editor-paragraph">And if you're worried you'll consume too many Opal credits with your agent - there is a very simple way to check how many tokens each run consumes - from agent editor go to Logs tab and it's all there.</p>
<p class="article-editor-paragraph"><img src="/link/7a75638925da4c3aa379c04553d38074.aspx" width="1247" height="463" /></p>
<p class="article-editor-paragraph">As you see, the amount of credits consumed by our agent is very reasonable which is another reminder that small agents focused on one task are easier to maintain and more cost efficient that complex do-it-all agents.</p>
<h2 class="article-editor-heading">Conclusion</h2>
<p class="article-editor-paragraph">If there's one thing to take from this, it's that building an Opal agent is mostly clear thinking written down and knowing some best practices. You define a job, describe it in clear direct language with steps by step instructions, give the agent the inputs and the tools it needs, and then test and tune it until it's reliable. The Answer Readiness Reviewer we used as example is straightforward under the hood – two main inputs, one tool, a well-structured but simple prompt. And yet it does something quite useful and something that a generic script cannot do.</p>
<p class="article-editor-paragraph">For now, the best next step is a simple one: open Opal, find the agent closest to something you'd find useful, duplicate it, and start changing it. You learn this far faster by building than by reading.</p>2026-07-23T14:34:13.0000000ZBlog post