Guida introduttiva: Analizzare un documento con la modalità agentic

In questa guida introduttiva si userà l'API REST Azure Content Understanding in Foundry Tools per creare un analizzatore di documenti con modalità agentic, analizzare un documento e recuperare i risultati strutturati. La modalità agentic è utile quando una risposta deve essere compilata da prove anziché estratte da un'unica posizione.

La modalità agentic consente di connettere le informazioni in un documento, eseguire calcoli, convalidare i risultati, interpretare tabelle o figure complesse e restituire campi corrispondenti allo schema.

Se non hai una sottoscrizione di Azure, crea un account gratuito.

Importante

La versione 2026-06-01-preview dell'API è disponibile in anteprima pubblica. Le anteprime vengono fornite senza un contratto di servizio e non sono consigliate per i carichi di lavoro di produzione. Per ulteriori informazioni, vedere Condizioni Supplementari per l'utilizzo delle versioni di anteprima di Microsoft Azure e l’Addendum sulla protezione dei dati di Microsoft Products and Services ("DPA").

Importante

La modalità agentic richiede la versione 2026-06-01-previewdell'API .

Prerequisiti

  • Una sottoscrizione di Azure attiva.
  • Una risorsa Microsoft Foundry in un'area supportata. Per creare la risorsa, è necessario il ruolo Collaboratore o un ruolo superiore nella sottoscrizione o nel gruppo di risorse di destinazione.
  • Distribuzione del modello di completamento della chat foundry supportata configurata come modello di completamento predefinito per la risorsa Content Understanding. Configurare almeno 400.000 token al minuto (TPM) per la distribuzione per evitare errori di limite di frequenza 429 durante un processo di analisi agente. Per istruzioni sull'installazione, vedere Connettere la risorsa Content Understanding con i modelli Foundry.
  • L'endpoint e la chiave della risorsa dal portale di Azure.
  • cURL.

Creare un analizzatore agentico

Lo schema dell'analizzatore definisce i campi strutturati restituiti dalla modalità agentic. In questo esempio viene valutata una fattura calcolando il totale della voce e confrontando il valore con il totale segnalato.

Creare un file denominato agentic-invoice.json con il contenuto seguente:

{
  "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."
      }
    }
  }
}

Il valore della "agentic" richiesta abilita la modalità agentic. Usare "default"o omettere workflowper consentire al servizio di selezionare un flusso di lavoro standard in base alla configurazione dell'analizzatore.

Sostituire {endpoint}, {key}e {analyzerId} nella richiesta seguente. Creare quindi l'analizzatore:

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

La 201 Created risposta include un'intestazione Operation-Location . Copiare l'URL e usarlo per controllare lo stato di creazione dell'analizzatore:

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

Ripetere la richiesta fino a quando la risposta non restituisce "status": "Succeeded". Attendere almeno un secondo tra le richieste.

Quando si recupera l'analizzatore creato, config.workflow è "agentic.2026-06-01-preview". Il servizio risolve il selettore della fase di creazione in questo valore della famiglia di flussi di lavoro con controllo delle versioni. La agentic famiglia usa la frequenza di contestualizzazione avanzata.

Analizzare un documento

Inviare un documento all'analizzatore. Questo esempio usa una fattura di esempio:

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"
      }
    ]
  }'

Per analizzare il proprio documento, sostituire l'URL di esempio con un URL accessibile pubblicamente. Ad esempio, usare un URL BLOB Archiviazione di Azure con una firma di accesso condiviso.

La 202 Accepted risposta include un'intestazione Operation-Location . Copiare l'URL e usarlo per recuperare il risultato dell'analisi:

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

Se l'oggetto restituito status è Running o NotStarted, ripetere la richiesta dopo uno o due secondi. Quando lo stato è Succeeded, trovare l'output a forma di schema in result.contents[].fields. Il risultato contiene il totale calcolato, il totale segnalato, il confronto e il riepilogo della convalida definiti nello schema dell'analizzatore.

Esaminare i risultati agenti prima di usarli in flussi di lavoro ad alto impatto. La modalità agentica non è una sostituzione per la revisione umana.

Limitazioni dell'anteprima

L'anteprima iniziale presenta queste limitazioni:

  • Ogni richiesta di analisi supporta un file di input.
  • La modalità agentic supporta solo analizzatori di documenti.
  • I campi che usano il extract metodo non sono supportati.
  • L'uso di esempi etichettati per migliorare l'analizzatore non è supportato.

Per altri limiti di input, vedere Quote e limiti del servizio.

Pulire le risorse

Eliminare l'analizzatore personalizzato quando non è più necessario:

curl -i -X DELETE \
  "{endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2026-06-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}"

L'eliminazione dell'analizzatore non elimina la risorsa Foundry o la distribuzione del modello connesso.

Contenuti correlati

  • Last updated on