Skip to main content
POST
/
ai_agents
cURL
curl --request POST \
  --url https://api.box.com/2.0/ai_agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "ai_agent",
  "name": "My AI Agent",
  "access_state": "enabled",
  "icon_reference": "https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg",
  "allowed_entities": [
    {
      "id": "11446498",
      "type": "user"
    }
  ],
  "ask": {
    "type": "ai_agent_ask",
    "access_state": "enabled",
    "description": "This is ASK Agent",
    "custom_instructions": "This is a custom instruction",
    "suggested_questions": [
      "What is in this file?",
      "What are the main highlights of this document?"
    ],
    "long_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "is_custom_instructions_included": false
    },
    "basic_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false
    },
    "basic_image": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false
    },
    "spreadsheet": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      }
    },
    "long_text_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "is_custom_instructions_included": false
    },
    "basic_text_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false
    },
    "basic_image_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false
    }
  },
  "text_gen": {
    "type": "ai_agent_text_gen",
    "access_state": "enabled",
    "description": "This is ASK Agent",
    "custom_instructions": "This is a custom instruction",
    "suggested_questions": [
      "What is in this file?",
      "What are the main highlights of this document?"
    ],
    "basic_gen": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. `{user_question}`",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "content_template": "---{content}---",
      "is_custom_instructions_included": false
    }
  },
  "extract": {
    "type": "ai_agent_extract",
    "access_state": "enabled",
    "description": "This is ASK Agent",
    "custom_instructions": "This is a custom instruction",
    "long_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "is_custom_instructions_included": false
    },
    "basic_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false
    },
    "basic_image": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false
    }
  }
}
'
{
  "id": "1234567890",
  "origin": "CUSTOM",
  "name": "This is my Agent",
  "access_state": "enabled",
  "type": "ai_agent",
  "created_by": {
    "id": "11446498",
    "type": "user"
  },
  "created_at": "2022-01-01T00:00:00Z",
  "modified_by": {
    "id": "11446498",
    "type": "user"
  },
  "modified_at": "2022-01-01T00:00:00Z",
  "icon_reference": "https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg",
  "allowed_entities": [
    {
      "id": "11446498",
      "type": "user"
    }
  ],
  "ask": {
    "type": "ai_agent_ask",
    "access_state": "enabled",
    "description": "This is ASK Agent",
    "custom_instructions": "This is a custom instruction",
    "suggested_questions": [
      "What is in this file?",
      "What are the main highlights of this document?"
    ],
    "long_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "basic_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "basic_image": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "spreadsheet": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "long_text_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "basic_text_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "basic_image_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    }
  },
  "text_gen": {
    "type": "ai_agent_text_gen",
    "access_state": "enabled",
    "description": "This is ASK Agent",
    "custom_instructions": "This is a custom instruction",
    "suggested_questions": [
      "What is in this file?",
      "What are the main highlights of this document?"
    ],
    "basic_gen": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. `{user_question}`",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "content_template": "---{content}---",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    }
  },
  "extract": {
    "type": "ai_agent_extract",
    "access_state": "enabled",
    "description": "This is ASK Agent",
    "custom_instructions": "This is a custom instruction",
    "long_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "basic_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "basic_image": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    }
  }
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

The schema for AI agent create request.

​
type
enum<string>
required

The type of agent used to handle queries.

Available options:
ai_agent
Example:

"ai_agent"

​
name
string
required

The name of the AI Agent.

Example:

"My AI Agent"

​
access_state
string
required

The state of the AI Agent. Possible values are: enabled, disabled, and enabled_for_selected_users.

Example:

"enabled"

​
icon_reference
string

The icon reference of the AI Agent. It should have format of the URL https://cdn01.boxcdn.net/app-assets/aistudio/avatars/<file_name> where possible values of file_name are: logo_boxAi.png,logo_stamp.png,logo_legal.png,logo_finance.png,logo_config.png,logo_handshake.png,logo_analytics.png,logo_classification.png.

Minimum string length: 1
Example:

"https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg"

​
allowed_entities
(User (Base) · object | Group (Base) · object)[]

List of allowed users or groups.

A mini representation of a user, used when nested within another resource.

​
ask
AI agent capability ask request · object

The AI agent to be used to handle queries.

​
text_gen
AI agent capability text generation request · object

The AI agent to be used to generate text.

​
extract
AI agent capability extract request · object

The AI agent to be used for metadata extraction.

Response

Definition of created AI agent.

Full representation of an AI Agent instance.

​
id
string
required

The unique identifier of the AI Agent.

Example:

"1234567890"

​
origin
string
required

The provider of the AI Agent.

Example:

"CUSTOM"

​
name
string
required

The name of the AI Agent.

Example:

"This is my Agent"

​
access_state
string
required

The state of the AI Agent. Possible values are: enabled, disabled, and enabled_for_selected_users.

Example:

"enabled"

​
type
enum<string>

The type of agent used to handle queries.

Available options:
ai_agent
Example:

"ai_agent"

​
created_by
User (Base) · object

The user who created this agent.

​
created_at
string<date-time>

The ISO date-time formatted timestamp of when this AI agent was created.

Example:

"2022-01-01T00:00:00Z"

​
modified_by
User (Base) · object

The user who most recently modified this agent.

​
modified_at
string<date-time>

The ISO date-time formatted timestamp of when this AI agent was recently modified.

Example:

"2022-01-01T00:00:00Z"

​
icon_reference
string

The icon reference of the AI Agent.

Minimum string length: 1
Example:

"https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg"

​
allowed_entities
(User (Base) · object | Group (Base) · object)[]

List of allowed users or groups.

A mini representation of a user, used when nested within another resource.

​
ask
AI agent capability ask · object

The AI agent to be used to ask questions.

​
text_gen
AI agent capability text generation · object

The AI agent to be used to generate text.

​
extract
AI agent capability extract · object

The AI agent to be used for metadata extraction.