Uso de Content Understanding con el marco del agente de Microsoft

El Azure Content Understanding in Foundry Tools integration for the Microsoft Agent Framework proporciona un proveedor de contexto para los datos adjuntos de archivos. El proveedor detecta documentos, imágenes, audio y vídeo admitidos en la entrada del agente, analiza los archivos y agrega Markdown y los campos extraídos al contexto del modelo.

Prerrequisitos

¿Por qué usar esta integración?

  • Procesamiento automático de datos adjuntos. El marco llama al proveedor antes de cada invocación de modelo, por lo que no se llama directamente al analizador.
  • Entrada multi-modal. El proveedor acepta documentos, imágenes, audio y vídeo.
  • Salida estructurada. El proveedor puede agregar Markdown y los campos extraídos al contexto del modelo.
  • Procesamiento diferido. Un tiempo de espera configurable permite que los análisis de larga duración continúen en segundo plano. La búsqueda de archivos opcional admite cargas extraídas de Markdown en un almacén de vectores para la generación aumentada de recuperación (RAG).

Instalar el paquete

Instale el paquete de integración de Content Understanding para Microsoft Agent Framework. La integración se incluye en el agent-framework-azure-contentunderstanding paquete, que también está disponible en PyPI:

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

Note

La --pre marca instala la compilación de versión preliminar actual del paquete.

Registro de Content Understanding como proveedor de contexto

Cree un ContentUnderstandingContextProvider, páselo al agente a través del context_providers parámetro y ejecute el agente dentro del bloque del async with proveedor. En el ejemplo siguiente se responde a una pregunta sobre un documento adjunto:

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 invocación de modelo, el marco llama al proveedor. El proveedor detecta y analiza los datos adjuntos admitidos, por lo que no se invoca directamente al analizador.

Configurar el proveedor

Pase parámetros adicionales para seleccionar un analizador y controlar cuánto contenido devuelve el proveedor:

Parámetro Purpose
endpoint Punto de conexión del recurso Microsoft Foundry. Si se omite, el proveedor lo lee de la AZURE_CONTENTUNDERSTANDING_ENDPOINT variable de entorno.
credential Para AzureKeyCredential la autenticación de clave de API o una credencial de identidad de Azure, como AzureCliCredential o DefaultAzureCredential, para la autenticación de Microsoft Entra ID.
analyzer_id Identificador de analizador precompilado o personalizado. Si omite este parámetro, el proveedor selecciona prebuilt-documentSearch para documentos e imágenes, prebuilt-audioSearch para audio y prebuilt-videoSearch para vídeo.
max_wait Cuántos segundos hay que esperar antes de aplazar el análisis al fondo. El valor predeterminado es 5 segundos. Establézcalo en None para esperar hasta que finalice el análisis.
output_sections Qué secciones de resultados se van a agregar al contexto del modelo. Las secciones predeterminadas son Markdown y campos.
file_search Configuración opcional para cargar Markdown extraído en un almacén de vectores en lugar de agregar el contenido completo al contexto del modelo.

Tip

Para la extracción específica del dominio, establezca en analyzer_id un identificador de analizador precompilado o personalizado. A continuación, el proveedor agrega los campos del analizador al contexto del modelo.

Tipos de archivo compatibles

El proveedor acepta documentos, imágenes, audio y vídeo. Para obtener la lista completa de los formatos y límites de tamaño admitidos, consulte Límites y cuotas del servicio Content Understanding.

Pasos siguientes

  • Se actualizó por última vez el