# Configuring Custom Agents
Veeva AI agents use a Large Language Model (LLM) to perform a set of agent actions in Vault and determine the actions and responses [Veeva AI Chat](/en/lr/950642/) can provide to users. You can define the agent's objective, context, and action's instructions, which inform the LLM of the agent's role, responsibilities, and parameters in which it can operate, ensuring agent actions are executed as you intend. A Vault can include standard and custom agents. This article describes how to configure custom agents for use in your Vault. agents are Vault-specific, meaning they cannot interact with data on other Vault domains or outside of your Vault. In addition, if no agents are enabled in your Vault, users cannot interact with the Veeva AI Chat window. See below for definitions of terms used in this article: * **Agent:** Defines a set of agent actions that can be performed on a document or object record in your Vault. * **Agent Objective**: A description of the agent's roles and responsibilities, similar to a job description. * **Agent Context:** Defines the information an agent knows about your Vault, allowing the agent action to return this information in a response. Agent context can include document content and data such as document fields, object fields, and object relationships. * **Agent Action:** The actions users can select in the Veeva AI Chat window, such as _Summarize Document_ and _Translate Record_. agents perform agent actions based on the provided agent objective, context, and instructions. * **Agent Tools:** You can assign [agent tools](/en/lr/950647/) to agent actions. When an agent action is executed in Veeva AI Chat, your LLM can request agent tools and use Vault's tool response to complete the agent action. ## Configuration Overview {#configuration-overview} The following list is an overview of configuring custom agents in your Vault: 1. Configure a custom [LLM Connection][0] if you are not using a Veeva-provided LLM connection. This action establishes a connection between your Vault and your LLM. 2. Set up your custom LLM connection details in **Admin** > **Settings** > [**Veeva AI Settings**][2]. 3. Configure the agent objective using a description of the agent's intended roles and responsibilities. 4. Configure the parameters of the agent context. 5. Configure the agent action by defining a description and instructions on how to execute the action. 6. Optional: Assign an [agent tool][1] to the agent action. ## Configuring a Custom LLM Connection {#configure-custom-llm-connection} If you are not using a Veeva-provided LLM, you must set up a connection that allows Vault to communicate with your own LLM provider. This connection is required so agents can send Vault data to your LLM, which allows it to understand how to execute and respond to agents. To begin establishing the custom LLM connection, set up an _LLM_ [_Connection Authorization_](/en/lr/53358/) record. When configuring a custom LLM connection, it is recommended to enable a guardrail in your LLM account provider. This feature allows you to prevent Veeva AI Chat from engaging in inappropriate conversations. We recommend selecting the _Standard_ content filter in AWS Bedrock and the default guardrail in Azure AI Foundry. ### AWS Bedrock Connection {#aws-bedrock-connection} If you are using an AWS Bedrock LLM, ensure you have following information before beginning this process. You can find this information in your AWS Bedrock LLM account: * Access Key * Secret Access Key * AWS Region * Model ID Follow the steps below to create the _LLM_ _Connection Authorization_ record for an AWS Bedrock LLM: 1. [Create](/en/lr/53358/#Create_Connections) a _Connection Authorization_ record and select **Client Credential** as the **Connection Type**. 2. Enter a **Name** for this connection. 3. Set the **Status** to **Active** or **Inactive**. By default, new _Client Credential Connection Authorization_ records are created in the _Active_ status. 4. Enter your **Access Key** in the **Client ID** field. 5. Click **Save**. 6. Select **Set Client Secret** from your new _Client Credential Connection Authorization_ record's **Actions** menu. 7. Enter your **Secret Access Key** in the **Client Secret** and **Confirm Client Secret** fields. 8. Click **Save**. 9. Create another _Connection Authorization_ record and select **LLM** as the **Connection Type**. 10. Enter a **Name**. 11. Enter an **API Name**. 12. Select **AWS Bedrock** from the **Provider** drop-down. 13. Enter the **Model ID** in the **Model Name** field. 14. Select the _Client Credential_ _Connection Authorization_ record you configured in steps 1-5 from the **Authorization** drop-down. 15. Enter the **AWS Region** in the **Region** field. 16. Click **Save**. The _LLM Connection Authorization_ record is now available for an AWS Bedrock LLM connection. Next, select your [default LLM connection][2]. ### Azure AI Foundry Connection {#azure-ai-foundry-connection} If you are using an Azure AI Foundry LLM, ensure you have following information before beginning this process. You can find this information in your Azure AI Foundry LLM account: * API Key * Azure Open AI endpoint * Model ID Follow the steps below to create the _LLM Connection Authorization_ record for an Azure AI Foundry LLM: 1. [Create](/en/lr/53358/#Create_Connections) a _Connection Authorization_ record and select **API Key** as the **Connection Type**. 2. Enter a **Name** for this connection. 3. Set the **Status** to **Active** or **Inactive**. By default, new _Client Credential Connection Authorization_ records are created in the _Active_ status. 4. Click **Save**. 5. Select **Set API Key** from your new _API Key Connection Authorization_ record's **Actions** menu. 6. Enter the **API key** in the **API Key** and **Confirm API Key** fields. 7. Click **Save**. 8. Create another _Connection Authorization_ record and select **LLM** as the **Connection Type**. 9. Enter a **Name**. 10. Enter an **API Name**. 11. Select **Azure** from the **Provider** drop-down. 12. Enter the **Model ID** in the **Model Name** field. 13. Select the _API Key_ _Connection Authorization_ record you configured in steps 1-5 from the **Authorization** drop-down. 14. Click **Save**. The _LLM Connection Authorization_ record is now available for an AWS Bedrock LLM connection. Next, select your [default LLM connection][2]. ### How to Set Up Veeva AI Settings {#set-up-veeva-ai-settings} Veeva AI Settings allows you to set up details related to your custom LLM connection. You can select your basic and advanced LLM connection, enter a default AWS guardrail, and enter a custom LLM connection's maximum token output. If you are using Veeva-provided LLM connections, you can skip many of these settings. To set up your Veeva AI Settings: 1. Navigate to **Admin** > **Settings** > **Veeva AI Settings**. 2. Click **Edit**. 3. Select the **Basic LLM** and **Advanced LLM** connection. You can select your [custom configured LLM][0] for either option or **Veeva AI Basic** and **Veeva AI Advanced** for Veeva-provided LLM connections. Your custom agents will operate based on the selected LLMs. It is recommended to use _Basic LLM_ for agents that perform simple actions, such as _Summarize Document_ and _Advanced LLM_ for agents that perform complex actions, such as those that require agent tools. 4. If you are using a custom [AWS Bedrock LLM connection][8] with a guardrail configured, enter the **Default AWS Guardrail ID** and **Version**. 5. Optional: Clear the **Auto-switch Chat Conversation** setting if you want to remove the [conversation switching ability in Veeva AI Chat](/en/lr/950642/#switch-conversations). 6. Enter your custom LLM connection's number of **Maximum Output Tokens**. You can enter a maximum of 10,000 and minimum of 512 tokens. The default is 4,096. If _Basic LLM_ and _Advanced LLM_ are both custom LLM connections, this field covers the maximum token output for both LLMs. 7. Click **Save**. Your Veeva AI settings are now established. You can return here to change any of these settings if necessary. You can also use Veeva AI Settings to track your [LLM token usage](/en/lr/1000971/#llm-token-usage).
### Test Your LLM Connection {#test-llm-connection} Use the following steps to test your LLM connection to ensure there are no issues: 1. Ensure you have a security profile with the necessary [permissions][3] to configure custom agents and use Veeva AI Chat. 2. Navigate to **Admin** > **Agents** > **Base Document Chat Agent** > **Actions** > **Edit**. 3. Set the **Status** to **Active**. 4. Click **Save**. 5. Navigate to a document in your **Library**. 6. Click the **Veeva AI** icon (Global AI Chat Icon) in the upper right of the Vault interface when viewing a document via the Doc Info page. 7. Select **Summarize Document**. If your LLM connection is properly configured, Veeva AI Chat responds with a document summary. You can now begin configuring custom agents. ## Standard Agents {#standard-agents} By default, your Vault includes two standard agents with the following agent actions: * _Base Document Chat Agent_ * _Summarize Document_ * _Translate Document_ * _Ask Questions_ * _Base Object Chat Agent_ * _Summarize Record_ * _Translate Record_ * _Ask Question_ These default agent actions are only available to your users if you activate the _Base Document Chat Agent_ and _Base Object Chat Agent_ in your Vault. You cannot edit or delete standard agents or any of their agent objectives, context, or actions. These agents fall under the _Base Document Class_ and _Base Object Class_ respectively. Currently, when configuring a custom agent, you can only create agents within these classes. ## How to Configure a Custom Agent {#configure-custom-agent} To configure a custom Agent: 1. Navigate to **Admin** > **Configuration** > **agents**. 2. Click **Create** to access the _agent Configuration_ page. 3. Enter a **Label**. The **Name** value is populated based on the **Label**. 4. Set the **Status** to **Active** or **Inactive**. By default, new agents are created in the _Inactive_ status. If the agent is **Inactive**, its related agent actions are not displayed in Veeva AI Chat. An agent action is required to set the _Status_ to _Active_. Once activated, an [agent user][10] is either created or reused if available. 5. In the **Agent Class** drop-down, select **Base Document Class** to create a document agent or select **Base Object Class** to create an object agent. You cannot undo this selection. * If you selected **Base Document Class**, select the **Document Type** where this agent can perform agent actions. * Optional: If you selected **Base Object Class**, select the **Primary Object** and **Object Type** where this agent can perform agent actions. 6. Enter a **Description**. Ensure the description is clear and precise as Vault sends this information to your LLM to help it understand the basic purpose of the agent. 7. Select the agent's **Model**: [**Basic** or **Advanced**][2]. This setting determines whether the agent will operate with your Basic or Advanced LLM. 8. Enter the agent's **Objective**. This description should reflect the roles and responsibilities of the agent. You can write the description as if you are talking to the agent. For example, a Site Visit agent objective could read, "Your primary objective is to summarize, quality check, and translate specific site visit object records." Use [field reference syntax](/en/lr/796234/#word-fo-field-reference-syntax) to include attributes such as fields, labels, and user names in the agent objective. Select the {…} icon to insert object or document-related [tokens](/en/lr/6382/) into the agent objective. 9. Optional: Enter a **Supplemental Objective**. This field is only available on standard and system-managed agents based on application family availability. Use supplemental objectives to add supporting information to the agent objective. Supplemental objectives are not meant to replace the original agent objective. 10. Click **Save**. The basic details on the agent are now configured. Next, configure the [agent context][4].
Create Custom Agent Configuration Page ### Agent Users {#agent-users} When a custom agent is activated, Vault creates and assigns an _Agent User_ record to the agent. The agent user allows agent actions to execute without a user at the keyboard, such as through a job or email processor. Once the agent user is assigned, the _Agent User_ field on the _Agent Configuration_ page is populated with a link to the _Agent User_ record. These records are system-managed and include the following fields: * **Username**: A username that follows a specific pattern: `[agent][agent_name]@domain.com`. For example, `[agent]deviation__c@vernbio.com` is the _Deviation_ agent's agent user. * **Email**: `no-reply@veeva.com` * **First Name**: Agent _Label_ in the Vault's base language. For example, _Deviation_. If the agent's _Label_ is updated, this field is updated as well with the new _Label_. * **Last Name**: Agent * **Language**: Base Vault _Language_ * **Locale**: Base Vault _Locale_ * **Time Zone**: Default Vault time zone * **Security Policy**: System Managed * **License Type**: Full * **Application License**: Null * **Security Profile**: Read-only User You can only edit the _Security Profile_ and any custom fields added to the _User_ object on _Agent User_ records. Some fields, such as _Language_, _Locale_, and _Security Profile_, may vary for standard agents based on application. If an agent is deleted, Vault sets the agent user's _Status_ to _Inactive_. Vault can reuse this agent user if a new agent is created or activated with the same _Name_.
#### Changing an Agent's Name If the agent's _Name_ changes, Vault creates a new _Agent User_ record using the new agent _Name_ and deactivates the previous _Agent User_ record. If an _Agent User_ record already exists with the agent's new _Name_, Vault reuses that record and associates it to the agent. For example, Vault A contains an agent (`agent1__c`) associated with an agent user (`[agent]agent1__c@vernbio.com`). The agent's _Name_ is updated to `agent2__c`. Then, Vault creates or reuses an _Agent User_ record with the _Name_ `[agent]agent2__c@vernbio.com`.
#### Username on Multiple Domains Custom agents can have the same _Name_ on multiple Vaults within the same domain. This scenario causes each agent user to have the same username on each Vault. In this scenario, the agent user's _First Name_ is updated based on the agent in the corresponding domain. For example, Vault A contains an agent with the following details: * **Name**_:_ `product__c` * **Label**: _Product_ * **Agent User User Name**: `[agent]product__c@vernbio.com` Vault B on the Vault A domain contains an agent with the same _Name_ and _Label_. In this case, if the Vault B agent is assigned an agent user, the _First Name_ of the agent on Vault A changes to _Product2_ while Vault B creates an agent user based on the existing domain agent user with _First Name_ set to _Product_. #### Audit Behavior When an agent user is associated with an agent, any agent actions executed without a user at the keyboard are logged in the audit trail as performed by the agent user. If the agent action executes agent tools that generate audit entries, such as creating or updating records, the agent user is also logged as the user performing those actions. This includes updates to _Created By_ and _Last Modified By_ fields. In the case of agent actions executed by jobs, the agent user is logged in the audit trail only if it or a group is assigned to the _Job Owner_ role. Agent actions executed by a user at the keyboard, such as through Veeva AI Chat, with an agent user assigned to the agent are logged as `[agent user's user name]` on behalf of `[keyboard user's user name]`. ## How to Configure Agent Context {#configure-agent-context} Agent context defines information about a document or record available to an agent action when it is executed. The agent action uses this information to return relevant details to users in Veeva AI Chat. For example, if you configure a _Summarize Document_ action to perform a spell check, you can use the agent context to instruct the agent action to spell check only the document text, certain fields in the document, or the document source file. You can also use agent context to instruct the agent action to return specific field values on a record. For example, a _Summarize Record_ action could return the _Last Modified Date_ value and show a timeline of changes to the record. ### How to Configure Document Agent Context {#document-agent-context} To configure agent context for a Base Document Class agent: 1. Select **Context** on the _Agent Configuration_ page. 2. Click **Create**. 3. Select **Document Data** **and Content** or **Related Document Data and Content** from the **Type** drop-down. 4. Enter a **Label**. The API **Name** value is populated based on the **Label** value. 5. Set the **Status** to **Active** or **Inactive**. By default, new agent context is created in the **Active** status. 6. Optional: Enter a **Description**. Ensure the description is clear and precise as Vault sends this information to your LLM to help it understand and execute the agent context. 7. Select **Yes** on the **Always Include** setting to automatically include this agent context with each agent action configured in this agent. Select **No** to manually include the agent context with each agent action as necessary. 8. If you selected **Related Document Data and Content**, select a **Relationship Type**. Only [_Single Use_ document relationships](/en/lr/9069191/#relationship-settings-filters) are available for selection. 9. Optional: Enter **Document Fields** to prompt the agent action to display the field label and values in the Veeva AI Chat response. This field is required if you do not select an option from the **Include Document Content** picklist. You can click [**Generate Default**][5] to display a template you can use to enter the document fields. After saving the agent context, click [**Test**][9] to view the template's output with a document. 10. Optional: Select one or more options from the **Include Document Content** picklist: **Text**, **Images**, or **Source File**. Select **Text** to include all document text in the agent action. Select **Images** to export each page in the document as an image. Select **Source File** to include the document's source file in the agent action. This field is required if **Document Fields** is left blank. 11. Optional: Select **Use Structured Text Format** to prompt the agent action to respond in an XML-based format that separates each page of content with XML tags. 12. Click **Save**. The agent context is now available for use with agent actions configured within your _Base Document Class_ agent. Next, configure the [agent actions][6].
Create Document Agent Context ### How to Configure Object Agent Context {#object-agent-context} To configure agent context for a _Base Object Class_ agent: 1. Select **Context** on the _Agent Configuration_ page. 2. Click **Create**. 3. Enter a **Label**. The API **Name** value is populated based on the **Label** value. 4. Set the **Status** to **Active** or **Inactive**. By default, new agent context is created in the **Active** status. 5. Optional: Enter a **Description**. Ensure the description is clear and precise as Vault sends this information to your LLM to help it understand and execute the agent context. 6. Select **Yes** on the **Always Include** setting to automatically include this agent context with each agent action configured in this agent. Select **No** to manually include the agent context with each agent action as necessary. 7. Enter **Object Fields** to prompt the agent action to display the field labels and values in the Veeva AI Chat response. You can click [**Generate Default**][5] to display a template you can use to enter the object fields. After saving the agent context, click [**Test**][9] to view the fields used with an object record. 8. Click **Save**. The agent context is now available for use with agent actions configured within your _Base Object Class_ agent. Next, configure the [agent actions][6]. Create Object Agent Context ### Agent Context Field Configuration {#agent-context-field-configuration} Agent context with document or object fields prompts the agent action to extract the field values and display them in Veeva AI Chat responses. For example, you can use agent context to prompt the _Summarize Document_ action to return the _Name_, _Created Date_, and _Last Modified Date_ of a document the user is viewing in Vault. You can also use agent context to return field values from related and child records in a _Summarize Record_ action. Click **Generate Default** to display a template you can use to add fields to the agent context. Document agent context templates include fields from the agent's selected _Document Type_ and those available on the Doc Info page. Object agent context templates include fields from the assigned layout of the agent's _Primary Object_ and any child or related objects. You can use [Microsoft Word template syntax](/en/lr/796234/#microsoft-word-template-syntax) and [field reference syntax](/en/lr/796234/#word-fo-field-reference-syntax) when modifying the template to reference specific field values and labels.
#### Document Agent Context Example {#document-agent-context-example} Document Agent Context Fields Example #### Object Agent Context Example {#object-agent-context-example} Object Agent Context Fields Example You can use the template to access child and grandchild records. For example, _Class Section_ is a child of _Class_, and _Student Registration_ is a child of _Class Section_. In this case, the template would appear as displayed in the image below. In this example, a `WHERE` clause is used in the `${Rowset()}` syntax to filter out inactive records as this syntax returns both active and inactive records by default. Object Agent Context Fields with Grandchild and WHERE Clause
### Test Output {#test-agent-context-output} You can test the output of your document and object fields to ensure the values are populated as expected. To test your output, save the agent context, then click **Test** next to the _Document Fields_ or _Object Fields_. When testing the output of document fields, you must select a document version based on the agent's document type. When testing the output of object fields, you can only select records from the _Primary Object_ or object type if available. ## How to Configure Agent Actions {#configure-agent-action} Agent actions define the tasks an agent can execute through Veeva AI Chat. Agent actions follow the specific instructions you provide as well as any assigned agent context or agent tools. It is important to ensure the instructions are clear and precise, as ambiguity can lead to errors when the agent action is executed. To configure an agent action: 1. Select **Actions** on the _Agent Configuration_ page. 2. Click **Create**. 3. Enter a **Label**. The API **Name** value is populated based on the **Label** value. 4. Set the _Status_ to **Active** or **Inactive**. By default, new agent actions are created in the same status as their associated [agent][11]. 5. Enter a **Description** of the agent action. Ensure the description is clear and precise as Vault sends this information to your LLM to help it understand the agent action. 6. Enter the agent action's [**instructions**][7]. Your LLM uses these instructions to understand how to execute and respond to the agent action. Select the {…} icon to insert object or document-related [tokens](/en/lr/6382/) into the instructions. 7. Select **Support Chat** to display this agent action in the Veeva AI Chat window. Select **No** to hide it from the Veeva AI Chat window. Leave this field unselected to hide the agent action from the chat window. 8. Select **Hide in Chat** to hide this agent action from the Veeva AI Chat window. The chat window can still route to this agent action based on the user's input. This field is available only if **Support Chat** is selected. 9. Click **Save**. Your agent is now configured and users can select the agent actions in Veeva AI Chat. Create Agent Action ### Writing Agent Action Instructions {#write-agent-action-instructions} When writing the agent action's instructions, you can use simple instructions, such as "Summarize document" or slightly more complex details that define the structure of the agent action's response. For example, if you are configuring a _Summarize Document_ agent action, your instructions could prompt the agent action to respond with a header for a one-line summary, specific document metadata, and related documents. To reference field values from the primary object, related objects, or documents, use Word formatted output [field reference syntax](/en/lr/796234/#word-fo-field-reference-syntax). ### Adding Agent Context and Tools to an Action {#add-agent-context-tool-to-action} You can assign agent context and [agent tools](/en/lr/950647/) to the agent action after it is saved. To add agent context and agent tools: 1. On the _Agent Action Configuration_ page, click **Available Context** or **Available Tools.** 2. Click **Add**. 3. Select the agent context or agent tool from the dialog. 4. Click **OK**. The agent action will now operate within the parameters of the agent context and/or agent tool you assigned. Add Agent Context and Tools to Agent Action Once the agent action is saved, click **Actions** > **Edit**. Then, in the **Tool Evaluation** drop-down, select **Auto** to allow your LLM to decide when to execute the agent tool. Or, select **Required** to prompt your LLM to use the agent tool each time the agent action is executed. Agent Tool Evaluation ## Limits {#limits} * You can create up to 500 custom agents per Vault. * An agent can contain up to 20 agent actions, agent contexts, and agent tools. * If _Images_ is selected from the _Include Document Content_ drop-down, only the first 20 pages are included. ## Related Permissions {#related-permissions} The following permissions control your ability to configure agents: | Type | Permission | Access Details | | --- | --- | --- | | Admin | Admin: Agents: Read, Create, Edit, Delete | Ability to view, create, edit, and delete agents. | | Admin | Admin: Tools: Read, Create, Edit, Delete | Ability to view, create, edit, and delete agent tools. | | Agents | All Agents: Execute | Ability to select all agent actions within Veeva AI Chat. | | Agents | [Agent]: Execute | Ability to execute a specific agent and their configured agent actions in Veeva AI Chat. | | Objects | Agent Instance: Read | Ability to view the _Agent Instance_ object. | | Objects | Agent Action Execution: Read | Ability to view the _Agent Action Execution_ object. | | Applications | Vault Actions: Veeva AI Chat: Use Chat | Ability to view and interact with Veeva AI Chat. | [0]: #configure-custom-llm-connection [1]: #add-agent-context-tool-to-action [2]: #set-up-veeva-ai-settings [3]: #related-permissions [4]: #configure-agent-context [5]: #agent-context-field-configuration [6]: #configure-agent-action [7]: #write-agent-action-instructions [8]: #aws-bedrock-connection [9]: #test-agent-context-output [10]: #agent-users [11]: #configure-custom-agent