From 8ab2b469b6316ed70b1214c6d3fe0d30de8525cb Mon Sep 17 00:00:00 2001 From: Justyna Sztyper Date: Thu, 28 Aug 2025 18:48:01 +0200 Subject: [PATCH 1/3] Add guide for Enhanced Extract Agent --- .../extract-metadata-structured.md | 61 +++++++++++++++++++ content/guides/box-ai/index.md | 15 ++++- 2 files changed, 74 insertions(+), 2 deletions(-) diff --git a/content/guides/box-ai/ai-tutorials/extract-metadata-structured.md b/content/guides/box-ai/ai-tutorials/extract-metadata-structured.md index 11a739725..bd888256f 100644 --- a/content/guides/box-ai/ai-tutorials/extract-metadata-structured.md +++ b/content/guides/box-ai/ai-tutorials/extract-metadata-structured.md @@ -175,6 +175,67 @@ The response lists the fields included in the metadata template and their values } ``` +### Enhanced Extract Agent + +To start using the agent, you need: +* A Box Platform App with enabled `Manage AI` scope. +* The app installed and enabled in your Box instance. +* A file to test with. + +Calling an Enhanced Extract Agent works like calling the AI API - set the `type` to `AI Agent ID`, then string to the Enhanced Extract AI agent. + +To extract data using the Enhanced Extract Agent you need: +* Inline field definitions created with `agentCreateAiExtractStructuredMetadataTemplate` if your fields change frequently, +* or a metadata template that contains the data about the fields you wish to extract, if your extracted fields stay the same. + +See the full sample Python script that demonstrates how to call the Enhanced Extract Agent on a file using the Box AI SDK: + +```Python +from box_sdk_gen import ( + AiAgentReference, + AiAgentReferenceTypeField, + AiItemBase, + AiItemBaseTypeField, + BoxClient, + BoxCCGAuth, + CCGConfig, + CreateAiExtractStructuredMetadataTemplate +) + +# Create your client credentials grant config from the developer console +ccg_config = CCGConfig( + client_id="my_box_client_id", # replace with your client id + client_secret="my_box_client_secret", # replace with your client secret + user_id="my_box_user_id", # replace with the box user id that has access + # to the file you are referencing +) +auth = BoxCCGAuth(config=ccg_config) +client = BoxClient(auth=auth) +# Create the agent config referencing the enhanced extract agent +enhanced_extract_agent_config = AiAgentReference( + id="enhanced_extract_agent", + type=AiAgentReferenceTypeField.AI_AGENT_ID +) +# Use the Box SDK to call the extract_structured endpoint +box_ai_response = client.ai.create_ai_extract_structured( + # Create the items array containing the file information to extract from + items=[ + AiItemBase( + id="my_box_file_id", # replace with the file id + type=AiItemBaseTypeField.FILE + ) + ], + # Reference the Box Metadata template + metadata_template=CreateAiExtractStructuredMetadataTemplate( + template_key="InvoicePO", + scope="enterprise" + ), + # Attach the agent config you created earlier + ai_agent=enhanced_extract_agent_config, +) +print(f"box_ai_response: {box_ai_response.answer}") +``` + [prereq]: g://box-ai/ai-tutorials/prerequisites [agent]: e://get_ai_agent_default [model-param]: r://ai_agent_text_gen#param_basic_gen_model diff --git a/content/guides/box-ai/index.md b/content/guides/box-ai/index.md index b771daedf..da39f7cc4 100644 --- a/content/guides/box-ai/index.md +++ b/content/guides/box-ai/index.md @@ -74,9 +74,19 @@ For details, see [Box AI for Notes][boxainotes]. The [`POST /2.0/ai/extract`][extract] and [`POST /2.0/ai/extract_structured`][extract-structured] endpoints allow you to extract data from the provided input and return them in a form of key-value pairs. -* Use the `extract_structured` endpoint to extract data according to a pre-defined structure obtained from the metadata template, or a set of fields. +* Use the `extract_structured` endpoint to extract data according to a pre-defined structure obtained from the metadata template, or a set of fields. Use it for shorter documents + * Use the Enhanced Extract Agent for long, complex documents * Use the `extract` endpoint to extract data from a file using a prompt that can include a stringified version of formats such as JSON or XML, or even plain text. +#### Enhanced Extract Agent + +The Enhanced Extract Agent is designed to extract key-value pairs from complex documents. It converts the unstructured content into metadata for easier discovery and search. + +You can [use the agent][eea-tutorial] through the Box AI API and turn unstructured data into structured output to use in production databases, third party systems, or analytics. + +The Enhanced Extract Agent uses Gemini 2.5 Pro to provide a chain-of-thought reasoning and returns both the extracted values and a reasoning behind +its answer. + ### Configuration overrides You can use the `ai_agent` parameter available in the Box AI API requests to override the default agent configuration and introduce your own custom settings. @@ -125,4 +135,5 @@ better results for this language. [uar]: https://support.box.com/hc/en-us/articles/4415012490387-User-Activity-Report [agent-default]: g://box-ai/ai-agents/get-agent-default-config [extract]: e://post_ai_extract -[extract-structured]: e://post_ai_extract_structured \ No newline at end of file +[extract-structured]: e://post_ai_extract_structured +[eea-tutorial]: g://box-ai/ai-tutorials/extract-metadata-structured# \ No newline at end of file From fb4736ce916955df5c6dc16e803ec4df0de39edd Mon Sep 17 00:00:00 2001 From: Justyna Sztyper Date: Thu, 28 Aug 2025 18:52:19 +0200 Subject: [PATCH 2/3] Correct lint issues --- .../ai-tutorials/extract-metadata-structured.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/content/guides/box-ai/ai-tutorials/extract-metadata-structured.md b/content/guides/box-ai/ai-tutorials/extract-metadata-structured.md index bd888256f..c84f6f93d 100644 --- a/content/guides/box-ai/ai-tutorials/extract-metadata-structured.md +++ b/content/guides/box-ai/ai-tutorials/extract-metadata-structured.md @@ -178,15 +178,17 @@ The response lists the fields included in the metadata template and their values ### Enhanced Extract Agent To start using the agent, you need: -* A Box Platform App with enabled `Manage AI` scope. -* The app installed and enabled in your Box instance. -* A file to test with. + +- A Box Platform App with enabled `Manage AI` scope. +- The app installed and enabled in your Box instance. +- A file to test with. Calling an Enhanced Extract Agent works like calling the AI API - set the `type` to `AI Agent ID`, then string to the Enhanced Extract AI agent. To extract data using the Enhanced Extract Agent you need: -* Inline field definitions created with `agentCreateAiExtractStructuredMetadataTemplate` if your fields change frequently, -* or a metadata template that contains the data about the fields you wish to extract, if your extracted fields stay the same. + +- Inline field definitions created with `agentCreateAiExtractStructuredMetadataTemplate` if your fields change frequently, +- or a metadata template that contains the data about the fields you wish to extract, if your extracted fields stay the same. See the full sample Python script that demonstrates how to call the Enhanced Extract Agent on a file using the Box AI SDK: From 48ae3ec9892843a907ae65d874f263a7db99d747 Mon Sep 17 00:00:00 2001 From: Justyna Sztyper Date: Thu, 28 Aug 2025 19:11:40 +0200 Subject: [PATCH 3/3] Correct formatting --- content/guides/box-ai/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/box-ai/index.md b/content/guides/box-ai/index.md index da39f7cc4..fb2f07935 100644 --- a/content/guides/box-ai/index.md +++ b/content/guides/box-ai/index.md @@ -85,7 +85,7 @@ The Enhanced Extract Agent is designed to extract key-value pairs from complex d You can [use the agent][eea-tutorial] through the Box AI API and turn unstructured data into structured output to use in production databases, third party systems, or analytics. The Enhanced Extract Agent uses Gemini 2.5 Pro to provide a chain-of-thought reasoning and returns both the extracted values and a reasoning behind -its answer. +its answer. ### Configuration overrides