box-ai-agents-toolkit
Advanced tools
A Python library for building AI agents for Box. This toolkit provides functionalities for authenticating with Box using OAuth and CCG, interacting with Box files and folders, managing document generation operations, and handling metadata templates.
To install the toolkit, run:
pip install box-ai-agents-toolkit
Create a .env file with:
BOX_CLIENT_ID = "your client id"
BOX_CLIENT_SECRET = "your client secret"
BOX_SUBJECT_TYPE = "user/enterprise"
BOX_SUBJECT_ID = "user id/enterprise id"
Then authenticate:
from box_ai_agents_toolkit import get_ccg_client
client = get_ccg_client()
Create a .env file with:
BOX_CLIENT_ID = "your client id"
BOX_CLIENT_SECRET = "your client secret"
BOX_REDIRECT_URL = "http://localhost:8000/callback"
Then authenticate:
from box_ai_agents_toolkit import get_oauth_client
client = get_oauth_client()
Get File by ID:
from box_ai_agents_toolkit import box_file_get_by_id
file = box_file_get_by_id(client, file_id="12345")
Extract Text from File:
from box_ai_agents_toolkit import box_file_text_extract
text = box_file_text_extract(client, file_id="12345")
List Folder Contents:
from box_ai_agents_toolkit import box_folder_list_content
contents = box_folder_list_content(client, folder_id="0")
print("Folder contents:", contents)
Create a Folder:
from box_ai_agents_toolkit import box_create_folder
folder = box_create_folder(client, name="New Folder", parent_id="0")
print("Created folder:", folder)
Update a Folder:
from box_ai_agents_toolkit import box_update_folder
updated_folder = box_update_folder(client, folder_id="12345", name="Updated Name", description="New description")
print("Updated folder:", updated_folder)
Delete a Folder:
from box_ai_agents_toolkit import box_delete_folder
box_delete_folder(client, folder_id="12345")
print("Folder deleted")
Upload a File:
from box_ai_agents_toolkit import box_upload_file
content = "This is a test file content."
result = box_upload_file(client, content, file_name="test_upload.txt", folder_id="0")
print("Uploaded File Info:", result)
Download a File:
from box_ai_agents_toolkit import box_file_download
path_saved, file_content, mime_type = box_file_download(client, file_id="12345", save_file=True)
print("File saved to:", path_saved)
Search for Content:
from box_ai_agents_toolkit import box_search
results = box_search(client, query="contract", limit=10, content_types=["name", "description"])
print("Search results:", results)
Locate Folder by Name:
from box_ai_agents_toolkit import box_locate_folder_by_name
folder = box_locate_folder_by_name(client, folder_name="Documents", parent_folder_id="0")
print("Found folder:", folder)
Mark a File as a DocGen Template:
from box_ai_agents_toolkit import box_docgen_template_create
template = box_docgen_template_create(client, file_id="template_file_id")
print("Created DocGen Template:", template)
List DocGen Templates:
from box_ai_agents_toolkit import box_docgen_template_list
templates = box_docgen_template_list(client, marker='x', limit=10)
print("DocGen Templates:", templates)
Delete a DocGen Template:
from box_ai_agents_toolkit import box_docgen_template_delete
box_docgen_template_delete(client, template_id="template_file_id")
print("Template deleted")
Retrieve a DocGen Template by ID:
from box_ai_agents_toolkit import box_docgen_template_get_by_id
template_details = box_docgen_template_get_by_id(client, template_id="template_file_id")
print("Template details:", template_details)
Retrieve a DocGen Template by Name:
from box_ai_agents_toolkit import box_docgen_template_get_by_name
template_details = box_docgen_template_get_by_name(client, template_name="My Template")
print("Template details:", template_details)
List Template Tags and Jobs:
from box_ai_agents_toolkit import box_docgen_template_list_tags, box_docgen_template_list_jobs
tags = box_docgen_template_list_tags(client, template_id="template_file_id", template_version_id='v1', marker='m', limit=5)
jobs = box_docgen_template_list_jobs(client, template_id="template_file_id", marker='m2', limit=3)
print("Template tags:", tags)
print("Template jobs:", jobs)
Create a Document Generation Batch:
from box_ai_agents_toolkit import box_docgen_create_batch
data_input = [
{"generated_file_name": "file1", "user_input": {"a": "b"}},
{"generated_file_name": "file2", "user_input": {"x": "y"}}
]
batch = box_docgen_create_batch(client, file_id="f1", input_source="api", destination_folder_id="dest", output_type="pdf", document_generation_data=data_input)
print("Batch job created:", batch)
Create Single Document from User Input:
from box_ai_agents_toolkit import box_docgen_create_single_file_from_user_input
result = box_docgen_create_single_file_from_user_input(
client,
file_id="template_file_id",
destination_folder_id="dest_folder_id",
user_input='{"name": "John Doe", "date": "2024-01-01"}',
generated_file_name="Generated Document",
output_type="pdf"
)
print("Single document created:", result)
Get DocGen Job by ID:
from box_ai_agents_toolkit import box_docgen_get_job_by_id
job = box_docgen_get_job_by_id(client, job_id="job123")
print("Job details:", job)
List DocGen Jobs:
from box_ai_agents_toolkit import box_docgen_list_jobs
jobs = box_docgen_list_jobs(client, marker="m", limit=10)
print("DocGen jobs:", jobs)
List Jobs by Batch:
from box_ai_agents_toolkit import box_docgen_list_jobs_by_batch
batch_jobs = box_docgen_list_jobs_by_batch(client, batch_id="batch123", marker="m", limit=5)
print("Batch jobs:", batch_jobs)
Create a Metadata Template:
from box_ai_agents_toolkit import box_metadata_template_create
template = box_metadata_template_create(
client,
scope="enterprise",
display_name="My Template",
template_key="tmpl1",
hidden=True,
fields=[{"key": "a", "type": "string"}],
copy_instance_on_item_copy=False,
)
print("Created Metadata Template:", template)
Retrieve a Metadata Template by Key:
from box_ai_agents_toolkit import box_metadata_template_get_by_key
template = box_metadata_template_get_by_key(client, scope="enterprise", template_key="tmpl1")
print("Metadata Template Details:", template)
Retrieve a Metadata Template by ID:
from box_ai_agents_toolkit import box_metadata_template_get_by_id
template = box_metadata_template_get_by_id(client, template_id="12345")
print("Metadata Template Details:", template)
Retrieve a Metadata Template by Name:
from box_ai_agents_toolkit import box_metadata_template_get_by_name
template = box_metadata_template_get_by_name(client, template_name="My Template", scope="enterprise")
print("Metadata Template Details:", template)
Set Metadata Instance on File:
from box_ai_agents_toolkit import box_metadata_set_instance_on_file
metadata = {"field1": "value1", "field2": "value2"}
result = box_metadata_set_instance_on_file(
client,
file_id="12345",
scope="enterprise",
template_key="tmpl1",
metadata=metadata
)
print("Metadata set:", result)
Get Metadata Instance on File:
from box_ai_agents_toolkit import box_metadata_get_instance_on_file
metadata = box_metadata_get_instance_on_file(
client,
file_id="12345",
scope="enterprise",
template_key="tmpl1"
)
print("File metadata:", metadata)
Update Metadata Instance on File:
from box_ai_agents_toolkit import box_metadata_update_instance_on_file
updates = [
{"op": "replace", "path": "/field1", "value": "new_value1"},
{"op": "add", "path": "/field3", "value": "value3"}
]
result = box_metadata_update_instance_on_file(
client,
file_id="12345",
scope="enterprise",
template_key="tmpl1",
request_body=updates
)
print("Metadata updated:", result)
Delete Metadata Instance on File:
from box_ai_agents_toolkit import box_metadata_delete_instance_on_file
box_metadata_delete_instance_on_file(
client,
file_id="12345",
scope="enterprise",
template_key="tmpl1"
)
print("Metadata instance deleted")
Ask AI a Question about a Single File:
from box_ai_agents_toolkit import box_ai_ask_file_single
response = box_ai_ask_file_single(client, file_id="12345", prompt="What is this file about?")
print("AI Response:", response)
Ask AI a Question about Multiple Files:
from box_ai_agents_toolkit import box_ai_ask_file_multi
file_ids = ["12345", "67890"]
response = box_ai_ask_file_multi(client, file_ids=file_ids, prompt="Compare these files")
print("AI Response:", response)
Ask AI a Question about a Box Hub:
from box_ai_agents_toolkit import box_ai_ask_hub
response = box_ai_ask_hub(client, hubs_id="12345", prompt="What is the current policy on parental leave?")
print("AI Response:", response)
Extract Information from Files using AI (Freeform):
from box_ai_agents_toolkit import box_ai_extract_freeform
response = box_ai_extract_freeform(client, file_id="12345", prompt="Extract date, name, and contract number from this file.")
print("AI Extract Response:", response)
Extract Structured Information using Fields:
from box_ai_agents_toolkit import box_ai_extract_structured_using_fields
fields = [
{"key": "contract_date", "type": "date", "description": "The contract signing date"},
{"key": "parties", "type": "array", "description": "Names of contracting parties"}
]
response = box_ai_extract_structured_using_fields(client, file_id="12345", fields=fields)
print("Structured Extract Response:", response)
Extract Enhanced Structured Information using Fields:
from box_ai_agents_toolkit import box_ai_extract_structured_enhanced_using_fields
fields = [
{"key": "contract_date", "type": "date", "description": "The contract signing date"},
{"key": "parties", "type": "array", "description": "Names of contracting parties"}
]
response = box_ai_extract_structured_enhanced_using_fields(client, file_id="12345", fields=fields)
print("Enhanced Structured Extract Response:", response)
Extract Structured Information using Template:
from box_ai_agents_toolkit import box_ai_extract_structured_using_template
response = box_ai_extract_structured_using_template(client, file_id="12345", template_key="contract_template")
print("Template-based Extract Response:", response)
Extract Enhanced Structured Information using Template:
from box_ai_agents_toolkit import box_ai_extract_structured_enhanced_using_template
response = box_ai_extract_structured_enhanced_using_template(client, file_id="12345", template_key="contract_template")
print("Enhanced Template-based Extract Response:", response)
Clone the repository:
git clone https://github.com/box-community/box-ai-agents-toolkit.git
cd box-ai-agents-toolkit
Install dependencies:
pip install -e .[dev]
To run the tests, use:
pytest
To run the linter:
ruff check
To format code:
ruff format
This project is licensed under the MIT License. See the LICENSE file for details.
Contributions are welcome! Please open an issue or submit a pull request for any enhancements or bug fixes.
For questions or issues, open an issue on the GitHub repository.
FAQs
A python library for building AI agents for Box
We found that box-ai-agents-toolkit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Four npm packages disguised as cryptographic tools steal developer credentials and send them to attacker-controlled Telegram infrastructure.
Security News
Ruby maintainers from Bundler and rbenv teams are building rv to bring Python uv's speed and unified tooling approach to Ruby development.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.