---
title: Create a specialized agent
slug: agent-platform/docs/create-a-specialized-agent
docTags: 
createdAt: 2026-08-12T15:37:09.000Z
---

Specialized agents are custom agents you configure to perform specific tasks in Agent Platform. 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](docId\:bDeUnJYXOZjhodVf7vcxg).

## Access your agents

1. Go to [home.optimizely.com](https://home.optimizely.com).
2. Select your organization.
3. Click **Mark**.

   ![Screenshot of the Optimizely World Organization page where Mark is one of the quick link tiles](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/IJp9Lul9HZT1dGYaFbve4_mark-card-on-welcome-back-page0.png)
4. Click **Agents**.

   ![Screenshot of the Mark left menu where the Agents option displays](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/rq62wY7Qz3MLcZ5wzhi5d_mark-chat-reusables-agents-menu-item0.png)
5. Select the **Your Agents** tab.

   ![Screenshot of Agents where the Your Agents tab displays](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/6aS1CBibkuJv4Ya7nB1Y3_mark-chat-reusables-agents-your-agents-tab0.png)

## Initial configuration

Complete the following steps to name and describe your specialized agent.

1. Follow the steps in the [Access your agents](docId\:tZPJWDyE1GSB-epLsUh5S) section.
2. Click **Add Agent**.
3. Select **Specialized Agent**.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/GWDvj9WFjVoN4q3TnM9Vi_select-agent-type.png" size="100" isUploading="false" position="center" width="2198" height="804" darkWidth="2198" darkHeight="804" showCaption="false" indent="1"}

4. Enter a **Name**.
5. 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, Mark suggests a few available options instead. Click a suggestion to autofill the **Id** field.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/cMkfjN7jVJ2KGDPbClCJV_ensure-agent-is-available.png" size="100" isUploading="false" position="center" width="1530" height="600" darkWidth="1530" darkHeight="600" showCaption="false" indent="1"}

6. Add a **Description**.

### Configure interaction mode

Specialized agents support two interaction modes, single-turn and multi-turn, each described in the following configuration steps:

1. 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 [Mark chat](docId\:dtNBEttEGVvkhNkwNypLM) for follow-up conversation.
   - **Off** – Single-turn mode. The agent runs once and returns a final result.
2. Toggle **Trigger from Chat** on or off. Default is **On**.
   - **On** – The agent is visible in Mark chat and available to invoke.
   - **Off** – The agent does not display in Mark chat and users cannot invoke it from there. It is still available in [workflow agents](docId\:KWaI2TBwD38sN7p74exoy).

     ::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/EfqMzy3qcdPDy7rObXBhi_interaction-mode.png" size="60" isUploading="false" position="center" width="416" height="216" darkWidth="416" darkHeight="216" showCaption="false"}

## Configure the prompt template

The prompt template defines the instruction set the specialized agent applies every time it runs.

1. Enter your **Prompt Template**. For guidance on structuring your prompt, see [Prompt details for specialized agents](docId:9pdZe9-mheIMGp0NsjdkX).
2. If you toggled **Support multi-turn conversation** on, expand **Multi-turn Conversation Settings**.
   1. (Optional) Update the **System Prompt**.
   2. 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](docId\:bDeUnJYXOZjhodVf7vcxg).

### Define input variables (optional)

:::hint{type="info"}
**Note**

When you invoke a multi-turn agent in chat, Mark collects your **Variables** first. Mark then injects those values into your prompt template to start the conversation.
:::

For information on variables, see [Specialized agents fundamentals and best practices](docId\:bDeUnJYXOZjhodVf7vcxg). To create variables, complete the following:

1. Click **Add Variable**.
2. Select the **Type** (**String**, **Boolean**, **Number**, **Datetime**, **Object**, or **File**).
3. 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.
4. Enter a **Name**. Variable names are case-insensitive and cannot be duplicated.
5. Add a **Description**.
6. (Optional) Select **Required?** if users must provide this variable each time the specialized agent runs.
7. Click **Save variable**.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/ZPa004oWvSE7TRfGd3ctm_add-variable.png" size="100" isUploading="false" position="center" width="1140" height="820" darkWidth="1140" darkHeight="820" showCaption="false" indent="1"}

Variables not referenced in the prompt display a **Not in use** message.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/3tQQU7G2yVKLbAtDCmWkB_variable-not-in-use.png)

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 Mark predict and add relevant tools based on user queries and conversation history.

![](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/3J1-Oc158tPTjoN--men__enable-auto-tool-prediction.png)

Mark merges predicted tools with manually configured tools.

**Manually**

To manually select which tools the agent can use, complete the following steps:

1. Click **Add tool**.
2. (Optional) Click a tool to see its description.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/Sw2papjU5ndqnlsW7qGdK_add-tools-manually.png" size="100" isUploading="false" position="center" width="919" height="471" darkWidth="919" darkHeight="471" showCaption="false" indent="1"}

3. Select the checkboxes for the tools you referenced.
4. (Optional) Select the checkbox next to a section heading to add all tools in that section.
5. Click **Add selected**.

For information on tools, see [Tools overview](docId:-j4zNs-l3kIKD0n58bVPt).

### Skills (optional)

[Skills](docId:1HTjxW2J-ZOkYEZMwnasU) are reusable instructions Mark can apply to your agent at runtime. The specialized agents work with [organization skills](docId\:N3n_NnF8J0Ykujmp2Sg00) only. [Personal skills](docId\:us7iZ6Rvo_03yXtLw_vdr) cannot be added to agents. You can let Mark select organization skills automatically, insert specific ones yourself, or do both.

- To let Mark apply organization skills that match your prompt, select **Automatically select skills matching the prompt**.
- To let Mark 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.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/4a4kyQET7ywyaQ8Phiqiu_include-skill-in-prompt-template.png" size="100" isUploading="false" position="center" width="1516" height="728" darkWidth="1516" darkHeight="728" showCaption="false" indent="1"}

Automatic selection depends on how your skills are configured. Test the agent after enabling automatic options so you can confirm the skills Mark 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](docId:1HTjxW2J-ZOkYEZMwnasU).

## 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](docId\:rHBhJmLiQvmx9789rso0n), but with content locked.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/DcFigU3jYAihq5PW94xxG_screenshot-2026-09-30-at-41529-pm.png" alt="Screenshot of the Private executions toggle in the specialized agent settings panel" size="50" isUploading="false" position="center" showCaption="false"}

**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 Mark chat** – Click **Run this agent as private execution** when you `@mention` this agent. Mark 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.

1. 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](docId:9zEIcJxiAxixeYL1C3hIG) for information.
   - **Off** – The agent does not use any user-specific personal context. Use this default for generic, user-independent agents.
2. 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.

:::hint{type="info"}
**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**, Mark 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 Mark 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:

1. Click the **LLM Provider** drop-down list.
2. Select a provider.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/qrHBugeopNDHYNqnDRutT_select-llm-provider.png" size="60" isUploading="false" position="center" width="530" height="438" darkWidth="530" darkHeight="438" showCaption="false" indent="1"}

### Select the inference level

The inference level controls which AI model Mark 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](docId\:U8woFQDDL-TVTM7gogq7b).

To set the inference level for the agent, follow these steps:

1. Click the **Inference Level** drop-down list.
2. Select an **Inference Level**.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/pIuRXjQBXCuZqz5Lh2mYX_select-inference-lvel.png" size="70" isUploading="false" position="center" width="510" height="678" darkWidth="510" darkHeight="678" showCaption="false" indent="1"}

## 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.

1. Expand the **Files** section.
2. Click **Add File**.
3. Select the relevant files from your computer.
4. Click **Upload**.

:::hint{type="info"}
**Note**

Multi-turn specialized agents support one file in the **Files** section.
:::

See [Supported file types in Mark](docId\:YYVLgm6QM2za-Mrx3kOQU).

## Configure output

Specify the format of the output the specialized agent returns.

1. Expand the **Output** section.
2. Select the **Output Data Type**.
3. (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](docId:2HD0fUsIsfdek516VtN9l).
4. (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.

1. Click **Save** to create your specialized agent.
2. (Optional) Click **Test Run** to test your specialized agent. See [Test an agent](docId\:SSeNiblVMXwVvDR_lhtvI).

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](docId\:RyEJ8-_Fwgaw2WxYQKt1g) for details on Output Evaluation, Execution Guardrails, and Execution Advisor.

## Share your agent (optional)

See [Share agents and manage visibility](docId\:laxzyBnBQE8VCkD7f6-qu) to give other users access or make the agent available to your organization.

## Next steps

- See [Manage specialized agents](docId\:cFB_b7jzgV6k0Ry_cVXSS) for information on editing and deleting agents.
- See [Prompt details for specialized agents](docId:9pdZe9-mheIMGp0NsjdkX) for guidance on structuring your prompt.
- See [Default agents overview](docId\:mCCl_y-hNkhT-uKIXvReF) for a list of agents automatically available in your Mark instance.

:::hint{type="info"}
**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 applications](docId\:X5U0kKD2azV5cIdNqwGNj).
:::