Table of Contents

Agent Properties Reference

This document describes the property management actions available for agent resources in FoundationaLLM. These actions allow you to read and update specific agent properties without retrieving or replacing the entire agent resource.

Overview

FoundationaLLM provides two actions for managing agent properties:

Action Description
get-properties Retrieve specific properties from an agent
set-properties Update specific properties on an agent

Properties are categorized into:

  • Readable properties - Can be retrieved via get-properties
  • Writable properties - Can be modified via set-properties
  • Read-only properties - Can be retrieved but not modified

Get Properties Action

Retrieves specific properties from an agent resource.

Endpoint

POST /instances/{instanceId}/providers/FoundationaLLM.Agent/agents/{agentName}/get-properties

Request Payload

The request payload uses the ResourcePropertiesGetRequest model:

{
  "property_names": [
    "property_name_1",
    "property_name_2"
  ],
  "metadata_property_names": [
    "metadata_property_name_1"
  ]
}

Payload Structure

Field Type Required Description
property_names string[] No Array of property names to retrieve.
metadata_property_names string[] No Array of metadata property names to retrieve.

Note: At least one property name must be specified in either property_names or metadata_property_names. The request will fail with a 400 Bad Request if both arrays are empty.

Response

The response contains a ResourcePropertiesGetResult object:

{
  "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/{agentName}",
  "is_success": true,
  "resource": {
    "properties": {
      "property_name_1": "value_1",
      "property_name_2": { ... }
    },
    "metadata_properties": {
      "metadata_property_name_1": "metadata_value_1"
    }
  }
}

Example: Get All Agent Properties

{
  "property_names": [
    "object_id",
    "type",
    "name",
    "display_name",
    "description",
    "cost_center",
    "created_on",
    "created_by",
    "updated_on",
    "updated_by",
    "expiration_date",
    "deleted",
    "inheritable_authorizable_actions",
    "workflow",
    "tools",
    "virtual_security_group_id",
    "text_rewrite_settings",
    "cache_settings",
    "conversation_history_settings",
    "shielding_settings",
    "realtime_speech_settings",
    "show_message_tokens",
    "show_message_rating",
    "show_view_prompt",
    "show_file_upload",
    "show_content_artifacts",
    "owner_user_id"
  ],
  "metadata_property_names": [
    "welcome_message"
  ]
}

Set Properties Action

Updates specific properties on an agent resource.

Endpoint

POST /instances/{instanceId}/providers/FoundationaLLM.Agent/agents/{agentName}/set-properties

Request Payload

The request payload uses the ResourcePropertiesUpdateRequest model:

{
  "properties": {
    "property_name": "property_value"
  },
  "metadata_properties": {
    "metadata_property_name": "metadata_property_value"
  }
}

Payload Structure

Field Type Required Description
properties object No Dictionary containing the agent properties to be updated. Keys must be valid writable property names.
metadata_properties object No Dictionary containing the agent metadata properties to be updated. Keys must be valid metadata property names.

Note: At least one property must be specified in either properties or metadata_properties. The request will fail with a 400 Bad Request if both dictionaries are empty.

Response

The response contains a ResourceProviderActionResult object:

{
  "object_id": "/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/{agentName}",
  "is_success": true
}

Property Reference

Read-Only Properties

These properties can be retrieved via get-properties but cannot be modified via set-properties.

Resource Base Read-Only Properties

Property JSON Name Type Description
Object ID object_id string The unique identifier of the resource.
Type type string The type of the resource (e.g., generic-agent).
Name name string The name of the resource.
Created On created_on DateTimeOffset The time at which the resource was created.
Created By created_by string The entity who created the resource.
Deleted deleted boolean Indicates whether the resource has been logically deleted.

Agent-Specific Read-Only Properties

Property JSON Name Type Description
Workflow workflow object The agent's workflow configuration.
Tools tools array The list of tools that are registered with the agent.
Virtual Security Group ID virtual_security_group_id string The agent's virtual security group identifier.

Writable Properties

These properties can be both retrieved via get-properties and modified via set-properties.

Agent-Specific Writable Properties

text_rewrite_settings

Controls the user prompt rewrite functionality for the agent.

Type: object | null

Structure:

{
  "text_rewrite_settings": {
    "user_prompt_rewrite_enabled": true,
    "user_prompt_rewrite_settings": {
      "user_prompt_rewrite_ai_model_object_id": "/instances/{instanceId}/providers/FoundationaLLM.AIModel/aiModels/{modelName}",
      "user_prompt_rewrite_prompt_object_id": "/instances/{instanceId}/providers/FoundationaLLM.Prompt/prompts/{promptName}",
      "user_prompts_window_size": 5
    }
  }
}
Field Type Description
user_prompt_rewrite_enabled boolean Indicates whether user prompt rewrite is enabled. Default: false
user_prompt_rewrite_settings object The settings for user prompt rewrite. Only valid when user_prompt_rewrite_enabled is true.

user_prompt_rewrite_settings Structure (AgentUserPromptRewriteSettings):

Field Type Required Description
user_prompt_rewrite_ai_model_object_id string Yes The object identifier of the AI model to use for user prompt rewriting.
user_prompt_rewrite_prompt_object_id string Yes The object identifier of the prompt to use for user prompt rewriting.
user_prompts_window_size integer Yes The window size (number of previous user prompts) to consider for rewriting.

Constraints: Set to null to clear the settings.

cache_settings

Controls the semantic caching functionality for the agent.

Type: object | null

Structure:

{
  "cache_settings": {
    "semantic_cache_enabled": true,
    "semantic_cache_settings": {
      "embedding_ai_model_object_id": "/instances/{instanceId}/providers/FoundationaLLM.AIModel/aiModels/{embeddingModelName}",
      "embedding_dimensions": 1536,
      "minimum_similarity_threshold": 0.975
    }
  }
}
Field Type Description
semantic_cache_enabled boolean Indicates whether the semantic cache is enabled. Default: false
semantic_cache_settings object The settings for semantic caching. Only valid when semantic_cache_enabled is true.

semantic_cache_settings Structure (AgentSemanticCacheSettings):

Field Type Default Description
embedding_ai_model_object_id string required The object identifier of the AI model to use for generating embeddings.
embedding_dimensions integer - The number of dimensions to use for the embedding vectors.
minimum_similarity_threshold decimal 0.975 The minimum similarity threshold (0.0-1.0) for cache matches. A higher value requires closer semantic matches.

Constraints: Set to null to clear the settings.

conversation_history_settings

Controls how conversation history is managed for the agent.

Type: object | null

Structure:

{
  "conversation_history_settings": {
    "enabled": true,
    "max_history": 10,
    "history_content_artifact_types": "text,image"
  }
}
Field Type Description
enabled boolean Indicates whether conversation history is enabled.
max_history integer Maximum number of turns to store in the conversation history.
history_content_artifact_types string Comma-separated list of content artifact types to store in history. Optional.

Constraints: Set to null to clear the settings.

shielding_settings

Selects the shielding plugins Core runs for this agent. Completions are not sent to a Gatekeeper API.

Type: object | null

Structure:

{
  "shielding_settings": {
    "pre_completion_plugins": [
      { "plugin_name": "Dotnet-FoundationaLLMShieldingPlugins-AzureContentSafety" }
    ],
    "post_completion_plugins": [
      { "plugin_name": "Dotnet-FoundationaLLMShieldingPlugins-Presidio" }
    ]
  }
}
Field Type Description
pre_completion_plugins object[] Plugins that screen the user prompt, in order.
post_completion_plugins object[] Plugins that screen the model response, in order.
plugin_name string Name of a shielding plugin from the installed package.

Constraints: Set to null, or leave both lists empty, to disable completion shielding. The obsolete gatekeeper_settings property is still accepted so older agents load. Core uses it only when shielding_settings is absent.

realtime_speech_settings

Controls realtime speech functionality for the agent.

Type: object | null

Structure:

{
  "realtime_speech_settings": {
    "enabled": true,
    "realtime_speech_ai_model_object_id": "/instances/{instanceId}/providers/FoundationaLLM.AIModel/aiModels/{modelName}",
    "stop_words": ["stop", "end conversation", "goodbye"],
    "max_session_duration_seconds": 300,
    "show_transcriptions": true,
    "include_conversation_history": true
  }
}
Field Type Default Description
enabled boolean false Whether realtime speech is enabled.
realtime_speech_ai_model_object_id string required Object ID of the AI model to use for realtime speech.
stop_words string[] ["stop", "end conversation", "goodbye"] Examples of clear hangup phrasing for the realtime end_conversation tool. They are not matched as substrings of the transcript.
max_session_duration_seconds integer 0 Maximum session duration in seconds. 0 means unlimited.
show_transcriptions boolean true Whether to show transcriptions in the chat thread.
include_conversation_history boolean true Whether to include conversation history in the session context.

Constraints: Set to null to clear the settings.

show_message_tokens

Controls whether token counts are displayed on messages in the UI.

Type: boolean | null

Default: true

Example:

{
  "show_message_tokens": false
}
show_message_rating

Controls whether rating options are displayed on messages in the UI.

Type: boolean | null

Default: true

Example:

{
  "show_message_rating": true
}
show_view_prompt

Controls whether the "view prompt" option is displayed on agent messages in the UI.

Type: boolean | null

Default: true

Example:

{
  "show_view_prompt": false
}
show_file_upload

Controls whether the file upload option is displayed on agent message input in the UI.

Type: boolean | null

Default: true

Example:

{
  "show_file_upload": true
}
show_content_artifacts

Controls whether content artifacts are displayed in the UI.

Type: boolean | null

Default: true

Example:

{
  "show_content_artifacts": false
}
owner_user_id

Sets or changes the owner user identifier for the agent.

Type: string

Constraints:

  • Cannot be null.
  • The calling user must have the Owner role assigned on the agent to change this property.
  • The new owner user ID is only set if it differs from the current value.

Example:

{
  "owner_user_id": "user-guid-here"
}

Resource Base Writable Properties

These properties are common to all resources.

display_name

The display name of the agent.

Type: string

description

The description of the agent.

Type: string

cost_center

The cost center associated with the agent.

Type: string

updated_on

The timestamp of the most recent update to the resource.

Type: null

Constraints: The value must be null. The system automatically sets this to the current time. This prevents clients from setting an incorrect timestamp.

Note: When using set-properties, the updated_on property is automatically updated even if not explicitly specified in the request.

updated_by

The user identifier of the most recent updater of the resource.

Type: null

Constraints: The value must be null. The system automatically sets this to the calling user's identity. This prevents clients from setting an incorrect user.

Note: When using set-properties, the updated_by property is automatically updated even if not explicitly specified in the request.

expiration_date

The expiration date of the agent.

Type: string (ISO 8601 date-time format)

inheritable_authorizable_actions

The list of inheritable authorizable actions for the agent.

Type: string[]

Metadata Properties

Metadata properties are stored in the agent's Properties dictionary and can be used for both get-properties and set-properties.

welcome_message

The welcome message displayed when a user starts a conversation with the agent.

Type: string | null

Constraints: Set to null to remove the welcome message.

Example:

{
  "metadata_properties": {
    "welcome_message": "Hello! How can I assist you today?"
  }
}

Property Summary Tables

All Readable Properties

Category Property Name Read Write
Resource Base object_id ? ?
Resource Base type ? ?
Resource Base name ? ?
Resource Base created_on ? ?
Resource Base created_by ? ?
Resource Base deleted ? ?
Resource Base display_name ? ?
Resource Base description ? ?
Resource Base cost_center ? ?
Resource Base updated_on ? ?*
Resource Base updated_by ? ?*
Resource Base expiration_date ? ?
Resource Base inheritable_authorizable_actions ? ?
Agent workflow ? ?
Agent tools ? ?
Agent virtual_security_group_id ? ?
Agent text_rewrite_settings ? ?
Agent cache_settings ? ?
Agent conversation_history_settings ? ?
Agent shielding_settings ? ?
Agent realtime_speech_settings ? ?
Agent show_message_tokens ? ?
Agent show_message_rating ? ?
Agent show_view_prompt ? ?
Agent show_file_upload ? ?
Agent show_content_artifacts ? ?
Agent owner_user_id ? ?
Metadata welcome_message ? ?

* These properties can be included in set-properties but must have a null value. The system automatically sets the actual values.

Example Requests

Get Specific Properties

{
  "property_names": [
    "display_name",
    "description",
    "cache_settings",
    "conversation_history_settings"
  ],
  "metadata_property_names": [
    "welcome_message"
  ]
}

Update Multiple Properties

{
  "properties": {
    "show_message_tokens": true,
    "show_message_rating": true,
    "show_file_upload": false,
    "conversation_history_settings": {
      "enabled": true,
      "max_history": 20
    }
  },
  "metadata_properties": {
    "welcome_message": "Welcome! I'm your AI assistant."
  }
}

Clear Settings

To clear a settings object, set it to null:

{
  "properties": {
    "cache_settings": null,
    "text_rewrite_settings": null
  }
}

Update Shielding Settings

{
  "properties": {
    "shielding_settings": {
      "pre_completion_plugins": [
        { "plugin_name": "Dotnet-FoundationaLLMShieldingPlugins-AzureContentSafety" }
      ],
      "post_completion_plugins": [
        { "plugin_name": "Dotnet-FoundationaLLMShieldingPlugins-Presidio" }
      ]
    }
  }
}

Error Responses

Status Code Description
400 Bad Request Invalid property name, empty properties dictionary/array, or invalid property value.
403 Forbidden User is not authorized to access/update the agent or specific property (e.g., owner_user_id).
404 Not Found The specified agent does not exist.
500 Internal Server Error A property was not found on the resource (for get-properties).

Example Error Response

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The following property names are invalid: invalid_property_name.",
  "instance": "/instances/{instanceId}/providers/FoundationaLLM.Agent/agents/{agentName}/set-properties"
}

Notes

  1. Partial Operations: Both get-properties and set-properties work on specific properties. For get-properties, only requested properties are returned. For set-properties, only specified properties are updated.

  2. Validation: All property names are validated against the allowed property names. Invalid property names result in a 400 Bad Request error.

  3. Authorization: Some properties (like owner_user_id) require specific role assignments to update.

  4. Automatic Timestamps: When using set-properties, the updated_on and updated_by properties are automatically updated by the system, even if not explicitly included in the request.

  5. Persistence: After updating properties via set-properties, the agent resource is saved to storage. The changes are immediately effective.

  6. Read-Only Properties: Attempting to update read-only properties via set-properties will result in a 400 Bad Request error.