Box AI Studio API allows developers to create and manage powerful AI agents for their organizations.
For instance, you can create an AI agent that acts as a compliance consultant, answering questions regarding customer documentation while considering specific compliance rules and standards.
Some of the advanced features of AI agents include configuring and customizing prompts with specific instructions. For example, you can specify how the agent should respond in a way that reflects the business’s context and brand tone.
Secure AI Models for AI Agents
Additionally, there are secure AI models available that you can choose from to power your AI agents. For more details on the latest models offered by our trusted AI model providers, visit our developer documentation page.
The list of models may change depending on the model availability. Models offered in Preview mode have not been fully performance-tested at scale and are made available on an as-is basis. You may experience variability in model/output quality, availability, and accuracy.
How to enable Box AI Studio
You can enable Box AI Studio in the Box Admin Console. Follow these steps:
- Go to Enterprise Settings.
- Select the Box AI tab.
- Edit the configuration under the option labeled Box AI Studio disabled.
AI agents can be enabled for selected users and groups or all enterprise users.
Box AI Studio is available only for Enterprise Advanced accounts.
Press enter or click to view image in full size
Start interacting with Box AI Studio API
If you’re new to the Box Platform, visit our developer guide to learn how to create your first Box Platform app.
To perform a Box AI Studio API call, you need a Box Platform app with the appropriate scope enabled. Navigate to the Box Developer Console, select your chosen Box Platform app, go to the Configuration tab, scroll down to the Application Scopes section, and enable the Manage AI scope.
When the application’s scopes or access level change the application needs to be re-authorized. Check more details in developer documentation.
Now, you can start interacting with the Box AI Studio API. It consists of five endpoints:
Create AI Agent
I used Postman to interact with Box API. You can follow this quick start guide for an easy setup.
In my first API call, I created a professional assistant specialized in enterprise marketing and content strategy. Let’s break down some of the parameters within this request.
I passed three required parameters:
{
"type": "ai_agent",
"access_state": "enabled",
"name": "Professional assistant"
}However, this is not sufficient to create an AI agent. We need to specify at least one capability for the agent. There are three available capabilities, ask , text_gen , and extract. In my example, I chose the text_gen capability.
In the text_gen object, I specified several options, including the AI model that will power this agent. I also added a system_message, which helps the LLM understand its role and purpose. You could also add additional properties, likecustom_instructions to further specify requirements for the agent. Here you can see the request body I used for this example call.
{
"type": "ai_agent",
"access_state": "enabled",
"name": "Professional assistant",
"text_gen": {
"type": "ai_agent_text_gen",
"access_state": "enabled",
"basic_gen": {
"is_custom_instructions_included": false,
"model": "azure__openai__gpt_4o_mini",
"num_tokens_for_completion": 8400,
"system_message": "You are a helpful professional assistant specialized in enterprise marketing and content strategy."
},
"description": "Professional assistant specialized in creating marketing copy"
}
}
The API returns a lot of information, including the AI agent ID, which will be useful in our next request:
{
"id": "1234567",
"type": "ai_agent",
"origin": "CUSTOM",
"name": "Professional assistant",
"access_state": "enabled",
"created_by": {
"type": "user",
"id": "21212121212"
},
"created_at": "2025-02-24T10:56:13Z",
"modified_by": {
"type": "user",
"id": "21212121212"
},
"modified_at": "2025-02-24T10:56:13Z",
"text_gen": {
"description": "Professional assistant specialized in creating marketing copy",
"access_state": "enabled",
"type": "ai_agent_text_gen",
"basic_gen": {
"model": "azure__openai__gpt_4o_mini",
"system_message": "You are a helpful professional assistant specialized in enterprise marketing and content strategy.",
"num_tokens_for_completion": 8400,
"embeddings": {
"model": "azure__openai__text_embedding_ada_002"
}
}
}
}To see the list of created AI agents, go to Box Admin Console and navigate to the Box AI tab. The list of AI agents displays the Professional assistant we just created using Box AI Studio API.
As a result, Box end users can change the Default Box agent to the Professional Assistant agent and interact with it, for example, in Box Notes. As specified in the agent’s system message, it will assist in generating text specialized in enterprise marketing and content strategy.
Keep in mind that agents can have more than one capability. For example you could use the Update AI agent endpoint and add additional capabilities, like extract metadata or ask questions related to content with specific instructions. Thanks to additional granular parameters, you can create tailored AI agents and fine tune them. Here you can find the full specification for every capability:
Get AI agent by agent ID
With the Get AI agent by agent ID endpoint, you can retrieve all data related to a specific AI agent. The only required parameter is the AI agent ID.
To get all details related to the agent configuration, add an additional fields query parameter as shown in this example:
https://api.box.com/2.0/ai_agents/{agent_id}?fields=ask,text_gen,extract
This results in an extended response that includes all details related to the AI agent.
You can also interact with the Box AI Studio API using our generated Box SDKs. Check out the code snippets available in multiple programming languages such as TypeScript, Python, .NET, Swift (currently in beta), and Java (currently in beta).
As always, we are excited to hear your feedback and stories on the Box Developer Community. 🦄
