Usar o Content Understanding com o Microsoft Agent Framework

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

Pré-requisitos

Por que usar essa integração

  • Processamento automático de anexos. A estrutura chama o provedor antes de cada invocação de modelo, para que você não chame o analisador diretamente.
  • Entrada multimodal. O provedor aceita documentos, imagens, áudio e vídeo.
  • Saída estruturada. O provedor pode adicionar o Markdown e os campos extraídos ao contexto do modelo.
  • Processamento adiado. Um tempo de espera configurável permite que análises de longa execução continuem em segundo plano. O suporte à pesquisa de arquivos opcional carrega o Markdown extraído em um repositório de vetores para RAG (geração aumentada de recuperação).

Instalar o pacote

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

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

Note

O --pre sinalizador instala o build de pré-lançamento atual do pacote.

Registrar o Reconhecimento de Conteúdo como um provedor de contexto

Crie um ContentUnderstandingContextProvider, passe-o para o agente por meio do context_providers parâmetro e execute o agente dentro do bloco do async with provedor. O exemplo a seguir responde a uma pergunta sobre um documento anexado:

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, a estrutura chama o provedor. O provedor detecta e analisa anexos com suporte, para que você não invoque o analisador diretamente.

Configure o provedor

Passe parâmetros adicionais para selecionar um analisador e controlar a quantidade de conteúdo retornada pelo provedor:

Parâmetro Purpose
endpoint O ponto de extremidade do recurso Microsoft Foundry. Se omitido, o provedor o lerá da AZURE_CONTENTUNDERSTANDING_ENDPOINT variável de ambiente.
credential Uma AzureKeyCredential autenticação de chave de API ou uma credencial de identidade Azure, como AzureCliCredential ouDefaultAzureCredential, para autenticação Microsoft Entra ID.
analyzer_id Uma ID de analisador predefinida ou personalizada. Se você omitir esse parâmetro, o provedor selecionará prebuilt-documentSearch documentos e imagens, prebuilt-audioSearch para áudio e prebuilt-videoSearch vídeo.
max_wait Quantos segundos aguardar antes de adiar a análise para o segundo plano. O padrão é 5 segundos. Defina-o para None aguardar até que a análise seja concluída.
output_sections Quais seções de resultado adicionar ao contexto do modelo. As seções padrão são Markdown e campos.
file_search Configuração opcional para carregar Markdown extraído em um repositório de vetores em vez de adicionar o conteúdo completo ao contexto do modelo.

Tip

Para extração específica do domínio, defina analyzer_id como uma ID de analisador predefinida ou personalizada. Em seguida, o provedor adiciona os campos do analisador ao contexto do modelo.

Tipos de arquivo com suporte

O provedor aceita documentos, imagens, áudio e vídeo. Para obter a lista completa de formatos com suporte e limites de tamanho, consulte cotas e limites de serviço de Compreensão de Conteúdo.

Próximas Etapas 

  • Última atualização em