Table of Contents

Agent Creation UX Walkthrough

A step-by-step walkthrough of creating an agent in the Management Portal, tab by tab.

Overview

This walkthrough follows the agent editor in the order most people fill it in. It focuses on what to do and what to expect at each step. For a complete description of every field, default, and validation message, see Create a New Agent.

Prerequisites

  • The Agents Contributor role on the instance.
  • At least one AI model of type completion. See AI Models.
  • (Optional) Workflow prompts such as a router prompt. See Managing Prompts.
  • (Optional) Tools in the Tool Library. See Tools.

Step 1: Open the Editor

  1. Sign in to the Management Portal.
  2. In the sidebar, select Agents > Agents.
  3. Select Create Agent at the top right.

The editor header shows New and the placeholder title "New agent". Create Agent and Cancel stay at the top right on every tab.

Step 2: Choose the Workflow First

Open the Workflow tab before filling in Basic Settings. On a new agent, selecting a workflow resets the workflow properties (including Max rounds and Enable tool escalation) to the workflow's defaults.

  1. Under "What workflow should the agent use?", select a workflow, for example GenericAgentWorkflow.
  2. Review the fields that appear:
    • Workflow name — defaults to Agent-Workflow for the generic agent workflow.
    • Workflow package name — for the generic agent workflow, pick a Python plugin package (defaults to foundationallm_agent_plugins when installed).
    • Workflow class name — pick a workflow class from the selected package, for example FoundationaLLMFunctionCallingWorkflow.
    • Workflow host — LangChain.
  3. If the workflow needs extra prompts, add them under Additional workflow resources:
    1. Select the add icon.
    2. In Add Resource, set Resource Type to Prompt.
    3. Type at least three characters to search, then select the prompt. Only Agent Workflow prompts are listed.
    4. Enter the Resource Role, for example router_prompt.
    5. Select Save.

The FoundationaLLMFunctionCallingWorkflow class requires a router_prompt resource. A files_prompt and a final_prompt are optional.

Step 3: Basic Settings

  1. Enter an Agent Display Name, for example Sales Assistant. The editor title updates as you type.
  2. Enter an Agent name, for example sales-assistant. Use letters, numbers, dashes, and underscores. Wait for ✔️ (available). If ❌ appears, hover over it to see why and choose another name. You cannot change this name later.
  3. Enter a Description.
  4. Select the Main model. The model's parameters are copied into Workflow main model parameters on the Workflow tab.
  5. Set Max rounds if the workflow should call tools across several rounds. Leave it at 0 for a single round.
  6. Select Enable tool escalation if the model should first name the tools it needs before they are bound.
  7. Enter the main workflow prompt under "What is the main workflow prompt?". Select the expand icon for a larger editor.

Example main workflow prompt:

You are a helpful assistant named Sales Assistant that helps sales staff find product and pricing information.
Provide concise, accurate answers. If you don't know something, say so clearly.

Step 4: Agent Configuration

Each setting is a card. Select a card to open it, change the settings, and select Done.

  1. Conversation History — set Enabled to Yes to include earlier messages, and set Max Messages (default 5).
  2. Shielding — select Add pre-completion plugin to screen user prompts, or Add post-completion plugin to screen responses. Choose a plugin in Select a shielding plugin, set its parameters, and order the plugins with the arrows.
  3. User Prompt Rewrite — if enabled, choose a Rewrite Model, search for and select a Rewrite Prompt, and set Rewrite Window Size (default 3).
  4. Semantic Cache — if enabled, choose a Model, and review Embedding Dimensions (default 2048) and Minimum Similarity Threshold (default 0.97).
  5. Realtime Speech Configuration — shown only when the preview feature flag is on. See Enabling Realtime Speech.
  6. Enter a cost center and pick an expiration date if needed. Leave the date empty for no expiration.

Step 5: Tools

  1. Open the Tools tab.
  2. (Optional) Choose a Self-service tool set.
  3. Select Add Tool.
  4. In Add Tool to Agent, search or browse the Tool Library, select Select next to a tool, and then select Add to Agent.
  5. In Edit Agent Tool, check the tool Name, fill in any required Resource References (for example Main Model), and select Save changes.
  6. Repeat for each tool. To add a group of tools, use Add Tool Set under More options; to reuse another agent's tools, use Copy from another agent.

See Tools for details on each section of the tool editor.

Step 6: Portal Experience

  1. Write a Welcome message. Leave it empty to use the default welcome message.
  2. Open Conversation Starters, select Add Starter, and enter a Title and Content for each starter. Drag rows to reorder. Select Done.
  3. Set the experience toggles. Defaults are:
    • Show message tokens: Yes
    • Allow rating: Yes
    • See message prompts: Yes
    • Upload files: No
    • Show content artifacts: Yes
    • Show operation identifier: No
  4. For each toggle, use the Edit in Agent Portal? column to decide whether the setting can be changed when the agent is edited in the Agent Portal. All are Yes by default.

Step 7: Security

On a new agent, the Security tab has nothing to configure. Access Control, the virtual security group ID, and agent access tokens become available when you edit the agent after it is created.

The Sandbox and Private Storage tabs also appear only when you edit a saved agent and the related feature flags are enabled.

Step 8: Create the Agent

  1. Select Create Agent.
  2. If validation fails, the editor switches to the tab with the first error and shows the message under the field. Fix it and select Create Agent again.
  3. When the agent is saved, the message "Agent "[name]" was successfully created!" appears and the portal returns to the Agents page.

After Creation

  1. Find the agent on the Agents page and select the Edit icon.
  2. On the Security tab, select Access Control to grant other users access to the agent and its prompt.
  3. Create agent access tokens if API clients need to call the agent without Microsoft Entra ID.
  4. Open the User Portal and test the agent.

Common Issues

The agent name shows ❌

Hover over the icon to see the reason. Usually the name is already taken; choose a different name.

The main model is not listed

Only AI models of type completion are listed. Check the model type under Agents > Models, and confirm you can read the model.

A workflow prompt is not listed in Add Resource

Only prompts with the Agent Workflow category are listed, and you must type at least three characters. Check the prompt's category under Agents > Prompts.

Max rounds reset after choosing a workflow

On a new agent, selecting a workflow replaces the workflow properties. Set Max rounds and Enable tool escalation again after you select the workflow.