Custom agents transform how organizations interact with their content by enabling tailored AI assistants built on Box's AI Agent framework. Rather than relying on generic AI responses, agent creators can configure specialized solutions that align with specific business needs, workflows, and knowledge bases.
Once you have enabled Box AI Studio, go to the AI Studio tab to see the list of agents available and start building one yourself. To get started, click on New Agent.
Creating a New Agent
Core Configuration Elements
Every agent requires a Name and can be enhanced with several optional configurations:
| Element | Purpose |
| Details |
Identifies the agent (required) with name and description
|
| Custom Instruction | Defines personality, tone, behavior, constraints, and decision-making style |
| Knowledge | Binds the agent to specific files, or hubs for reference |
| Suggested Prompts | Pre-defined examples shown to users to encourage interaction |
| Availability on Box | Control where users have access to the agent |
| Advance | Override default AI models or let Box optimize automatically |
Agent Configuration
From the right side panel, customize the agent settings:
Details
From here you can:
- Change the icon of the agent
- Set the name for the agent
- Explain the use and intent of the agent and its capabilities
Custom Instructions
Custom instructions shape how your agent behaves including its reasoning style, communication norms, and task approach.
What custom instructions can do:
- Set personality, tone, and voice
- Enforce step-by-step workflows ("First analyze, then propose, then act")
- Prioritize verification before responding
- Specify output formats (headings, bullets, citations, structured JSON)
- Encourage or discourage risk-taking ("When unsure, always ask a question")
- Direct the agent to favor certain tools when multiple are available
What they cannot do:
- Override human approval workflows
- Break safety policies enforced in code
- Access restricted data or classifications
- Force tool execution when permissions block them
Example: You're an expert in marketing campaigns. You assist copy writers by providing short, concise, and creative answers.
Guidelines for Box AI Questions
Box AI pulls information only from the document you loaded in preview. If you ask questions outside the scope of the document, Box AI informs you that it cannot answer with the information provided.
Best practices:
-
Be as specific as possible. Use parameters such as numbered lists, brevity, tables, and central themes or key points.
- OK: "List key points"
- Better: "Can you list the key points in a numbered list?"
- OK: "What's the point of this document?"
- Better: "Can you briefly and succinctly outline only the most important points with a list?"
- Stay within the scope of the document
- Focus on text-based responses only
Consider adjusting the following to refine responses:
- Custom instructions
- Model type
- Custom system prompts
Attaching Knowledge Sources
Reference knowledge using @mentions within custom instructions to specify what content the agent uses and how it should be applied. This approach ensures agents remain grounded in authoritative sources.
Single source example:
Reference the example below using @mention for a single sources:
When answering policy questions, reference @Company_Handbook as the single source of truth. If information isn't found, acknowledge this and offer alternatives.
Multi-source with priority:
Reference the example below using @mention for multiple sources:
For product questions, combine information from:
- @ProductSpecs (highest priority)
- @ReleaseNotes (secondary)
- @FAQ (lowest priority)
If conflicts exist, always use @ProductSpecs as correct.
Attaching Content
You can attach files and Hubs as knowledge, with explicit priority rules for handling conflicts between sources. Knowledge can also be used for transformation tasks—summarizing, simplifying, or rewriting content while maintaining factual accuracy.
To attach content:
- Click Select Content
- From the file viewer, select the files and/or Hubs you want to add
Suggested Prompts
Create custom prompts to use with your agent. You can add up to 4 custom questions that appear when users interact with Box AI.
To add suggested questions:
- Toggle on Use custom suggestions
- Click Add +
- Add your custom question (click the X icon to remove)
Example prompts for various use cases:
- What are the top 3 differentiators of [Product Name] for an enterprise buyer?
- How does [Product Name] compare to [Competitor Name] for [Use Case or Industry]?
- Write a 3-sentence value proposition for [Product Name] tailored to [Persona, e.g., IT leaders or CMOs].
Availability on Box
Configure where your agent appears across Box through the Availability on Box settings. Platforms include:
- AI Home
- Files
- Hubs
Availability expands as your agent passes evaluation tests for increasingly complex knowledge configurations—from single files to multiple files, and hubs.
All usage on Custom Agents will be charged against AI Units. Allow queries to exceed the default capability limit for optimal results.
Usage
Expanded Mode is enabled by default for all Custom Agents in AI Studio, allowing queries to exceed standard capability limits for optimal results. Agent creators can disable this feature at any time.
- After enabling, set a maximum limit for AI Units; default value is 1,000.
Advanced Settings
Choose what model the agent uses when answering questions:
You can select Auto or from the list of other providers available in your organization.
Enabling Pro Mode
Pro Mode is enabled by default for all Custom Agents created in AI Studio. Agent creators can turn Pro Mode off from within AI Studio.
When Pro Mode is enabled, the agent uses higher thinking levels and may access more capable and newer models. It supports advanced agent behaviors such as recursive reasoning and enhanced document or video analysis.