Skip to main content

Box

Give agents read access to a Box account: browse folder trees, search content by name and type, and produce short-lived download links for individual files.

All three tool types require a Box connector — an OAuth connection to the Box account the agent should read from. The tool config points at the connector with connectorId, and Autessa refreshes the OAuth token automatically before each call; if Box invalidates the refresh token the tools ask for re-authentication. See Connectors for how to link an account. This family is read-only: agents can find and fetch files but never modify the Box account.

List Files TOOLBOX_LIST_FILES​

Lists files and folders, with folderPrefix behaving differently by mode. With recursive true, it is a slash-delimited folder path (for example Contracts/2026): the executor walks from the Box root matching folder names, then collects the entire subtree depth-first up to limit items. With recursive false, folderPrefix is treated as a search string instead, matching items anywhere in the account. The result returns an entries array of Box items — files and folders, each with its id, name, type, size, and modified_at — plus total_count. limit defaults to 100.

Example​

Tool config
{
  "toolType": "BOX_LIST_FILES",
  "connectorId": "V1StGXR8Z5",
  "folderPrefix": "Contracts/2026",
  "recursive": true,
  "limit": 100
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    folderPrefix
    Type
    string
    Description
    Required string value.
  • Name
    recursive
    Type
    boolean
    Description
    Required boolean value.
  • Name
    limit
    Type
    integer
    Description
    Required integer value.

Search Files TOOLBOX_SEARCH_FILES​

Runs a Box content search restricted to files (folders are excluded) and returns the matches as a files array with total_count. fileExtensions takes a comma-separated list like pdf,docx and is enforced strictly: it both narrows the Box query and filters the results so only file names ending in one of the extensions come back. Use the returned id values with Download File to fetch a specific match. limit defaults to 100.

Example​

Tool config
{
  "toolType": "BOX_SEARCH_FILES",
  "connectorId": "V1StGXR8Z5",
  "searchQuery": "@@{searchTerms}",
  "fileExtensions": "pdf,docx",
  "limit": 50
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    searchQuery
    Type
    string
    Description
    Required string value.
  • Name
    fileExtensions
    Type
    string
    Description
    Required string value.
  • Name
    limit
    Type
    integer
    Description
    Required integer value.

Download File TOOLBOX_DOWNLOAD_FILE​

Produces a download link for one file by its Box fileId: the executor looks up the file's metadata, obtains Box's authenticated download URL, and wraps it in a short Autessa-hosted link. The result carries file_name, file_size, the file's full file_path inside Box, and the download_url — valid for 120 seconds (expires_in_seconds: 120), so the link should be consumed immediately by the next step rather than stored. The tool returns a link, not the file's content; pair it with a content-extraction tool when the agent needs to read the file's text.

Example​

Tool config
{
  "toolType": "BOX_DOWNLOAD_FILE",
  "connectorId": "V1StGXR8Z5",
  "fileId": "@@{fileId}"
}
This tool type requires a connected external account. Pass the connector's ID as connectorId in the tool configuration.

Configuration fields

  • Name
    connectorId
    Type
    string (ID)
    Description
    Required string (ID) value. References a connector by ID.
  • Name
    fileId
    Type
    string
    Description
    Required string value.