Use Compreensão de Conteúdo com a Microsoft Agent Framework

A integração Azure Content Understanding in Foundry Tools para o Microsoft Agent Framework fornece um fornecedor de contexto para anexos de ficheiros. O fornecedor deteta documentos, imagens, áudio e vídeo suportados na entrada do agente, analisa os ficheiros e adiciona Markdown e campos extraídos ao contexto do modelo.

Pré-requisitos

Por que usar esta integração

  • Processamento automático de anexos. O framework chama o fornecedor antes de cada invocação do modelo, por isso não liga diretamente ao analisador.
  • Entrada multimodal. O fornecedor aceita documentos, imagens, áudio e vídeo.
  • Saída estruturada. O fornecedor pode adicionar Markdown e campos extraídos ao contexto do modelo.
  • Processamento adiado. Um tempo de espera configurável permite que análises de longa duração continuem em segundo plano. A pesquisa de ficheiros opcional suporta o carregamento do Markdown extraído para uma loja vetorial para geração aumentada por recuperação (RAG).

Instale o pacote

Instale o pacote de integração Content Understanding para o Microsoft Agent Framework. A integração vem incluída no agent-framework-azure-contentunderstanding pacote, que também está disponível no PyPI:

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

Note

A --pre flag instala a versão pré-lançamento atual do pacote.

Registar o Content Understanding como fornecedor de contexto

Crie um ContentUnderstandingContextProvider, passe ao seu agente através do context_providers parâmetro e execute o agente dentro do bloco async with do fornecedor. O exemplo seguinte responde a uma questão sobre um documento anexo:

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())

Antes de cada invocação de modelo, o framework chama o fornecedor. O fornecedor deteta e analisa anexos suportados, por isso não invoca diretamente o analisador.

Configurar o fornecedor

Passe parâmetros adicionais para selecionar um analisador e controlar quanto conteúdo o fornecedor devolve:

Parâmetro Purpose
endpoint O ponto final do seu recurso Microsoft Foundry. Se for omitido, o fornecedor lê-o a partir da AZURE_CONTENTUNDERSTANDING_ENDPOINT variável de ambiente.
credential Um AzureKeyCredential para autenticação por chave API, ou uma credencial de identidade Azure, como AzureCliCredential ou DefaultAzureCredential, para autenticação Microsoft Entra ID.
analyzer_id Um ID de analisador pré-construído ou personalizado. Se omitir este parâmetro, o fornecedor seleciona prebuilt-documentSearch para documentos e imagens, prebuilt-audioSearch para áudio e prebuilt-videoSearch para vídeo.
max_wait Quantos segundos esperar antes de adiar a análise para o segundo plano? O padrão é 5 segundos. Defina para None esperar até a análise terminar.
output_sections Que secções de resultado adicionar ao contexto do modelo. As secções padrão são Markdown e campos.
file_search Configuração opcional para carregar o Markdown extraído para uma loja vetorial em vez de adicionar o conteúdo completo ao contexto do modelo.

Sugestão

Para extração específica de domínio, defina analyzer_id um ID de analisador pré-construído ou personalizado. O fornecedor adiciona então os campos do analisador ao contexto do modelo.

Tipos de ficheiros suportados

O fornecedor aceita documentos, imagens, áudio e vídeo. Para a lista completa de formatos suportados e limites de tamanho, consulte Compreensão de Conteúdos quotas e limites de serviço.

Passos seguintes

  • Última atualização a