# Create and configure an AI agent

> [HTML Version](cortex-configure-agent.html)

Before creating [AI agents](cortex-ai-agents.md), make sure you have [connected language model providers in BRIX AI](cortex-llm-providers.md).

To configure an AI agent, complete the following steps in **BRIX AI**:

1. [Add an AI agent](#add-agent).

2. [Configure basic settings](#main-settings). Select a language model and write instructions for generating responses. You can also specify the execution environment for the AI agent (OpenAI or ReAct), which determines how the agent interacts with its tools.

3. [Connect tools](#tools-settings). Define the functions available to the AI agent, such as which data it can retrieve, which actions it can perform, and more.

4. [Connect managed agents](#child-agents). Set up task routing between AI agents by specifying child agents with specialized functions.

5. [Set an API key to call the AI agent in scripts](#api-key). Set up the ability to call the AI agent via API from BRIX scripts and external systems.

6. [Set up security tools](#guardrails-masking). Enable Guardrails checks to block unwanted requests and responses, and set up sensitive data masking before sending prompts to the language model.

7. [Set up the AI agent chat widget](#widget-settings). Specify the AI agent name that users will see when chatting with it in BRIX, and configure quick actions.

**Important**: the steps described in this article are based on the features available in the **BRIX AI Enterprise** edition. If you are using a different edition, some tools may be unavailable. To learn more, see [Available BRIX AI editions](cortex-editions.md).

## Step 1. Add an AI agent

1. In the left menu of **BRIX AI**, go to the **Agents** page.

2. Click **Add Agent**.

3. In the window that opens, fill in the following fields:

- **Name**. Rhe AI agent name displayed in **BRIX AI**.

- **Agent Chat Name**. The name displayed to users when chatting with the AI agent.

4. Click** Create**.

5. On the opened AI agent page, you can change its icon that appears in **BRIX AI** and in user chats. To do this, click the image next to the AI agent name in the top right corner and select a different option.

**(cortex-configure-ai-agent-1.png)**

## Step 2. Configure basic settings for the AI agent

On the **Settings** tab, set the main parameters:

1. Fill in the fields in the **Response Generation** section:

- **Instructions**. Write a prompt describing the AI operation's actions and the desired outcome.

- **LLM model**. Select the language model to use for generating responses. The list of available options depends on the [connected large language model providers](cortex-llm-providers.md).

This field also includes parameters for fine-tuning the predictability and variety of language model responses. We recommend completing the setup and [testing the AI agent](cortex-agent-calibration.md) with default settings first, and then adjusting them as needed if the results are unsatisfactory. To learn more, see the [description of response generation parameters](#generation-parameters).

- **Runtime Type**. Select the execution environment for the AI agent (OpenAI or ReAct). It determines how [tools](#tools-settings) are called. Make sure the specified runtime is supported by the selected language model:

	- **OpenAI**. Function calling is used to execute tools. The model receives descriptions of available tools and sends a structured request to use them. This reliable method works for most tasks.

	- **ReAct**. At each task execution step, the language model provides textual reasoning about its intended actions and then specifies which tool to use in text format.

2. Fill in the fields in the **Execution Environment** section:

- **API mode**. If you selected the OpenAI runtime, specify the interaction mode with the language model: **Chat Completions API** or **Responses API**. We recommend using **Responses API** as it is more up to date. Make sure it is supported by the selected language model provider.

- **Max agent iterations**. The maximum number of processing cycles allowed before sending a response. Each cycle includes calling the language model, executing tools if necessary, and processing the results. Higher values improve answer accuracy but consume more tokens.

- **Max tool response size (in tokens)**. The maximum number of tokens in a tool's response used to build the final AI agent response. Setting a limit reduces token consumption.

- **Enable parallel tool calling**. By default, the agent executes tools sequentially, which is more stable. Enable parallel calls to let the agent run tools simultaneously and reduce user wait times. This option is available only for the OpenAI runtime.

- **Generate response via final\_answer tool Instead of structured output**. For OpenAI runtime, enable this option if the selected language model does not support response generation using a JSON schema (**Structured Output**). This helps obtain a structured final output.

- **Enable stream mode**. Configure this setting based on stream mode availability in your language model. This option does not affect how responses are displayed to the user.

- **Enable reasoning mode**: For OpenAI runtime, enable this option to display the language model's reasoning chain before the final response. Then set up the following parameters:

	- **Reasoning effort**. Select an option determining reasoning detail. Deeper reasoning improves accuracy for complex queries but consumes more tokens.

	- **Response explanation**. Select the length of the displayed reasoning text.

3. Click **Save**.

### Configure response generation parameters

At each generation step, the language model evaluates which token (the smallest unit of text) best continues the response. You can adjust parameters to influence token selection, control response style, and manage variability.

For example, you can set strict factual responses for an AI agent answering questions based on company regulations, and more creative responses for an agent drafting commercial proposals.

To configure parameters:

1. On the **Settings** tab, under the **LLM model** field, click **Additional LLM settings**.

2. In the window that opens, fill in the fields. Available values are specified in the documentation for the language model you are using:

- **Temperature**. A value controlling randomness when selecting the next token during response generation. Lower temperatures produce consistent, predictable, fact-based answers, while higher values yield more creative text.

- **Max context size**. The maximum number of tokens in a prompt.

- **Max response size**. The maximum number of tokens in the agent's response.

- **Seed.** An integer used as the initial value for the random number generator in the language model. When specified, the model generates consistent responses to identical questions.

- **Top-k**. The maximum number of top-probable tokens to choose from during text generation. Used to strictly control response variety. For example, if set to **10**, the model selects from the 10 most likely next tokens and ignores the rest. Lower values produce predictable responses, while higher values increase variety.

- **Top-p**. A number from **0.00** to **1.00** that defines the cumulative probability of tokens considered for the next word. This parameter dynamically limits response variety: only tokens whose cumulative probability equals the specified value are considered. For example, if set to **0.70**, the model chooses only from the most probable tokens. Setting it to **0.95** increases variability by considering less probable options.

- **Presence penalty**. A positive or negative value regulating the repetition of already used tokens in responses. Negative values encourage the model to repeat words and concepts, which is useful for highly specialized tasks requiring strict terminology. Positive values help the model avoid previously used tokens to prevent topic loops.

3. Click **Save**.

4. Save the AI agent settings.

## Step 3. Connect tools to the AI agent

Set up tools that allow the agent to retrieve information from external sources, process data, and execute actions.

To learn more, see [Connect tools to an AI agent or AI operation](cortex-connect-tools.md).

## Step 4. Connect managed AI agents

If you are setting up the main AI agent that users will interact with, assign child managed agents configured for specialized tasks. The main AI agent delegates specific requests to managed agents to deliver more accurate results.

Unlike AI agents used as [tools](cortex-connect-tools.md#agent-tool), managed agents receive the full dialogue context when a task is delegated to them. Once completed, the managed agent returns the answer to the main AI agent.

To connect a child AI agent:

1. On the **Managed Agents** tab, click **+ Add**.

2. In the window that opens, select a configured AI agent and provide task delegation instructions.

3. Click **Save**.

## Step 5. Set an API key to call the AI agent in scripts

You can access the AI agent via API from BRIX scripts or external systems.

To do this, on the **API Keys** tab, configure request authorization for the AI agent: click **+ Add Key**, enter a key name, and select **Chat** in the **Access** field.

You can then call the AI agent in scripts using its API key and the ID from the **Agent API ID** field.

**(cortex-configure-ai-agent-2.png)**

Documentation for the public **BRIX AI** API is available at **https://<BRIX\_AI\_domain>/api/pub/v1/docs**.

## Step 6. Set up security tools

To ensure security when working with an AI agent, **BRIX AI** provides:

- **Guardrails checks** to block user prompts and language model responses that violate defined rules.

- **Masking** to protects against sensitive data leakage by replacing real values in prompts before sending them to the language model.

To learn more about setting up and using these tools together, see [Set up request verification and data masking](guardrails-masking.md).

## Step 7. Set up the AI agent chat widget

Employees interact with AI agents in BRIX using a dedicated widget displayed as an icon in the bottom right corner of the page. Clicking it opens the chat window where users can see the current AI agent name and its [icon](#change-agent-icon), chat with the agent, and switch between available agents.

On the **Widget** tab, you can:

- Change the AI agent name. Enter the name users will see in the chat and when switching between agents.

- Set up quick actions. Specify frequent prompts that will appear as buttons in the AI agent chat. Users can click a button to send the prompt text. The AI agent then processes the request according to the specified [instructions](#tools-settings). Enter each action name on a new line.

**(cortex-configure-ai-agent-3.png)**

To apply your changes, click **Save**.

The AI agent configuration is complete. It will now appear in the list on the **Agents** page.

## Actions on the AI Agents page

To view the list of created AI agents, go to the **AI Agents** page in the left menu of **BRIX AI**. Here you can:

- Find an agent by name. Start typing the AI agent name in the search bar in the top right corner.

- Open the AI agent page. Click the AI agent card to modify its settings.

- Disable an AI agent. Click the toggle next to the agent name to make it unavailable to users and other agents. It will no longer appear in user chats, and other **BRIX AI** components will not be able to access it.

- Perform actions with the AI agent by clicking the three-dot icon next to it and selecting an option:

	- **Edit**: change the AI agent name in **BRIX AI** and in user chats.

	- **Delete**: delete the AI agent and all its settings. This action cannot be undone.

Once configuration is complete, proceed to [test the AI agent](cortex-agent-calibration.md).