How to Manage AI 2.0 Agent Instructions, Libraries, Tools, and Settings
The Agent Builder provides the instructions, knowledge, tools, and settings that control how an AI 2.0 Agent processes information and responds. Changes are saved to the selected draft and can be tested before the version is published.
This article explains how to configure AI Agent instructions, link Libraries and AI Tools, select a model, manage context and execution settings, and define the response format.
Prerequisites
Before configuring an AI 2.0 Agent, ensure that:
- The AI 2.0 Agent has been created.
- Your AI Agent Builder Access is set to Full Access.
- The required libraries, MCP Servers, and API Actions are available, if applicable.
- You have identified the AI Agent’s audience, responsibilities, restrictions, and fallback behavior.
For creation instructions, explore How to Create an AI 2.0 Agent in BoldDesk.
Open the AI Agent in Agent Builder
To open an AI Agent for configuration:
- Go to AI Center > AI Agents.
- Locate the required AI Agent.
- Open More options.
- Select Edit.
The Agent Builder displays the selected AI Agent version and the following configuration areas:
The right side of the page contains Playground, and the upper-right corner displays the version selector and Publish menu.
Configure AI Agent Instructions
Instructions define the AI Agent’s role, responsibilities, supported scope, response behavior, restrictions, escalation conditions, and fallback behavior.
Open Instructions to enter, generate, or improve the instruction content. Review the completed instructions, and then select Save.
The following options are available:
| Option | Purpose |
|---|---|
| Instructions editor | Enter or paste instructions manually. |
| Generate using AI | Create instructions through Prompt Builder based on the requirements provided. |
| Improve Instruction | Improve the clarity, structure, formatting, and completeness of instructions already displayed in the editor. |
| Save | Save the instructions to the selected draft. |
| Discard | Remove unsaved instruction changes. |
Generated and improved instructions are not saved automatically. Review the resulting content, and then select Save.
For the recommended instruction format, reusable template, Prompt Builder guidance, restrictions, escalation rules, and testing recommendations, learn more on How to Create Effective AI Agent Instructions in BoldDesk.
Link Libraries
Libraries provide approved information that the AI Agent can use when responding.
To link a library:
- Open Libraries.
- Click Link Library.
- Select the required library.
- Complete the linking process.
- Confirm that the library appears in the linked libraries list.
To remove a linked library, locate it and click Unlink.
For library-management information, explore How to Add Knowledge Sources to BoldDesk AI 2.0.
Link only libraries containing information suitable for the AI Agent’s intended audience and deployment channels.
Link AI Tools
AI Tools allow an AI Agent to retrieve external information or perform supported operations through MCP Servers and API Actions. Only MCP Servers and API Actions available under AI Tools can be linked to an AI Agent.
To link an AI Tool:
- Open AI Tools.
- Select the required connection type:
-
Click Link MCP Server to connect an MCP Server.
-
Click Link API Connection to connect an API Action.
-
- Select the required MCP Server or API Connection.
- If you selected an MCP Server, select the tools the AI Agent can use.
- Complete the linking process.
- Confirm that the linked MCP Server or API Action appears under AI Tools.
For setup instructions, explore further instructions on How to Create and Configure an MCP Server in BoldDesk and How to Create and Publish API Connections in BoldDesk.
Review MCP Servers and API Actions that retrieve sensitive information or modify external records. Ensure that each tool has only the access required for the intended workflow.
Configure AI Agent Settings
Open Settings to configure the model, output length, tracing, context management, reasoning, execution controls, external tools, and response format.
System instructions guide how the AI agent processes and responds to user requests, while AI Agent skills and worker agents (Agent Orchestration) are made available as tools. These tools are not executed automatically. Instead, the AI agent evaluates each user query against its configured instructions and invokes the appropriate skills or worker agents only when required to fulfill the request.
The Settings page contains:
- Configuration
- File Upload
- Execution
- Trace Logging
- Context Management & Reasoning
- Response & Execution Controls
- Tool Configuration
- Response Format
- Agent Orchestration
After changing a setting, click Save. Click Discard to remove unsaved changes.
Configure the Model and Output Length
| Setting | Description |
|---|---|
| Model | Specifies the AI model used to process requests and generate responses. |
| Max output tokens | Controls the maximum length of the generated response. |
| Reset to default | Restores the recommended default output-token value. |
Select a model and output-token limit appropriate for the complexity and expected response length of the AI Agent’s workflow.
The available models depend on the models enabled for the BoldDesk AI workspace.
File Upload
Toggle this setting on to enable AI agents to support file attachments for Response, Background, and AI Trigger Orchestration agents. When a ticket is created or updated with attachments, supported files are automatically included in the AI agent request along with the ticket content.
- File upload can be enabled or disabled at the individual agent level.
- Multiple file attachments are supported.
- Attachments can be uploaded directly through the agent’s File Upload setting.
Supported File Formats
The supported file formats for file upload are discussed below.
Image Formats
| Format | MIME Type |
|---|---|
| PNG | image/png |
| JPG | image/jpeg |
| JPEG | image/jpeg |
Document Formats
| Format | MIME Type |
|---|---|
application/pdf |
|
| TXT | text/plain |
| MD | text/markdown |
| HTML | text/html |
| CSV | text/csv |
Attachment Limits
| Limit | Value |
|---|---|
| Maximum attachment count | 20 files |
| Maximum file size | 5 MB per file |
| Maximum total request size | 50 MB |
Please check the visual below for more insights.
Only files that meet the supported format and size requirements are included in the AI request. Unsupported file types or files that exceed the supported limits are ignored.
Execution
The Execution section controls how long an agent can run and whether it can execute code in an isolated sandbox environment.
Background Agent Execution
Background agent execution allows the AI agent to continue running in the background for long-running tasks. To enable Background agent execution:
- Go to Execution.
- Turn on the Background agent execution toggle.
- Review the confirmation message.
- Click Confirm.
Enabling Background agent execution creates a new draft version of the agent with background execution enabled. This action cannot be undone.
Sandbox Code Execution
Sandbox code execution allows the AI agent to write and run code in an isolated sandbox environment to compute answers, validate output, or reproduce errors. To enable Sandbox code execution:
- Go to Execution.
- Turn on the Sandbox code execution toggle.
- Select the desired Environment for sandbox runs:
- Small - 1 CPU, 512 MB memory
- Medium - 2 CPUs, 2048 MB memory
- Large - 4 CPUs, 4096 MB memory
Sandbox environments are short-lived and isolated for each run. Files and installed packages are discarded when the run ends. The selected environment is applied to all sandbox runs for the agent.
Configure Trace Logging
Turn on Trace Logging to record selected AI execution details for troubleshooting and monitoring.
LLM Tracing
| Setting | Description |
|---|---|
| Log LLM Inputs | Records the messages and context sent to the AI model. |
| Log LLM Outputs | Records generated responses and applicable tool or action calls. |
Tool Tracing
| Setting | Description |
|---|---|
| Log Tool Schemas | Records definitions and parameters of tools available to the AI Agent. |
| Log Tool Responses | Records results returned by linked tools. |
Trace logs can contain customer messages, system context, tool parameters, and tool responses. Enable tracing according to your organization’s privacy, security, and data-retention requirements.
Configure Context Management and Reasoning
Expand Context Management & Reasoning to configure:
| Setting | Description |
|---|---|
| History message limit | Specifies how many previous conversation messages are retained as context. |
| Number of Chunks | Specifies how many retrieved knowledge chunks are provided to the model. |
| Reasoning effort | Controls the available reasoning depth. |
| Reasoning verbosity | Controls the level of detail in applicable explanations. |
Choose values that provide sufficient context without adding unnecessary conversation history or unrelated knowledge.
Configure Response and Execution Controls
Expand Response & Execution Controls to configure:
| Setting | Description |
|---|---|
| Grounded response only | Restricts responses to available knowledge and uses fallback behavior when relevant information is unavailable. |
| Custom error message | Specifies the message displayed when an AI or system error occurs. |
| Fallback instruction | Defines the response used when relevant information cannot be found. |
| Max iterations | Limits the number of processing attempts during one execution. |
Use a fallback instruction that directs the customer to an appropriate next step, such as creating a ticket, contacting the configured support email address, or requesting a human agent.
Configure External Tool Access
Expand Tool Configuration to configure:
| Setting | Description |
|---|---|
| URL Context Tool | Allows the AI Agent to retrieve information from a provided URL. |
| Web Search | Allows the AI Agent to retrieve supported current information from the web. |
Enable these settings only when external information is required for the AI Agent’s workflow.
Configure the Response Format
Expand Response Format and select the required output type:
| Format | Description |
|---|---|
| Text | Generates natural-language responses for customer or agent conversations. |
| JSON | Generates structured JSON for integrations or automated processing. |
| Structured output | Generates output according to a predefined schema. |
Use Text for conversational workflows. Use JSON or Structured output when a system or orchestration rule must process specific output properties.
Save and Test the Configuration
After configuring the AI Agent:
- Review the instructions, libraries, tools, and settings.
- Click Save in each area containing changes.
- Confirm that the unsaved-changes warning is no longer displayed.
- Open Playground.
- Test representative questions, alternate wording, missing-information scenarios, tool use, and applicable edge cases.
- Update and retest the configuration when the results do not meet the intended requirements.
For detailed testing instructions, learn more on How to Test an AI 2.0 Agent in BoldDesk.
Saving updates the selected draft. Saving does not publish the version or make Deploy available.
Assign and Deploy AI 2.0 Agents Across BoldDesk Channels
After the draft produces the expected results, publish the version and map it to the required channels.
For instructions, explore How to Assign and Deploy AI 2.0 Agents Across BoldDesk Channels.
Troubleshooting
Instructions Changes Are Not Retained
Confirm that you clicked Save. If the unsaved-changes warning remains visible, review and save the changes again.
The AI Agent Generates Irrelevant Responses
Review the instructions, linked libraries, context settings, grounded-response setting, and fallback instructions.
A Required Tool Is Not Available
Confirm that the MCP Server or API Action exists under AI Tools, is available for selection, and is linked to the AI Agent.
The AI Agent Cannot Find an Answer
Confirm that the required information exists in a linked library and is available to the AI Agent. Review the grounded-response and fallback settings.
The AI Agent Uses the Wrong Tool
Review the AI Agent instructions and linked tools. Clearly define the conditions under which each tool can be used.
Frequently Asked Questions
-
Can I generate AI Agent instructions automatically?
Yes. Use Generate using AI, and then review and edit the generated instructions. -
What is the difference between Libraries and AI Tools?
Libraries provide knowledge. AI Tools retrieve external information or perform supported operations. -
Can an AI Agent use both an MCP Server and API Actions?
Yes. Link only the tools required for the intended workflow. -
Can an AI Agent Retrieve Information from Another AI Agent or Product?
An AI Agent generates responses using the instructions, knowledge libraries, and AI Tools configured for that specific agent.
The AI Agent does not automatically:- Search another AI Agent’s knowledge libraries.
- Inherit knowledge sources configured for another agent.
- Retrieve information from an unrelated product or external platform.
- Use an API connection or MCP server that has not been made available to it.
If one AI Agent answers a query but another does not, compare their configurations and verify that:
- The relevant knowledge library is linked to the AI Agent.
- The required content exists in the linked library.
- The current draft or published version contains the correct library configuration.
- The AI Agent’s instructions do not restrict the query to another product or domain.
- Any required API Action or MCP server is configured and available.
- The correct AI Agent version has been published and deployed.
To support multiple products with one AI Agent, link the approved knowledge sources for those products and define clear instructions explaining when each source should be used.