How to create an agent to your cluster

Note

This page is about the in-app chatbot agent you configure in Neos Studio for the end users of a cluster. For the AI coding assistant that helps developers build Neos clusters from Claude Code or GitHub Copilot, see Neos Copilot.

Connector

You can choose between six connectors to implement the model you want!

Azure OpenAI

You must have an Azure account to use this connector. Then you must create deployment for the model you want to use. (https://portal.azure.com/#home).

Configuration:

API key (secret)
API endpoint (secret)
Deployment ID (in Neos Studio)
Model ID (in Neos Studio)

Warning

LLM model with reasoning capabilities do not support the temperature, topP and maxTokens parameters, so you must leave them empty.

Azure AI Inference

You must have an Azure account to use this connector. Then you must create deployment for the model you want to use. (https://portal.azure.com/#home).

Configuration:

API key (secret)
API Endpoint (secret)
Model ID (in Neos Studio)

OpenAI

Configuration:

API key

Warning

LLM model with reasoning capabilities do not support the temperature, topP and maxTokens parameters, so you must leave them empty.

Google

You must have a Google account to use this connector and create an API key.

Configuration:

API key (secret)
Model ID (in Neos Studio)

Mistral

You must have a Mistral account to use this connector and create an API key.

See Mistral models, use API Endpoint as model ID.

Configuration:

API key (secret)
Model ID (in Neos Studio)

Warning

Temperature cannot be set to 0.0 with Mistral, otherwise a 400 (BadRequest) error will be returned by the Mistral API.

Hugging Face

You must have a Hugging Face account to use this connector and create an API key. If you use serverless inference API, the APIEndPoint must be "https://api-inference.huggingface.co/"

For example you can set the APIEndPoint with the following command to add it to the user secrets:

dotnet user-secrets set AI:HuggingFace:ApiEndPoint https://api-inference.huggingface.co/

or in your cluster yaml configuration file:

AI:
  HuggingFace:
    ApiEndPoint: https://api-inference.huggingface.co/

Warning

The HuggingFace connector does not support the function calling capability. So you can't use skills with semantic functions with this connector.

Configuration:

API key (secret)
API endpoint (secret)
Model ID (in Neos Studio)

Setup Configuration

To configure the API key and endpoint, you have two options: dotnet user-secrets and secret store in Kubernetes.

Dotnet user-secrets

This is the recommended way in development mode.

API Key:

dotnet user-secrets set "AI:[ConnectorName]:ApiKey" "[Your API key]" --id "[Your cluster root namespace].AspNetCore"

Endpoint:

dotnet user-secrets set "AI:[ConnectorName]:ApiEndpoint" "[Your API endpoint]" --id "[Your cluster root namespace].AspNetCore"

For example, with AzureOpenAI:

dotnet user-secrets set "AI:AzureOpenAI:ApiKey" "2468" --id "GroupeIsa.Neos.Designer.AspNetCore"

dotnet user-secrets set "AI:AzureOpenAI:ApiEndpoint" "https://my-endpoint.openai.azure.com" --id "GroupeIsa.Neos.Designer.AspNetCore"

You can override the configuration for a specific model of the connector by adding the model name instead of the connector name:

dotnet user-secrets set "AI:AzureGpt54:ApiEndpoint" "https://my-gpt-endpoint.openai.azure.com" --id "GroupeIsa.Neos.Designer.AspNetCore"

Secret store in Kubernetes

In production it's recommended to use a secret store in Kubernetes:

Key	Value
Api:ConnectorName:ApiKey	Your API key
Api:ConnectorName:ApiEndpoint	The endpoint of the Azure OpenAI

Example, with AzureOpenAI:

Key	Value
Api:AzureOpenAI:ApiKey	2468
Api:AzureOpenAI:ApiEndpoint	https://my-endpoint.openai.azure.com

Configure AI Models

Then, you must configure AI models in Neos Studio. You can use the OpenAI API or the Azure Open API.

Azure OpenAI

Property	Description	Example
Name	A unique name	AzureGpt54
ModelId	The model identifier	gpt-5.4
DeploymentId	The identifier of your Azure deployment	gpt-5.4
Capabilities	An array of the model's capabilities	[TextGeneration, FunctionCalling]

You must also set the Azure OpenAI key and Azure OpenAI endpoint in dotnet user-secrets or in an environment variable. You can find the description of the procedure in the Devops wiki.

Azure AI Inference

Property	Description	Example
Name	A unique name	AzureGpt54
ModelId	The model identifier	gpt-5.4
Capabilities	An array of the model's capabilities	[TextGeneration, FunctionCalling]

You must also set the Azure AI inference key and Azure AI inference endpoint in dotnet user-secrets or in an environment variable. You can find the description of the procedure in the Devops wiki.

OpenAI

Property	Description	Example
Name	A unique name	OpenAIGpt54
ModelId	The model identifier	gpt-5.4
OrganizationId	An optional organization ID
Capabilities	An array of the model's capabilities	[TextGeneration, FunctionCalling]

You must also set the OpenAI key in dotnet user-secrets or in an environment variable. You can find the description of the procedure in the Devops wiki.

Ollama

First you must install Ollama, on Windows you can use the following command:

winget install --id=Ollama.Ollama  -e

Then you must install a LLM model:

Examples :

For phi4 model:

ollama pull phi4

For Mistral small 3.1 model:

ollama pull cnjack/mistral-samll-3.1:24b-it-q4_K_S

Then you must set the Ollama API endpoint in dotnet user-secrets or in an environment variable.

dotnet user-secrets set "AI:Ollama:ApiEndpoint" "http://localhost:11434" --id [cluster root namespace].AspNetCore

Property	Description	Example
Name	A unique name	OllamaPhi4
ModelId	The model identifier	phi4
Capabilities	An array of the model's capabilities	[TextGeneration, FunctionCalling]

Warning

The Ollama connector does not support the function calling capability in streaming mode. So you cannot use skills with semantic functions with this connector in the chatbot.
But you can use the function calling capability outside the chatbot.

Others models

You can configure other models in the same way as the OpenAI model. Currently, you can configure models from Google, Hugging Face and Mistral.

Warning

You must set the real capabilities of the model in the Capabilities property. To use the model to an agent available in chatbot, you must set the TextGeneration capability. To use skills with semantic functions, you must set the FunctionCalling capability if the model supports it. Empty capabilities should use only with model to vectorize text. Vision capabilities should use only with model to analyze images or generate images, currently the chatbot does not support this kind of capabilities.

Create an Agent

Then, you must configure an agent in Neos Studio.

Property	Description	Example
Identifier	A unique name	OrderCreator
Name	The displayed name in the chatbot	Bob
ModelName	The model name configured in the previous step	AzureGpt54
IconName	The name of the icon displayed in the chatbot	OrderIcon
Temperature	What sampling temperature to use. Higher values mean the model will take more risks. Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer.	0.9
TopP	An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with the top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered	1
MaxTokens	The maximum number of tokens to generate in the completion.
ReasoningEffort	The reasoning effort to use for the agent. The higher the reasoning effort, the more the agent will try to find a solution to the user's request. Available only for OpenAI models that support reasoning.	Medium
IncludeSkillInstructions	If true, the instructions of the skills used by the agent will be included in the prompt sent to the model. If false you can include them by using handlebars in the agent prompt	True
Description	A localized string to describe the agent	en: Order creator, fr: Créateur de commande
Instructions	A system-level instruction to guide your model's behavior throughout the conversation. The assistant refers to himself in the first person singular.	I'm an assistant that helps the user to create orders
Skills	The skills of your agent. You should select one or more skills provided by Neos or your own skills	OrderCreation

Note

When you create an agent, you need to generate the cluster to apply the changes. When you edit an agent except its name, you do not need to generate the cluster, the changes are applied immediately after saving.

Warning

The agent is not visible in the chatbot if the model API Key or API EndPoint is not configured.

Skills provided by Neos

Neos provides several skills that you can use to extend the capabilities of your agent. You don't need to reference the functions of these skills in the instructions of the agent, they are automatically available for the assistant.

EntitiesExplorer Skill

Provides functionalities to explore entities.

You can reference this skill as a dependency of other skills using GroupeIsa.Neos.Application.AI.Skills.IEntitiesExplorerSkill interface.

You must include this skill if the agent needs to explore entities to find an entity needed to perform an action asked by the user. Only entities with read permission will be provided.

Functions provided by this skill:

Semantic Function name	C# Method name	Description
GetAllEntities	Task GetAllEntitiesAsync()	Provides a markdown list of all entities with their description. Only entities with read permission will be provided.
GetEntityProperties	Task GetEntityPropertiesAsync(string entityName)	Provides a markdown list of all entity properties with their caption and description for the specified entity. Navigation properties to unauthorized entities will not be provided. Properties without caption and AI description will not be provided, so you can hide a property to an agent.
GetEnumValues	string GetEnum(string enumName)	Provides a markdown list of all enum members with their caption for the specified enum.

EntitiesQuerierSkill

Provides functionalities to query entities. You can reference this skill as a dependency of other skills using GroupeIsa.Neos.Application.AI.Skills.IEntitiesQuerierSkill interface.

You must include this skill if the agent needs to query entities with EF Linq queries.

Functions provided by this skill:

Semantic Function name	C# Method name	Description
QueryExpressionEvaluator	Task	Parse the C# code and return the result of its execution.

Note

The QueryExpressionEvaluator can only access on entities repositories with read permission, otherwise an exception will be thrown.
The expression query created by the agent is checked by the QueryExpressionEvaluator to avoid used of unauthorized entities.
So you must check if the entity is authorized if your cluster used the user permissions module.

Note

Security considerations
This skill executes C# code provided by the LLM. To avoid security issues, the code is parsed and checked to ensure that it does not contain any malicious code. Therefore, the code have a maximum execution time of 30 seconds by default. You can change this value in the Yaml configuration file of your cluster, for example to set the maximum execution time to 10 seconds:

AI:
  EntityQuerierSkill:
    ExecutionTimeout: 10

Note

Performance considerations
This skill executes C# code provided by the LLM using the Roslyn compiler. Every time the agent calls this skill, the code is parsed and compiled, which uses memory resources. By default the concurrency level is set to 5, which means that only five pieces of code can be executed at a time, the others will be queued and wait up to 30 seconds before being executed. You can change this value in the Yaml configuration file of your cluster, for example to set the concurrency level to 3:

AI:
  EntityQuerierSkill:
    MaxConcurrency: 3

You can also set the maximum time to wait for the code to be executed, by default it is set to 30 seconds, you can change this value in the Yaml configuration file of your cluster, for example to set the maximum waiting time to 10 seconds:

AI:
  EntityQuerierSkill:
    WaitTimeoutSeconds: 10

If this time is exceeded, an exception will be thrown.

EntityViewsExplorer Skill

Provides functionalities to explore entity views.

You can reference this skill as a dependency of other skills using GroupeIsa.Neos.Application.AI.Skills.IEntitiesExplorerSkill interface.

You must include this skill if the agent needs to explore entity views to find an entity view needed to perform an action asked by the user. For example to create an order, the agent needs to explore the entity views in order to find the appropriate entity view to create an Order.

Functions provided by this skill:

Function name	Description
string GetReadableEntityViews()	Provides a markdown list of all entity views with their description. Only entity views with read permission will be provided.
string GetWritableEntityViews()	Provides a markdown list of all entity views with their description. Only entity views with create, update or delete permission will be provided.
string GetEntityProperties(string entityViewName)	Provides a markdown list of all entity view property with their description for the specified entity View.

EntityViewQuerierSkill

Provides functionalities to query entity views.

You can reference this skill as a dependency of other skills using GroupeIsa.Neos.Application.AI.Skills.IEntitiesQuerierSkill interface.

You must include this skill if the agent needs to query entity views. For example to get the average price of a product, the agent needs to query the entity views to get the price of the product.

Functions provided by this skill:

Function name	Description
string HowToDoODataQuery()	Provide instructions to create an ODataQuery

DataCreatorSkill

Provides functionalities to create data.

You can reference this skill as a dependency of other skills using GroupeIsa.Neos.Application.AI.Skills.IDataCreatorSkill interface.

You must include this skill if the agent needs to create data. For example to create an employee, the agent needs to create an JSON schema to create a JSON string and send it to the API.

Functions provided by this skill:

Function name	Description
string? GetEntityViewJsonSchema(string entityViewName)	Provide a Json schema of POST API Model for the specified API
Task CreateEntityViewAsync(string? entityViewName, string? jsonString)	Create an entity view with the specified entity view name and JSON string

MermaidGraphSkill

Provides functionalities to create mermaid graphs.

You can reference this skill as a dependency of other skills using GroupeIsa.Neos.Application.AI.Skills.IMermaidGraphSkill interface.

You must include this skill if the agent needs to create mermaid graphs.

Functions provided by this skill:

Function name	Description
string HowToDoMermaidGraph()	Provide instructions to build mermaid charts and diagrams

UIInteractionSkill

Provides functionalities to interact with the UI.

You can reference this skill as a dependency of other skills using GroupeIsa.Neos.Application.AI.Skills.IUIInteractionSkill interface.

You must include this skill if the agent needs to interact with UI. This skill can open a UI view in creation mode with initial data and can open an UI view in edition mode.

Functions provided by this skill:

Function name	Description
string CreateNewEntityAsync(string? uiViewName, string? jsonString)	Opens the specified UI view with the initial data as JSON
string OpenUIViewNameAsync(string? uiViewName, string? identifiers, string? parameters)	Opens the UI view with the identifiers of an item and with parameters

DataProposalSkill

Provides functionalities to propose new data in a UI form.

You can reference this skill as a dependency of other skills using GroupeIsa.Neos.Application.AI.Skills.IDataProposalSkill interface.

Functions provided by this skill:

Function name	Description
string CreateNewEntityAsync(string? uiViewName, string? jsonString)	Open the specified UI view with the initial data as JSON

Create your own skill

See Create your own skill.

How to Monitor the Chatbot

You can create a class that implements the IChatBotInterceptor interface to get information about the conversation with the chatbot. Example:

public class ChatBotInterceptor : IChatBotInterceptor
{
    /// <inheritdoc />
    public Task OnFunctionInvokedAsync(string agentId, string threadId, string functionName, Dictionary<string, object?> parameters, object? result)
    {
        // Do what you want with the information about the function call with the semantic kernel.
    }

    /// <inheritdoc />
    public Task OnPromptInvokedAsync(string agentId, string threadId, string question, string answer)
    {
        // Do what you want with the exchange between the user and the chatbot.
    }
}

Once you have created the class, you need to register it in the Startup class:

public static class Startup
{
    public static void ConfigureServices(IServiceCollection services)
    {
        services.AddScoped<IChatBotInterceptor, ChatBotInterceptor>();
    }
}

Table of Contents

How to create an agent to your cluster

Note

Connector

Azure OpenAI

Warning

Azure AI Inference

OpenAI

Warning

Google

Mistral

Warning

Hugging Face

Warning

Setup Configuration

Dotnet user-secrets

Secret store in Kubernetes

Configure AI Models

Azure OpenAI

Azure AI Inference

OpenAI

Ollama

Warning

Others models

Warning

Create an Agent

Note

Warning

Skills provided by Neos

EntitiesExplorer Skill

EntitiesQuerierSkill

Note

Note

Note

EntityViewsExplorer Skill

EntityViewQuerierSkill

DataCreatorSkill

MermaidGraphSkill

UIInteractionSkill

DataProposalSkill

Create your own skill

How to Monitor the Chatbot