Create a specialized agent
Specialized agents are custom agents you configure to perform specific tasks in Optimizely Opal. An agent's behavior is determined by its prompt template (guidelines it follows), tools (actions it can take), variables (inputs provided at runtime), and skills (reusable directions it can apply). The Quality tab handles quality scoring and runtime safeguards for your agent.
Create a specialized agent when you want something that completes a single, well-defined task. For information on each component and when to use each option, see Specialized agents fundamentals and best practices.
Access your agents
- Go to home.optimizely.com.
- Select your organization.
- Click Opal.
- Click Agents.
- Select the Your Agents tab.
Initial configuration
Complete the following steps to name and describe your specialized agent.
- Follow the steps in the Access your agents section.
- Click Add Agent.
- Select Specialized Agent.
- Enter a Name.
- Enter a unique Id. The Id (prefixed with @) invokes the specialized agent. Ensure the Id displays as Available. If the Id is already in use, Opal suggests a few available options instead. Click a suggestion to autofill the Id field.
- Add a Description.
Configure interaction mode
Specialized agents support two interaction modes, single-turn and multi-turn, each described in the following configuration steps:
- Toggle Support multi-turn conversation on or off. Default is Off. Single-turn agents run once and return a result. Multi-turn agents remain active for continued back-and-forth conversation.
- On – Multi-turn mode. The agent stays active in Opal Chat for follow-up conversation.
- Off – Single-turn mode. The agent runs once and returns a final result.
- Toggle Trigger from Chat on or off. Default is On.
- On – The agent is visible in Opal Chat and available to invoke.
- Off – The agent does not display in Opal Chat and users cannot invoke it from there. It is still available in workflow agents.
Configure the prompt template
The prompt template defines the instruction set the specialized agent applies every time it runs.
- Enter your Prompt Template. For guidance on structuring your prompt, see Prompt details for specialized agents.
- If you toggled Support multi-turn conversation on, expand Multi-turn Conversation Settings.
- (Optional) Update the System Prompt.
- Set the Memory Token Limit (the maximum amount of conversation history the agent retains) by moving the slider or entering a value. For guidance on which limit to choose, see Specialized agents fundamentals and best practices.
Define input variables (optional)
Note
When you invoke a multi-turn agent in chat, Opal collects your Variables first. Opal then injects those values into your prompt template to start the conversation.
For information on variables, see Specialized agents fundamentals and best practices. To create variables, complete the following:
- Click Add Variable.
- Select the Type (String, Boolean, Number, Datetime, Object, or File).
- Toggle Accept multiple values on to let users add multiple values for a single variable. This is helpful for array and list inputs for batch operations or multi-file workflows.
- Enter or use the arrows to select the Minimum items. If you select Required?, the Minimum items must be at least one.
- (Optional) Enter or use the arrows to select the Maximum items. Leave this empty for no upper limit.
- Enter a Name. Variable names are case-insensitive and cannot be duplicated.
- Add a Description.
- (Optional) Select Required? if users must provide this variable each time the specialized agent runs.
- Click Save variable.
Variables not referenced in the prompt display a Not in use message.
If you try to Save the specialized agent with variables still not in use, an alert displays. Save the specialized agent anyway, or return to the prompt and add the variable.
Define tools (optional)
If you referenced tools in the prompt without adding them to the agent, add them automatically or manually.
Automatically
Select Enable automatic tool prediction to let Opal predict and add relevant tools based on user queries and conversation history.
Opal merges predicted tools with manually configured tools.
Manually
To manually select which tools the agent can use, complete the following steps:
- Click Add tool.
- (Optional) Click a tool to see its description.
- Select the checkboxes for the tools you referenced.
- (Optional) Select the checkbox next to a section heading to add all tools in that section.
- Click Add selected.
For information on tools, see Tools overview.
Skills (optional)
Skills are reusable instructions Opal can apply to your agent at runtime. The specialized agents work with organization skills only. Personal skills cannot be added to agents. You can let Opal select organization skills automatically, insert specific ones yourself, or do both.
- To let Opal apply organization skills that match your prompt, select Automatically select skills matching the prompt.
- To let Opal apply organization skills that match your agent's tools, select Automatically select skills matching the tools.
- To insert a specific organization skill yourself, enter / (or { in the Prompt Template and select Choose skills from the drop-down list. The picker lists organization skills that have a shortcut.
Automatic selection depends on how your skills are configured. Test the agent after enabling automatic options so you can confirm the skills Opal applies match your intent, particularly for prompt-based selection. For most agents, Automatically select skills matching the tools is the safer of the two automatic options to enable.
See the Skills.
Configure additional settings
Enable private executions (optional)
Select Private executions to restrict the logs, outputs, and run details of every execution to the user who triggered it. Other users with access to the agent still see that it ran in the agent logs, but with content locked.
Good to know
- This setting applies per agent, not per execution. Selecting it governs every future run until you clear it.
- Agent sharing permissions are unchanged. Private executions controls who sees run content, not who can access or edit the agent.
- Instance administrators cannot view a private execution's contents through normal access.
This setting controls the agent's default privacy. Regardless of this setting, you can still make an individual run private without changing the agent's default:
- Test Run – Turn on Run this agent as private execution before you click Run. If Private executions is already selected, Test Run displays a note informing the user that this agent already runs privately by default.
- @mention in Opal Chat – Click Run this agent as private execution when you @mention this agent. Opal Chat confirms with Private execution on – This run is private to you. This control displays only after you clear Private executions for the agent. When the setting is selected, every run is already private, so the icon does not display.
A private run stays private, even if you later clear Private executions for the agent.
If a workflow itself runs as a private execution, every agent step inside it runs privately, regardless of this setting.
Configure personal context and working directory (optional)
These settings personalize the agent's responses using the invoking user's saved preferences. They also control where the agent reads and writes files during a run.
- Toggle Enable personal context on or off. Default is Off.
- On – The agent uses the invoking user's personal AGENTS.md and MEMORY.md files, injected into its system prompt. This lets the agent tailor its responses to the user's preferences and prior interactions. Enable this option for personal-assistant-style agents. See Personal files overview for information.
- Off – The agent does not use any user-specific personal context. Use this default for generic, user-independent agents.
- Select the working directory root, labeled CWD.
- /workspace – A thread-scoped scratch directory the agent uses for file operations, such as code execution output. No personal files load into the prompt. This is the default if you leave CWD unset.
- /context – The user's personal-context tree. Requires Enable personal context. Optionally add a sub-path (for example, agents/support) to scope the agent to a specific area of personal context.
Note
The CWD configured here is a default. A parent workflow, primitive, or external caller that specifies its own CWD overrides this default for that run.
When you enable Enable personal context, Opal displays a preview of the files that load into the system prompt. The preview also displays where the agent writes its memory.
Select the LLM Provider
The LLM provider determines which AI model family the agent uses to generate responses. By default, an agent inherits the provider configured for your Opal instance in Settings > Chat. Select a provider here to override that default for this agent only.
Each provider has different strengths:
- Google Gemini – Fast, cost-effective responses and creative writing.
- Anthropic Claude – Complex tool orchestration and code generation.
To select the LLM provider for the agent, follow these steps:
- Click the LLM Provider drop-down list.
- Select a provider.
Select the inference level
The inference level controls which AI model Opal uses and how deeply the model reasons before responding. Higher inference levels pair more powerful models with deeper thinking to produce higher-quality output, but take longer and use more credits. Lower levels respond faster and use fewer credits, making them ideal for straightforward tasks. See Inference level.
To set the inference level for the agent, follow these steps:
- Click the Inference Level drop-down list.
- Select an Inference Level.
Add files (optional)
Upload files in the Files section for the specialized agent to reference each time you invoke it. For example, files can include an output template or data the specialized agent needs to reference.
- Expand the Files section.
- Click Add File.
- Select the relevant files from your computer.
- Click Upload.
Note
Multi-turn specialized agents support one file in the Files section.
Configure output
Specify the format of the output the specialized agent returns.
- Expand the Output section.
- Select the Output Data Type.
- (Optional) Enter a Description explaining the expected output of the prompt. The output description is useful when you use this agent within a workflow agent.
- (Optional) Enter the JSON schema for the output in the Output Schema field, if you selected JSON as the Data Type in step 2.
Save and test
Save the agent to finish creating it, then run an optional test to verify the configuration.
- Click Save to create your specialized agent.
- (Optional) Click Test Run to test your specialized agent. See Test an agent.
Your specialized agent is ready to use.
Configure quality evaluation (optional)
After you create the agent, configure output evaluation and runtime safeguards on the Quality tab. See Quality tab overview for details on Output Evaluation, Execution Guardrails, and Execution Advisor.
Share your agent (optional)
See Share agents and manage visibility to give other users access or make the agent available to your organization.
Next steps
- See Manage specialized agents for information on editing and deleting agents.
- See Prompt details for specialized agents for guidance on structuring your prompt.
- See Default agents overview for a list of agents automatically available in your Opal instance.
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.