Quickstart: Analyze a document with agentic mode

In this quickstart, you create an agentic mode document analyzer in Azure Content Understanding, analyze one document, and review structured results. Choose Content Understanding Studio for a browser-based walkthrough or the REST API for a code-based workflow.

Agentic mode connects information across a document, performs calculations, and returns fields that match your schema. Use it when an answer requires reasoning over evidence instead of extraction from a single location. Agentic mode requires API version 2026-06-01-preview. For more information, see the Agentic mode overview.

Important

API version 2026-06-01-preview is in public preview. Previews are provided without a service-level agreement and aren't recommended for production workloads. For more information, see Supplemental Terms of Use for Microsoft Azure Previews and the Microsoft Products and Services Data Protection Addendum ("DPA").

An active Azure subscription. If you don't have an Azure subscription, create a free account.
A Microsoft Foundry resource in a supported region. To create the resource, you need the Contributor role or higher on the target subscription or resource group.
A supported Foundry chat completion model deployment configured as the default completion model for your Content Understanding resource. Configure at least 400,000 tokens per minute (TPM) capacity for the deployment to help avoid 429 rate-limit errors during an agentic analysis job. For setup instructions, see Connect your Content Understanding resource with Foundry models.
A storage account and blob container for your Studio project.

Connect your Foundry resource to Content Understanding Studio before you create the project:

Go to the Content Understanding settings page.
Select the + Add resource button in the upper left.
Select the Foundry resource that you want to use and select Next > Save.

Ensure that the Enable autodeployment for required models if no defaults are available checkbox is selected. This selection allows Content Understanding Studio to deploy a standard model, a mini model, and an embeddings model for your resource. Different analyzers require different models. For the current list, see Supported generative models.

By taking these steps, you set up a connection between Content Understanding and Foundry models in your Foundry resource.

Create an agentic analyzer

Content Understanding Studio
REST API

Create an agentic project, and then define the fields you want to return. This example summarizes the parties, dates, renewal terms, and obligations in a contract.

Create a project

Open Content Understanding Studio and sign in with your Azure account.
Select Build, open Project list, and select Create.
In Create a new project, enter agentic-contracts for Project name.
For API version, select 2026-06-01 (Preview).
Under Workflow kind, select Agentic Extraction.
Select Create.

Define the contract schema

The schema describes the answers you want, including instructions for combining clauses and handling missing information. Use Generate for each field in this example. The agentic preview doesn't support Extract fields yet.

Download the sample web hosting agreement (contract.png) from GitHub, or use your own contract document.
In Studio, select Browse for files and upload the contract.
Download the contract field schema from GitHub and save it as agentic-contracts-schema.json.
On the Schema tab, select Import, choose the downloaded JSON file, and open it.

Review the imported imported Field definitions

Field name	Value type	Method	Field description
`Parties`	String	Generate	List the legal names of the contracting parties and their roles. Use only information in the contract.
`EffectiveDate`	Date	Generate	Return the date the contract takes effect. Distinguish it from signature dates. Return null if the effective date can't be determined from the contract.
`TerminationNoticeDays`	Number	Generate	Return the number of calendar days of notice required for termination without cause. Return null if the contract doesn't specify one unambiguous calendar-day notice period.
`RenewalSummary`	String	Generate	Summarize the renewal terms, including whether renewal is automatic, the renewal period, and any notice deadline. If renewal terms aren't stated, say so.
`ObligationsSummary`	String	Generate	Summarize each party's main obligations, combining relevant clauses across the contract. Include stated deadlines and conditions. Don't infer obligations that aren't stated.

Select Save to save the imported schema. You can edit the field descriptions to adapt the schema to your contract.

The analyzer schema defines the structured fields that agentic mode returns. This example evaluates an invoice by calculating its line-item total and comparing that value with the reported total.

Create a file named agentic-invoice.json with the following content:

{
  "description": "Calculate and validate totals in an invoice",
  "baseAnalyzerId": "prebuilt-document",
  "models": {
    "completion": "{your-completion-model}"
  },
  "config": {
    "workflow": "agentic"
  },
  "fieldSchema": {
    "fields": {
      "CalculatedLineItemTotal": {
        "type": "number",
        "method": "generate",
        "description": "Calculate the sum of all line-item amounts in the invoice."
      },
      "ReportedInvoiceTotal": {
        "type": "number",
        "method": "generate",
        "description": "Return the final total reported by the invoice."
      },
      "TotalsMatch": {
        "type": "boolean",
        "method": "generate",
        "description": "Return true when the calculated line-item total equals the reported invoice total. Otherwise, return false."
      },
      "ValidationSummary": {
        "type": "string",
        "method": "generate",
        "description": "Briefly explain whether the totals match and identify any discrepancy."
      }
    }
  }
}

The "agentic" request value enables agentic mode. Use "default", or omit workflow, to let the service select a standard workflow based on the analyzer configuration.

Replace {your-completion-model} with the catalog name of your supported completion model, not its deployment name.

Replace {endpoint}, {key}, and {analyzerId} in the following request. Then create the analyzer:

curl -i -X PUT \
  "{endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2026-06-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d @agentic-invoice.json

The 201 Created response includes an Operation-Location header. Copy its URL, and use it to check the analyzer creation status:

curl -i -X GET "{operation-location}" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Repeat the request until the response returns "status": "Succeeded". Wait at least one second between requests.

When you retrieve the created analyzer, config.workflow is "agentic.2026-06-01-preview". The service resolves the creation-time selector to this versioned workflow family value. The agentic family uses the advanced contextualization rate.

Analyze a document

Content Understanding Studio
REST API

Run the schema against your contract and check the generated answers against the document.

Select the uploaded contract, select the Test tab, and then select Run analysis. Agentic analysis can take a few minutes.
When analysis finishes, open Test > Fields. Check the parties and effective date against the contract. Compare the renewal and obligation summaries with the relevant clauses.
Select Result to inspect the JSON response and token usage.
If a field is incorrect or incomplete, refine its description on the Schema tab, select Save, and run analysis again.

Each analysis run incurs Content Understanding and model usage charges. For details, see Content Understanding pricing.

To use the analyzer in an application, select Build analyzer after reviewing the results. For the remaining build and integration steps, see Create and improve your custom analyzer in Content Understanding Studio.

Submit one document to the analyzer. This example uses a sample invoice:

curl -i -X POST \
  "{endpoint}/contentunderstanding/analyzers/{analyzerId}:analyze?api-version=2026-06-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": [
      {
        "url": "https://github.com/Azure-Samples/azure-ai-content-understanding-python/raw/refs/heads/main/data/invoice.pdf"
      }
    ]
  }'

To analyze your own document, replace the sample URL with a publicly accessible URL. For example, use an Azure Storage blob URL with a shared access signature.

The 202 Accepted response includes an Operation-Location header. Copy its URL, and use it to retrieve the analysis result:

curl -i -X GET "{operation-location}" \
  -H "Ocp-Apim-Subscription-Key: {key}"

If the returned status is Running or NotStarted, repeat the request after one or two seconds. When the status is Succeeded, find the schema-shaped output under result.contents[].fields. The result contains the calculated total, reported total, comparison, and validation summary defined in the analyzer schema.

Review agentic results before you use them in high-impact workflows. Agentic mode isn't a replacement for human review.

Preview limitations

The initial preview has these limitations:

Each analysis request supports one input file.
Agentic mode supports document analyzers only.
Fields that use the extract method aren't supported.
Using labeled samples to improve the analyzer isn't supported.

For other input limits, see Service quotas and limits.

Feedback

Was this page helpful?

Last updated on 2026-09-18