Usare Informazioni sul contenuto con Microsoft Agent Framework

L'integrazione di Azure Content Understanding in Foundry Tools per Microsoft Agent Framework fornisce un provider di contesto per gli allegati di file. Il provider rileva documenti, immagini, audio e video supportati nell'input dell'agente, analizza i file e aggiunge i campi Markdown ed estratti al contesto del modello.

Prerequisiti

Perché usare questa integrazione

  • Elaborazione automatica degli allegati. Il framework chiama il provider prima della chiamata a ogni modello, quindi non chiamare direttamente l'analizzatore.
  • Input multimodale. Il provider accetta documenti, immagini, audio e video.
  • Output strutturato. Il provider può aggiungere i campi Markdown ed estratti al contesto del modello.
  • Elaborazione posticipata. Un tempo di attesa configurabile consente alle analisi a esecuzione prolungata di continuare in background. Il supporto facoltativo per la ricerca di file supporta i caricamenti di Markdown estratti in un archivio vettoriale per la generazione aumentata del recupero (RAG).

Installare il pacchetto

Installare il pacchetto di integrazione Content Understanding per Microsoft Agent Framework. L'integrazione viene fornita nel agent-framework-azure-contentunderstanding pacchetto, disponibile anche in PyPI:

pip install agent-framework-azure-contentunderstanding --pre

Annotazioni

Il --pre flag installa la build preliminare corrente del pacchetto.

Registrare Content Understanding come provider di contesto

Creare un ContentUnderstandingContextProvider, passarlo all'agente tramite il context_providers parametro ed eseguire l'agente all'interno del blocco del async with provider. L'esempio seguente risponde a una domanda su un documento allegato:

import asyncio
from agent_framework import Agent, AgentSession, Message, Content
from agent_framework.foundry import FoundryChatClient
from agent_framework.foundry import ContentUnderstandingContextProvider
from azure.identity import AzureCliCredential

credential = AzureCliCredential()

cu = ContentUnderstandingContextProvider(
    endpoint="https://my-resource.cognitiveservices.azure.com/",
    credential=credential,
    # Block until analysis completes before sending to the model.
    max_wait=None,
)

client = FoundryChatClient(
    project_endpoint="https://your-project.services.ai.azure.com",
    model="gpt-5.2",
    credential=credential,
)

async def main():
    async with cu:
        agent = Agent(
            client=client,
            name="DocumentQA",
            instructions="You are a helpful document analyst.",
            context_providers=[cu],
        )
        session = AgentSession()

        response = await agent.run(
            Message(role="user", contents=[
                Content.from_text("What's on this invoice?"),
                Content.from_uri(
                    "https://raw.githubusercontent.com/Azure-Samples/"
                    "azure-ai-content-understanding-assets/main/"
                    "document/invoice.pdf",
                    media_type="application/pdf",
                    additional_properties={"filename": "invoice.pdf"},
                ),
            ]),
            session=session,
        )
        print(response.text)

asyncio.run(main())

Prima della chiamata a ogni modello, il framework chiama il provider. Il provider rileva e analizza gli allegati supportati, quindi non si richiama direttamente l'analizzatore.

Configura il provider

Passare parametri aggiuntivi per selezionare un analizzatore e controllare la quantità di contenuto restituito dal provider:

Parametro Purpose
endpoint Endpoint della risorsa Microsoft Foundry. Se omesso, il provider lo legge dalla AZURE_CONTENTUNDERSTANDING_ENDPOINT variabile di ambiente.
credential Oggetto AzureKeyCredential per l'autenticazione della chiave API o una credenziale di identità Azure, ad esempio AzureCliCredential o DefaultAzureCredential, per l'autenticazione di Microsoft Entra ID.
analyzer_id ID analizzatore predefinito o personalizzato. Se si omette questo parametro, il provider seleziona prebuilt-documentSearch per documenti e immagini, prebuilt-audioSearch per l'audio e prebuilt-videoSearch per il video.
max_wait Numero di secondi di attesa prima di rinviare l'analisi in background. Il valore predefinito è 5 secondi. Impostarla su None per attendere il completamento dell'analisi.
output_sections Sezioni dei risultati da aggiungere al contesto del modello. Le sezioni predefinite sono Markdown e campi.
file_search Configurazione facoltativa per il caricamento di Markdown estratti in un archivio vettoriale anziché aggiungere il contenuto completo al contesto del modello.

Tip

Per l'estrazione specifica del dominio, impostare su analyzer_id un ID analizzatore predefinito o personalizzato. Il provider aggiunge quindi i campi dell'analizzatore al contesto del modello.

Tipi di file supportati

Il provider accetta documenti, immagini, audio e video. Per l'elenco completo dei formati e dei limiti di dimensioni supportati, vedere Quote e limiti del servizio Content Understanding.

Passaggi successivi

  • Ultimo aggiornamento: