Build Your First AI Agent

What you will build

By the end of this tutorial, you will have:

• Defined a clear purpose for a custom Opal agent
• Written structured instructions that guide agent behavior
• Configured tools and input variables
• Tested and evaluated agent output quality
• Deployed the agent for your organization to use

This tutorial builds a “Product Description Writer” agent as an example. You can substitute your own use case at every step.

Before you start

undefined May 2025+

Opal Agent Builder requires Opti ID authentication. Your administrator must grant you the Opal Administrator or Agent Builder role before you can create agents.

Ensure you have:

• Opal access — Log into home.optimizely.com, select your organization, and confirm you see the Opal option
• Agent Builder role — Ask your admin to verify your role in Opti ID if the Create Agent button does not appear
• A repeatable task — Identify a task your team performs repeatedly that follows a consistent pattern (content drafting, data summarization, campaign briefs, etc.)

Step 1: Define your agent’s purpose

Every effective agent solves a specific, repeatable problem. Vague agents produce vague results.

Write a one-sentence purpose statement for your agent:

“This agent generates product descriptions for e-commerce pages using our brand voice, target audience data, and a list of product features.”

What makes a good purpose statement:

• Names the specific output (product descriptions, not “content”)
• Identifies the inputs it needs (brand voice, audience, features)
• Scopes the domain (e-commerce pages, not all marketing)

Expected result: A clear sentence you can use as the agent’s description in the next step.

Step 2: Choose the agent type

Opal supports two custom agent types. Choose based on your task complexity:

Agent type	Best for	Example
Specialized agent	Single-step tasks with defined inputs and outputs	Generating a product description from feature data
Workflow agent	Multi-step processes that chain actions together	Generating a description, creating a CMS draft, and scheduling review

For your first agent, start with a specialized agent. You can upgrade to a workflow agent after mastering the basics.

1. Navigate to Opal > Agents
2. Click Create Agent
3. Select Specialized Agent
4. Enter the name (e.g., “Product Description Writer”)
5. Paste your purpose statement into the Description field

Expected result: A new agent draft appears with your name and description.

Step 3: Write your instructions

Instructions define how the agent behaves. Think of them as detailed guidance you would give a skilled team member on their first day.

Structure your instructions with four sections:

## Objective
You generate product descriptions for e-commerce pages. Each description
must be 150-200 words, highlight three key benefits, and end with a
call to action.

## Process
1. Read the product name, features, and target audience
2. Identify the three strongest benefits from the feature list
3. Write the description in our brand voice: conversational, confident,
   jargon-free
4. End with a clear call to action using the provided CTA text

## Output Format
Return the description as plain text with:
- A compelling opening sentence (under 20 words)
- Three benefit paragraphs (2-3 sentences each)
- A closing call to action

## Constraints
- Never mention competitor products by name
- Never make unverified claims about performance metrics
- Keep reading level at grade 8 or below
- Do not use exclamation marks more than once

Paste your instructions into the Instructions field.

Expected result: The instructions field contains your structured guidance covering objective, process, output format, and constraints.

Step 4: Configure tools

Tools give your agent the ability to interact with Optimizely products and external data. Select only the tools your agent needs — fewer tools mean more predictable behavior.

1. In the agent editor, click Tools
2. Review the available tools and enable only those relevant to your agent’s purpose
3. For a product description agent, consider:
   • Content generation — Core text generation capability
   • Web search — If the agent needs to research competitor positioning or industry trends
   • Image generation — If descriptions should include AI-generated product visuals

Principle of least privilege: If the agent does not need a tool to accomplish its purpose, do not enable it. Each additional tool increases the possible ways the agent can respond, which makes output harder to predict.

Expected result: Only the tools your agent needs are enabled. Unrelated tools remain disabled.

Step 5: Set input variables

Input variables are placeholders for information that changes with each request. They turn a static set of instructions into a reusable template.

1. Click Input Variables in the agent editor
2. Add variables that match the placeholders in your instructions:

Variable name	Description	Example value
product_name	The name of the product	”Ergonomic Standing Desk Pro”
key_features	Comma-separated list of features	”Height adjustable, bamboo surface, cable management”
target_audience	Who the description is for	”Remote workers aged 25-45”
cta_text	Call to action text	”Shop Now”

3. Mark required variables — the agent will prompt users for these if not provided

Expected result: Your agent lists the input variables with descriptions. When users invoke the agent, they see prompts for each variable.

Step 6: Test in Chat

Before deploying, test your agent in Opal Chat to verify it produces the output you expect.

1. Navigate to Opal > Chat
2. Click Mention Agent or type @ProductDescriptionWriter
3. Provide test inputs:

@ProductDescriptionWriter
Product name: Ergonomic Standing Desk Pro
Key features: Height adjustable from 28-48 inches, sustainable
bamboo surface, integrated cable management tray, anti-fatigue mat
included
Target audience: Remote workers aged 25-45
CTA: Shop Now

4. Review the output against your instructions:

   • Is it 150-200 words?
   • Does it highlight three benefits?
   • Does it end with the CTA?
   • Is the tone conversational and jargon-free?

5. Run at least three different test inputs to check consistency

Expected result: The agent produces output that follows your instructions across multiple test inputs.

Step 7: Evaluate quality

Subjective review is a start, but structured evaluation catches issues you might miss.

1. Navigate to Opal > Agents > Your Agents
2. Select your agent and click the Evaluations tab
3. Create an evaluation set with 3-5 example inputs and your preferred outputs
4. Run the evaluation to see how the agent’s actual output compares to your expectations
5. Review the quality scores for each test case

What to evaluate:

• Accuracy — Does the output reflect the inputs correctly?
• Format compliance — Does it follow your specified structure?
• Constraint adherence — Does it respect your rules (no competitors, reading level)?
• Consistency — Do similar inputs produce similarly structured outputs?

Expected result: An evaluation report showing quality scores across your test cases.

Step 8: Refine your instructions

Use evaluation results to improve your instructions. Common refinements include:

• Too verbose? Add a word count constraint: “Keep the total description under 200 words”
• Missing structure? Add explicit format markers: “Begin with ‘Introducing [product_name]’”
• Inconsistent tone? Add tone examples: “Write like a knowledgeable friend, not a salesperson”
• Ignoring constraints? Move constraints to the top of the instructions — models pay more attention to content that appears early

After each change, re-run your evaluations to confirm the scores improve.

Expected result: Improved evaluation scores after instruction refinements. Repeat this step until quality meets your standards.

Step 9: Deploy to your organization

When the agent meets your quality bar, publish it so your team can use it.

1. Navigate to Opal > Agents > Your Agents
2. Select your agent and click More (…) > Publish
3. Configure access:
   • All users — Everyone in your organization can use the agent
   • Specific roles — Only users with certain Opti ID roles can access it
4. Add usage guidance in the agent description so team members understand when and how to use it
5. Click Publish

Expected result: The agent appears in the Agent Directory for authorized users. Team members can mention it in Chat.

Step 10: Monitor usage

After deployment, track how the agent is used and whether it continues to meet quality standards.

1. Navigate to Opal > Agents > Your Agents

2. Select your agent and click the Logs tab

3. Review:

   • Execution count — How often the agent is used
   • Credit consumption — How many credits each execution costs
   • User feedback — Thumbs up/down ratings from team members
   • Output samples — Spot-check recent outputs for quality drift

4. Schedule a monthly review to refine instructions based on real usage patterns

Expected result: A dashboard showing agent usage, credit consumption, and quality signals. Use this data to iterate on your agent over time.

What you built

You now have a deployed Opal agent that:

• Solves a specific, repeatable task for your team
• Follows structured instructions with clear constraints
• Accepts input variables for flexible, reusable operation
• Has been tested and evaluated for quality
• Is accessible to your organization through Opal Chat

What to do next

• Build a workflow agent — Chain multiple agents together for multi-step processes
• Configure RAG — Connect your agent to your content library for context-aware responses
• Set up ongoing evaluations — Automate quality monitoring with scheduled evaluation runs
• Explore the Agent Directory — Install pre-built agents for common use cases

📝 Check your understanding 2 questions

Related content

Continue your journey with these related pages.

📖Understand the concepts

• Opal AI Platform
• Opal Chat and Canvas

🔧Follow a guide

• Build Custom Agents
• Configure Instructions
• Manage Tools
• Set Up AI Evaluations