Table of Contents

Create a New Agent

This guide describes every tab and field in the Management Portal agent editor, which you use both to create agents and to edit existing ones.

Overview

The agent editor is a tabbed form. The same editor opens when you select Create Agent on the Agents page and when you select the Edit icon for an existing agent. Some tabs appear only when you edit an existing agent or when a feature flag is enabled.

For a guided, step-by-step version of the same flow, see the Agent Creation Walkthrough.

Prerequisites

  • The Agents Contributor role on the instance (required to see the Create Agent button).
  • At least one AI model of type completion. See AI Models.
  • At least one agent workflow resource, such as the generic agent workflow.
  • (Optional) Prompts for workflow resources. See Managing Prompts.
  • (Optional) Tools in the Tool Library. See Tools.

Opening the Editor

  • To create an agent: In the sidebar, select Agents > Agents, then select Create Agent.
  • To edit an agent: On the Agents page, select the Edit icon (pencil) for the agent.

Editor Header

Element Description
Back chevron Returns to the Agents page (same as Cancel).
Mode label New when creating, Editing when editing.
Title The agent display name. Shows "New agent" until you enter a display name.
Status chip Edit mode only. ACTIVE, or DELETED for a deleted agent.
Subtitle When creating: "Complete the settings below to create and deploy your new agent." When editing: "Last Edited: [date and time] by [user]".
Create Agent / Save Changes Validates and saves the agent. Shows Save Changes in edit mode. Disabled when you don't have write permission on the agent.
Cancel Returns to the Agents page.

The buttons stay visible on every tab. When you cancel with unsaved changes, a Cancel Agent Creation (or Cancel Agent Editing) dialog asks "Are you sure you want to cancel?". Select Yes to discard your changes. When editing, the dialog appears only if you changed something.

Tabs

Tab When it appears Purpose
Basic Settings Always Display name, agent name, description, main model, max rounds, tool escalation, main workflow prompt
Agent Configuration Always Conversation history, shielding, user prompt rewrite, semantic cache, realtime speech, cost center, expiration
Sandbox Edit mode, and the FoundationaLLM.ManagementPortal.Sandbox feature flag is enabled Sandbox Configuration for the agent
Private Storage Edit mode, the FoundationaLLM.Agent.PrivateStore feature flag is enabled, and the saved agent uses an Azure OpenAI Assistants workflow or the FoundationaLLMFunctionCallingWorkflow class Agent private store files
Tools Always Tools copied from the Tool Library and the self-service tool set
Portal Experience Always Welcome message, conversation starters, and chat feature toggles
Workflow Always Workflow type, package, class, host, model parameters, workflow properties, additional resources
Security Always (content depends on mode) Access Control, virtual security group ID, agent access tokens

Feature flags are managed on the Feature Flags tab under Platform > Configuration. See Configuration.

You can open a tab directly with the tab query parameter, for example /agents/edit/my-agent?tab=workflow. Valid values are basic, configuration, sandbox, private-storage, tools, portal, workflow, and security.

Basic Settings

Field Description
Agent Display Name The name users see when they interact with the agent. Optional.
Agent name The unique resource name. Use letters, numbers, dashes, and underscores only; the field removes other characters as you type. When creating, the portal checks availability and shows ✔️ (available) or ❌ (not available; hover for the reason). The name cannot be changed after creation.
Description Helps others understand the agent's purpose. Searched by the Agents page.
Main model The workflow's main AI model. Lists AI models of type completion, shown as "Display name (name)" and sorted by display name. Selecting a model copies that model's parameters into Workflow main model parameters on the Workflow tab.
Max rounds The maximum number of tool-calling rounds, stored as max_rounds in the workflow properties. 0 or empty removes the setting, so the workflow runs a single round.
Enable tool escalation Stored as enable_tool_escalation in the workflow properties. With the FoundationaLLMFunctionCallingWorkflow class, the model first names the tools it needs, and only those tools are bound for the next pass.
What is the main workflow prompt? The agent's system prompt. Select the expand icon to edit it in the larger Main workflow prompt dialog, then select Done.

When you save, the main workflow prompt is stored as a prompt resource with the category Workflow. For a new agent, the prompt is named after the agent.

Tip: On a new agent, selecting a workflow on the Workflow tab replaces the workflow properties with that workflow's defaults. Select the workflow first, then set Max rounds and Enable tool escalation.

Agent Configuration

Each setting appears as a summary card. Select a card to edit its settings, then select Done (or the up arrow) to close it.

Conversation History

Under "Should conversations be included in the context?":

Setting Default Description
Enabled No Includes earlier messages from the conversation in the context.
Max Messages 5 The number of earlier messages to include.

Shielding

Under "How should user-agent interactions be gated?", shielding plugins screen prompts and responses. Shielding replaces the former Gatekeeper settings.

Section Description
Pre-completion plugins Screen the user prompt before the model is called.
Post-completion plugins Run against the model response before it is returned.

In each section:

  1. Select Add pre-completion plugin or Add post-completion plugin.
  2. In Select a shielding plugin, choose a plugin. The list shows plugins in the Shielding category, for example Azure Content Safety, Lakera Guard, Enkrypt Guardrails, or Presidio, when those plugins are installed.
  3. Set the plugin parameters that appear under the plugin. Select the refresh icon to reload the parameter list from the plugin.
  4. Use the up and down arrows to change the order. Plugins run in the order listed.
  5. Select the trash icon to remove a plugin.

The summary card shows the plugin names for Pre-completion and Post-completion, or None. If you open an older agent that still has Gatekeeper options, the editor converts them to the equivalent shielding plugins; saving the agent stores the shielding settings and removes the Gatekeeper settings.

To shield the output of an individual tool, use Shield tool output in the tool editor on the Tools tab.

User Prompt Rewrite

Under "Should user prompts be rewritten?":

Setting Default Description
Enabled No Rewrites the user prompt before it is processed.
Rewrite Model — The model that rewrites the prompt. Required when enabled.
Rewrite Prompt — The rewrite instructions. Type at least three characters in Search prompts by name (min 3 characters)..., then pick a prompt from the dropdown. Required when enabled.
Rewrite Window Size 3 The number of user prompts to consider. Required when enabled.

Semantic Cache

Under "Should semantic cache be used?":

Setting Default Description
Enabled No Returns cached responses for semantically similar prompts.
Model — The model used for cache embeddings. Required when enabled.
Embedding Dimensions 2048 The embedding vector size.
Minimum Similarity Threshold 0.97 The similarity score a cached entry must reach to be used. Required when enabled.

Realtime Speech Configuration

This card appears only when the FoundationaLLM.Preview feature flag is enabled. See Enabling Realtime Speech.

Setting Default Description
Enabled No Turns on realtime speech for the agent.
Model — An AI model of type realtime-speech. Required when enabled.
Stop Words (comma-separated) stop, end conversation, goodbye Phrases that end the voice session.
Voice alloy One of alloy, ash, ballad, coral, echo, sage, shimmer, verse.
Speech Detection Threshold 0.50 0 to 0.99. Higher values reduce noise-triggered interruptions.
Silence Duration (ms) 500 100 to 3000 in steps of 50. Longer values reduce choppy end-of-turn behavior.
Allow Barge-in Yes Lets the user interrupt the agent's spoken response.
Show Transcriptions Yes Shows transcriptions of the voice exchange.
Include Conversation History Yes Includes conversation history in the voice session.

Cost Center and Expiration

Field Description
Would you like to assign this agent to a cost center? Optional cost center name.
Would you like to set an expiration on this agent? Optional expiration date (date picker).

Sandbox

Appears only in edit mode when the sandbox feature flag is enabled.

  1. In Sandbox Configuration, select a published Sandbox Configuration.
  2. The Effective published references section shows the selected configuration, sandbox class, and sandbox policy, each with its revision.

New sandboxes for the agent use the selected configuration's class, policy, and settings. Existing sandboxes keep their configuration snapshot. The selection is saved when you save the agent. See Sandboxes.

Private Storage

Appears only in edit mode when the agent private store feature flag is enabled and the saved agent uses an Azure OpenAI Assistants workflow or the FoundationaLLMFunctionCallingWorkflow class. Use Upload Files to add files to the agent's private store, the refresh icon to reload the file list, and the trash icon to delete a file. See Private Storage.

Tools

The Tools tab manages the agent's own copies of tools from the Tool Library. Changing an agent tool does not change the Tool Library. For full details on tool families, tool sets, and the tool editor, see Tools.

Element Description
Self-service tool set Optional tool set associated with the agent for self-service editing. Defaults to None.
Add Tool Opens the Add Tool to Agent: [agent name] dialog.
Tools available to the agent Table with Name, Type, and Actions (Edit and Remove).

Adding a tool

  1. Select Add Tool.
  2. Search with Search tools and sets... or browse the Tool Library, which groups tools by family.
  3. Select Select next to a tool, then select Add to Agent.
  4. The Edit Agent Tool: [tool name] dialog opens. Review the settings, then select Save changes.

The dialog's More options section also offers:

  • Copy from another agent — a three-step wizard that copies tools from an existing agent.
  • Add Tool Set — lists the tool sets; select Add set to copy all tools in a set.

Editing an agent tool

The Edit Agent Tool dialog contains these sections, depending on the tool:

Section Contents
Basics Name (the name the agent uses to invoke the tool; must be unique on the agent) and Description.
Connection MCP tools only: inline URL or registered endpoint.
Resource References The models, prompts, data pipelines, and knowledge resources the tool uses, for example Main Model, Main Prompt, and Router Prompt. The Main Model reference also has a Temperature field.
Content Safety Shield tool output and the Shielding plugin to use.
Settings Tool-specific properties.
Arguments (read-only) The arguments the tool accepts.

To remove a tool, select its trash icon and confirm Remove in the Remove Tool dialog. Tool changes are saved when you save the agent.

Portal Experience

Welcome message

A rich text editor for the message shown when a user starts a new conversation with the agent. If you leave it empty, the default welcome message is shown.

Conversation Starters

Select the Conversation Starters card to edit suggested starters shown to users at the start of a conversation.

  1. Select Add Starter.
  2. Enter a Title and the Content (the message sent to the agent).
  3. Drag rows to reorder them. Select the trash icon to remove a starter.
  4. Select Done.

Experience toggles

Each row has two toggles. The first sets the feature for the agent. The second, under the Edit in Agent Portal? column, controls whether that setting can be changed when the agent is edited in the Agent Portal.

Setting Default Edit in Agent Portal? default
Would you like to show the message tokens? Yes Yes
Would you like to allow the user to rate the agent responses? Yes Yes
Would you like to allow the user to see the message prompts? Yes Yes
Would you like to allow the user to upload files? No Yes
Would you like to show content artifacts in messages? Yes Yes
Would you like to show the operation identifier on agent messages? No Yes

When you open an agent that has no stored Agent Portal selection, every Edit in Agent Portal? toggle shows Yes.

Workflow

Selecting a workflow

Under "What workflow should the agent use?", select a workflow. The list contains the instance's agent workflow resources, by name (for example GenericAgentWorkflow). After you select a workflow, the configuration fields appear below the dropdown.

When you create an agent, selecting a workflow fills in defaults:

  • Workflow host is taken from the workflow resource.
  • The workflow properties are replaced with the workflow resource's properties.
  • For the generic agent workflow, Workflow name defaults to Agent-Workflow, Workflow package name defaults to foundationallm_agent_plugins when that package is installed, and Workflow class name defaults to the first workflow class in the selected package.
  • For LangChain workflow types, the package defaults to foundationallm_agent_plugins_langchain with the matching LangChain workflow class.
  • For other workflows, Workflow name and Workflow class name default to the workflow resource name.

Workflow fields

Field Description
Workflow name A name for this workflow configuration. Required.
Workflow package name For the generic agent workflow, a dropdown of Python plugin packages that declare a module name. For other workflows, a text field. Required.
Workflow class name For the generic agent workflow, a dropdown of the workflow classes declared by the selected package (for example FoundationaLLMFunctionCallingWorkflow). For other workflows, a text field.
Workflow host The orchestration host. LangChain is the only option. Required.
Workflow main model parameters Parameter overrides for the main model on the workflow. Prefilled from the main model's own parameters when you select it on Basic Settings. Select the add icon to open Create Property (Property Key, Property Type: String, Number, Boolean, or Object / Array, Property Value).
Workflow properties Other workflow properties. max_rounds and enable_tool_escalation are managed on Basic Settings and are not listed here.
Additional workflow resources Extra resources the workflow uses, such as router, files, and final prompts.

For model-specific parameter guidance (for example, Claude Sonnet 5 thinking and effort), see AI Models.

Adding a workflow resource

  1. Next to Additional workflow resources, select the add icon (Add Workflow Resource).
  2. In the Add Resource dialog, select a Resource Type: AI Model, API Endpoint, Azure AI Project, Data Pipeline, Knowledge Source, Knowledge Unit, Prompt, or Vector Database.
  3. For prompts, type at least three characters in Search prompts by name.... Only prompts with the Agent Workflow category are listed.
  4. Select the Resource.
  5. Enter the Resource Role, for example router_prompt, files_prompt, or final_prompt.
  6. Select Save.

Use the edit and delete actions in the resources table to change or remove a resource. Deleting asks for confirmation in the Delete Workflow Resource dialog.

Security

Element When it appears Description
Access Control Edit mode Opens the Access Control dialog with Agent and Prompt tabs, for role assignments on the agent and on its main workflow prompt.
Virtual security group ID When the agent has one Read-only. Select the copy icon to copy it to the clipboard.
Agent access tokens When the agent has a virtual security group ID Table of tokens (Description, Expiration Date, Delete). Select the add icon to open Create Access Token, enter a Token description and Token expiration date, then select Save. The key is shown once in View Access Token Details; store it safely.

See Access Control and Agent Access Tokens.

Saving the Agent

Select Create Agent (or Save Changes). The editor validates the form first. If a check fails, the message appears under the field and the editor switches to the tab that contains the first error.

Check Message
Agent name is empty Please give the agent a name.
Agent name is not available The reason returned by the name check
No main model Please select an AI model for the workflow.
Main workflow prompt is empty Please provide a system prompt.
No workflow selected Please select a workflow.
Workflow name is empty Please provide a workflow name.
Workflow package name is empty Please provide a workflow package name.
No workflow host Please select a workflow host.
User prompt rewrite enabled without a model, prompt, or window size Please select a model for the user prompt rewrite. / Please select a prompt for the user prompt rewrite. / Please input a window size for the user prompt rewrite
Semantic cache enabled without a model or threshold Please select a model for the semantic cache. / Please input the minimum similarity threshold for the semantic cache.

After a successful save:

  • New agent: the message "Agent "[name]" was successfully created!" appears and the portal returns to the Agents page.
  • Existing agent: the message "Agent "[name]" was successfully updated!" appears, you stay in the editor, and the subtitle shows the new last-edited time.