Agents and Workflows

This reference describes the agent resource, the workflow types an agent can use, and the workflow behaviors you configure in the Management Portal agent editor.

Overview

An agent is a resource of type generic-agent in the FoundationaLLM.Agent resource provider (agents resource type). It brings together:

A workflow that drives model and tool calls, including the main AI model and the main workflow prompt.
A list of tools that the workflow can call.
Shielding plugins that screen prompts and responses.
Conversation, caching, and prompt-rewrite settings.
Portal experience settings that control what users see in the User Portal, and which of those settings can be changed in the Agent Portal.

In the Management Portal, agents are created and edited under Agents > Agents. For step-by-step instructions, see Create a New Agent.

Agent Editor Tabs and Agent Properties

The agent editor groups the agent properties into tabs. The following table maps each tab to the agent JSON properties it edits.

Tab	What it edits	Agent properties
Basic Settings	Agent display name, agent name, description, main model, Max rounds, Enable tool escalation, and the main workflow prompt.	`display_name`, `name`, `description`, `workflow.resource_object_ids` (main model and main prompt), `workflow.properties.max_rounds`, `workflow.properties.enable_tool_escalation`
Agent Configuration	Conversation History, Shielding, User Prompt Rewrite, Semantic Cache, Realtime Speech Configuration (only when the preview feature flag is on), cost center, and expiration date.	`conversation_history_settings`, `shielding_settings`, `text_rewrite_settings`, `cache_settings`, `realtime_speech_settings`, `cost_center`, `expiration_date`
Sandbox	The sandbox configuration used by the agent. Shown only when editing an agent and the sandbox feature flag is on.	`sandbox_configuration_id`
Private Storage	Files in the agent's private store. Shown only when the agent private store feature flag is on and the agent uses an Azure OpenAI Assistants workflow or the FoundationaLLM function-calling workflow.	Agent files (`agentFiles` child resources)
Tools	The tools assigned to the agent and their models, prompts, resources, and properties. See Tools.	`tools`
Portal Experience	Welcome message, Conversation Starters, User Portal display toggles, and the Edit in Agent Portal? toggle for each display setting.	`properties.welcome_message`, `conversation_starters`, `show_*` properties, `self_service_editable_properties`
Workflow	Workflow type, workflow name, workflow package name, workflow class name, workflow host, workflow main model parameters, workflow properties, and additional workflow resources.	`workflow`
Security	Access Control for the agent and its prompt (when editing), the virtual security group ID, and agent access tokens.	`virtual_security_group_id`, agent access tokens (`agentAccessTokens` child resources)

Agent JSON Structure

The following example shows the main properties of an agent. Optional sections that are not in use can be omitted or set to null.

{
  "type": "generic-agent",
  "name": "my-agent",
  "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/my-agent",
  "display_name": "My Agent",
  "description": "Answers questions about our products.",
  "cost_center": "",
  "expiration_date": null,
  "sessions_enabled": true,
  "conversation_history_settings": {
    "enabled": true,
    "max_history": 10,
    "history_content_artifact_types": null
  },
  "text_rewrite_settings": {
    "user_prompt_rewrite_enabled": false,
    "user_prompt_rewrite_settings": null
  },
  "cache_settings": {
    "semantic_cache_enabled": false,
    "semantic_cache_settings": null
  },
  "shielding_settings": {
    "pre_completion_plugins": [
      { "plugin_name": "Dotnet-FoundationaLLMShieldingPlugins-LakeraGuard", "plugin_parameters": null }
    ],
    "post_completion_plugins": [
      { "plugin_name": "Dotnet-FoundationaLLMShieldingPlugins-Presidio", "plugin_parameters": null }
    ]
  },
  "workflow": {
    "type": "generic-agent-workflow",
    "name": "Agent-Workflow",
    "package_name": "foundationallm_agent_plugins",
    "class_name": "FoundationaLLMFunctionCallingWorkflow",
    "workflow_host": "LangChain",
    "resource_object_ids": {
      "/instances/{instanceId}/providers/FoundationaLLM.AIModel/aiModels/my-model": {
        "object_id": "/instances/{instanceId}/providers/FoundationaLLM.AIModel/aiModels/my-model",
        "properties": { "object_role": "main_model", "model_parameters": { "temperature": 0.0 } }
      },
      "/instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts/my-agent": {
        "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts/my-agent",
        "properties": { "object_role": "main_prompt" }
      },
      "/instances/{instanceId}/providers/FoundationaLLM.Agent/workflows/GenericAgentWorkflow": {
        "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/workflows/GenericAgentWorkflow",
        "properties": {}
      }
    },
    "properties": {
      "max_rounds": 5,
      "enable_tool_escalation": false
    }
  },
  "tools": [],
  "show_message_tokens": true,
  "show_message_rating": true,
  "show_view_prompt": true,
  "show_file_upload": true,
  "show_content_artifacts": true,
  "show_message_operation_id": false,
  "self_service_editable_properties": [
    "show_message_tokens",
    "show_message_rating",
    "show_view_prompt",
    "show_file_upload",
    "show_content_artifacts",
    "show_message_operation_id"
  ],
  "conversation_starters": [
    { "title": "Product overview", "content": "Give me an overview of the product line." }
  ],
  "properties": {
    "welcome_message": "Hi! Ask me anything about our products."
  },
  "virtual_security_group_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "owner_user_id": "11111111-2222-3333-4444-555555555555"
}

When you save an agent in the Management Portal, the main workflow prompt is saved as a separate prompt resource (named after the agent for new agents) and referenced from the workflow with the main_prompt role.

Agent Settings

Conversation History

Controls how much of the conversation is sent with each request.

Setting	Type	Description
`enabled`	boolean	Include previous messages in the context. Shown as Enabled in the editor.
`max_history`	integer	Maximum number of conversation turns (user message and agent response pairs) to include. Shown as Max Messages in the editor.
`history_content_artifact_types`	string	Optional comma-separated list of content artifact types to keep in the conversation history.

Shielding

Shielding replaces the earlier Gatekeeper settings. Shielding plugins are plugins of the Shielding category, delivered in plugin packages. In the editor, the Shielding section lists Pre-completion plugins (they screen the user prompt before the model is called) and Post-completion plugins (they run against the model response before it is returned). Plugins run in the order in which they are listed.

Setting	Type	Description
`shielding_settings.pre_completion_plugins`	array	Ordered list of plugins invoked against the user prompt.
`shielding_settings.post_completion_plugins`	array	Ordered list of plugins invoked against the completion response.
`plugin_name`	string	The name of the shielding plugin, for example `Dotnet-FoundationaLLMShieldingPlugins-AzureContentSafety`.
`plugin_parameters`	array	Optional plugin parameters, for example `EvaluateContentSafety` and `EvaluateAttacks` for Azure Content Safety.

The platform includes shielding plugins for Azure Content Safety, Lakera Guard, Enkrypt Guardrails, and Microsoft Presidio. The plugins available in your instance are the ones loaded from plugin packages under Platform > Packages.

Note

Agents created before shielding was introduced may still store gatekeeper_settings.options. When an agent has no shielding_settings, the platform maps the legacy options to shielding plugins: LakeraGuard, EnkryptGuardrails, AzureContentSafety, and AzureContentSafetyPromptShield become pre-completion plugins, and Presidio (or MicrosoftPresidio) becomes a post-completion plugin.

Individual tools can also shield their output with a shielding plugin. That setting belongs to the tool, not to the agent.

User Prompt Rewrite

Rewrites the user prompt into a clearer, more specific question, using recent conversation turns as context, before the workflow processes it.

Setting	Type	Description
`text_rewrite_settings.user_prompt_rewrite_enabled`	boolean	Enable user prompt rewriting.
`user_prompt_rewrite_settings.user_prompt_rewrite_ai_model_object_id`	string	The AI model used for rewriting.
`user_prompt_rewrite_settings.user_prompt_rewrite_prompt_object_id`	string	The prompt that contains the rewriting instructions.
`user_prompt_rewrite_settings.user_prompts_window_size`	integer	The number of recent conversation turns (user and agent message pairs) used as context when rewriting.

Semantic Cache

Returns a cached response when a new request is similar enough to a previous one.

Setting	Type	Description
`cache_settings.semantic_cache_enabled`	boolean	Enable the semantic cache.
`semantic_cache_settings.embedding_ai_model_object_id`	string	The embedding model used to compare requests.
`semantic_cache_settings.embedding_dimensions`	integer	The number of embedding dimensions.
`semantic_cache_settings.minimum_similarity_threshold`	decimal	The minimum similarity for a cache hit (default `0.975`).

Realtime Speech

realtime_speech_settings configures realtime speech sessions (for example, enabled and realtime_speech_ai_model_object_id). The Realtime Speech Configuration section appears on the Agent Configuration tab only when the preview feature flag is on. See Enabling Realtime Speech.

Cost Center and Expiration

Setting	Type	Description
`cost_center`	string	Cost allocation identifier used for chargeback.
`expiration_date`	datetime	The date after which the agent expires. `null` means no expiration.

Portal Experience Settings

These settings control what users see in the User Portal for this agent.

Editor question	Property	Default
Would you like to show the message tokens?	`show_message_tokens`	`true`
Would you like to allow the user to rate the agent responses?	`show_message_rating`	`true`
Would you like to allow the user to see the message prompts?	`show_view_prompt`	`true`
Would you like to allow the user to upload files?	`show_file_upload`	`true`
Would you like to show content artifacts in messages?	`show_content_artifacts`	`true`
Would you like to show the operation identifier on agent messages?	`show_message_operation_id`	`false`

Self-Service Editable Properties

Each display setting has an Edit in Agent Portal? toggle. The toggles are stored in self_service_editable_properties, a list of the display property names that agent owners can change in the Agent Portal:

When the property is missing, all six display properties are editable.
When the list is empty, none of them can be edited in the Agent Portal.

Welcome Message and Conversation Starters

Setting	Description
`properties.welcome_message`	The message shown when a user starts a conversation with the agent. If it is empty, the default welcome message is shown.
`conversation_starters`	Suggested prompts shown to users. Each starter has a `title` and a `content` value. In the editor, select Add Starter to add one.

Workflows

Workflow Types

The workflow type is the type value of the agent's workflow object. On the Workflow tab, the What workflow should the agent use? list shows the workflow resources (FoundationaLLM.Agent/workflows) defined in your instance, so the types you can select depend on your deployment.

Workflow type	Description
`generic-agent-workflow`	Runs a Python workflow plugin from a plugin package. The editor shows Workflow package name and Workflow class name as dropdowns filled from the Python plugin packages under Platform > Packages. New agents default to the `foundationallm_agent_plugins` package and the first workflow class it lists, such as `FoundationaLLMFunctionCallingWorkflow`.
`langchain-agent-workflow`	The LangChain agent workflow. New agents default to package `foundationallm_agent_plugins_langchain` and class `FoundationaLLMLangChainAgentWorkflow`.
`langchain-expression-language-workflow`	A LangChain Expression Language (LCEL) workflow. Runs `FoundationaLLMLangChainLCELWorkflow` from `foundationallm_agent_plugins_langchain`.
`langgraph-react-agent-workflow`	Deprecated. Use `langchain-agent-workflow` instead. Existing agents run `FoundationaLLMLangGraphReActAgentWorkflow` from `foundationallm_agent_plugins_langchain`.
`azure-openai-assistants-workflow`	Uses the Azure OpenAI Assistants API (legacy).
`azure-ai-agent-service-workflow`	Uses the Azure AI Agent Service. The workflow references an Azure AI project resource with the `ai_project` role.
`external-agent-workflow`	Runs a custom workflow implementation identified by package name and class name.

For plugin-based workflows, the package_name value FoundationaLLM refers to a legacy virtual package that the LangChain API no longer supports. Use a Python plugin package instead.

Workflow Resource Structure

The following table describes the properties of the agent's workflow object.

Setting	Description
`type`	The workflow type (see the previous table).
`name`	The workflow name, shown as Workflow name in the editor.
`package_name`	The Python module name of the plugin package that implements the workflow, shown as Workflow package name.
`class_name`	The workflow class within the package, shown as Workflow class name. Defaults to `name` when empty.
`workflow_host`	The service that runs the workflow, shown as Workflow host. The Management Portal offers `LangChain`, which is also used when the value is empty.
`resource_object_ids`	The models, prompts, and other resources used by the workflow. Each entry has an `object_id` and `properties`, including an `object_role`.
`properties`	Workflow-specific properties, shown as Workflow properties. `max_rounds` and `enable_tool_escalation` are set from the Basic Settings tab and are not listed in the properties editor.

Workflow Resource Roles

Role (`object_role`)	Description
`main_model`	The main AI model. Its `model_parameters` property holds the values from Workflow main model parameters.
`main_prompt`	The main workflow prompt that defines the agent's persona and instructions.
`router_prompt`	Instructions for selecting tools. The platform provides `Platform-Agent-Workflow-Router` and `Platform-Agent-Workflow-Router-Multi-Round`.
`files_prompt`	Instructions for using conversation files and attachments. The platform provides `Platform-Agent-Workflow-Files`.
`escalation_prompt`	Instructions for the tool escalation pass. When the workflow does not reference one, the platform uses `Platform-Agent-Workflow-Escalation`.
`final_prompt`	Instructions for building the final response from tool results. The platform provides `Platform-Agent-Workflow-Final`.
`ai_project`	The Azure AI project used by the Azure AI Agent Service workflow.

Add workflow resources with the + button next to Additional workflow resources: on the Workflow tab.

Max Rounds

Max rounds on the Basic Settings tab sets the max_rounds workflow property used by the FoundationaLLM function-calling workflow.

When max_rounds is set, the workflow runs in multi-round mode. In each round, the model either returns a final answer or selects tools to run, and the tool results feed the next round. The workflow stops after a final answer or after max_rounds rounds. If no final answer is produced by then, the workflow makes one last attempt to compose an answer with the final prompt.
When Max rounds is 0 or empty, the property is removed and the workflow runs a single round.

In multi-round mode, the workflow replaces {{max_rounds}} and {{current_round}} in the workflow prompts. The Platform-Agent-Workflow-Router-Multi-Round prompt uses these placeholders.

Tool Escalation

Enable tool escalation on the Basic Settings tab sets the enable_tool_escalation workflow property. When it is on, the FoundationaLLM function-calling workflow adds a lightweight first pass before the main workflow:

The model receives the main workflow prompt plus the escalation prompt, with only a synthetic request_tools function bound.
If the model answers directly, that answer is returned and no tools are loaded.
If the model requests specific tools, only those tools are bound for the rest of the workflow.
If the request is invalid (for example, it names a tool the agent does not have) or the escalation prompt cannot be loaded, the workflow fails open and binds all of the agent's tools.

The escalation pass is skipped when the agent has no tools or when the request includes attachments or conversation files.

Router Prompt Inclusion

The FoundationaLLM function-calling workflow appends the router prompt to the main workflow prompt only when at least one bound tool is listed in the FoundationaLLM:APIEndpoints:LangChainAPI:Configuration:WorkflowToolEscalation:ToolsRequiringRouterPrompt setting. When that setting is missing or empty, no tool requires the router prompt. Manage the list on the Agent Workflows tab under Platform > Configuration. The same tab manages the status messages that the workflow shows while it plans, runs tools, and decides whether tools are needed. See Configuration.

Tools

The agent's tools array holds the tools assigned to the agent. Each entry references a tool resource from the platform tool catalog and adds agent-specific configuration. Manage the catalog under Agents > Tools and MCP servers under Agents > MCP Servers; assign tools to an agent on the agent editor's Tools tab. See Tools and MCP Servers.

Property	Description
`name`	The tool name that the workflow exposes to the model.
`description`	The tool description that the workflow exposes to the model.
`category`	`Generic`, `Knowledge Search`, `Code Interpreter`, or `Image Generation`.
`tool_object_id`	The object ID of the tool resource in the catalog, for example `/instances/{instanceId}/providers/FoundationaLLM.Agent/tools/{toolName}`.
`package_name`	The Python plugin package that implements the tool.
`class_name`	The tool class within the package. Defaults to `name` when empty.
`resource_object_ids`	The models, prompts, and other resources used by the tool, each with an `object_role` (for example `main_model`, `main_prompt`, or `router_prompt`).
`properties`	Tool-specific property values.

Security

Virtual Security Group ID

Every agent has a virtual_security_group_id. The platform generates it when the agent is first saved and creates a Reader role assignment for it on the agent. Callers that use the agent's access tokens are members of this group. The Security tab shows the ID with a copy button.

Agent Access Tokens

Agent access tokens let clients use the agent without Entra ID authentication. See Agent Access Tokens.

Table of Contents