Table of Contents

Agent Management UX Walkthrough

A walkthrough of common tasks for managing existing agents in the Management Portal.

Overview

All agent management starts on the Agents page, which lists the agents you can view. From there you can find an agent, inspect its definition, open it in the editor, manage who can use it, and delete it. For a reference description of the page, see Agents.

Accessing Agent Management

  1. Open the Management Portal and sign in with your Microsoft Entra ID account.
  2. In the sidebar, select Agents > Agents.

To reach the page faster later, select the pin icon next to Agents in the navigation pane to add it to Quick Access.

Task: Find a Specific Agent

Scenario: You need to find the agent named "Sales Assistant".

  1. Type Sales in the Search agents box. The list refreshes once you have typed three characters. Press Enter to search with fewer characters.
  2. The search matches the agent name, display name, and description.
  3. Select Clear to show all agents again.

Task: Show Only Agents You Own

Scenario: You want to focus on the agents you are responsible for.

  1. In the Ownership dropdown, select:
    • Primary Owner to show agents for which you are the primary owner, or
    • Owner to show agents on which you hold the Owner role.
  2. Select All to return to the full list.

The portal keeps the search text and Ownership selection while you navigate, until you reload the portal.

Task: Inspect an Agent's Definition

Scenario: You want to check an agent's full configuration without opening the editor.

  1. Select the View JSON definition icon (</>) in the agent's row.
  2. Review the read-only JSON in the Agent Definition dialog.
  3. Select Copy JSON to copy it, or Close.

Task: Change an Agent's Welcome Message

Scenario: You need to update the message users see when they start a conversation.

  1. Select the Edit icon (pencil) in the agent's row.
  2. Open the Portal Experience tab.
  3. Edit the Welcome message in the rich text editor.
  4. Select Save Changes.
  5. The message "Agent "[name]" was successfully updated!" confirms the change, and the header subtitle shows the new "Last Edited" time.

The Edit icon is dimmed when you don't have write permission on the agent.

Task: Change the Main Model

Scenario: You want the agent to use a different model.

  1. Open the agent in the editor.
  2. On Basic Settings, select a different Main model.
  3. Open the Workflow tab and review Workflow main model parameters. Selecting a new model replaces these parameters with the new model's own parameters.
  4. Select Save Changes.

Task: Add a Tool to an Existing Agent

  1. Open the agent in the editor and go to the Tools tab.
  2. Select Add Tool, select a tool from the Tool Library, and select Add to Agent.
  3. Complete the Edit Agent Tool dialog and select Save changes.
  4. Select Save Changes at the top of the editor to save the agent.

See Tools.

Task: Delete an Agent

Scenario: An agent is no longer needed.

  1. Select the Delete icon (trash can) in the agent's row.
  2. In the Delete Agent dialog, confirm "Are you sure you want to delete the agent "[name]"?" by selecting Yes, or select Cancel.
  3. The list refreshes without the agent.

Warning: Deleting an agent also deletes the prompts the agent references, except the shared platform prompts. Users can no longer use a deleted agent.

The Delete icon is dimmed when you don't have delete permission on the agent.

Managing Access to an Agent

View role assignments

  1. Open the agent in the editor.
  2. Open the Security tab and select Access Control.
  3. The Access Control dialog shows two tabs:
    • Agent — role assignments on the agent.
    • Prompt — role assignments on the agent's main workflow prompt.

Add a role assignment

  1. In the Access Control dialog, choose the Agent or Prompt tab.
  2. Select Add role assignment for this Agent (or for this Prompt).
  3. Complete the Create Role Assignment form.
  4. Select Create role assignment, or Back to return without saving.

See Access Control for the role assignment form and available roles.

Manage agent access tokens

  1. Open the agent's Security tab.
  2. Under Agent access tokens, select the add icon to create a token, or the trash icon to delete one.
  3. When you create a token, copy the key from View Access Token Details. It is shown only once.

Agent access tokens are available only when the agent has a virtual security group ID. See Agent Access Tokens.

The Management Portal does not set a default agent. To highlight agents for users, use the Featured Agents tab under Platform > Configuration. See Configuration.

Refreshing Data

The Agents page does not refresh automatically. Select Refresh agents (the refresh icon) to reload the list, for example after another user changes an agent.

Troubleshooting

Agent not appearing in the list

  • Clear the search text and set Ownership to All.
  • Select Refresh agents.
  • Scroll to the bottom of the list to load more agents.
  • Confirm you have read permission on the agent.

Can't edit an agent

  • The Edit icon is dimmed, or Save Changes is disabled in the editor.
  • You need FoundationaLLM.Agent/agents/write on the agent. Ask an agent owner to grant you access.

Can't delete an agent

  • The Delete icon is dimmed.
  • You need FoundationaLLM.Agent/agents/delete on the agent.

Changes not saving

  • Look for messages under fields; the editor switches to the tab with the first error.
  • Check that required workflow fields (Workflow name, Workflow package name, Workflow host) are filled in.