Enlaces de agentes para Python en Azure Functions

Los enlaces de agentes para aplicaciones de funciones en Python te permiten añadir comportamientos agentes a funciones existentes. Cuando se ejecuta la función, la extensión construye un Agent a partir de instrucciones de Markdown y lo inyecta en tu controlador como parámetro tipado. Tu código decide cuándo y cómo invocar el agente junto con tu lógica de aplicación determinista.

Importante

Los enlaces de agentes para aplicaciones de funciones en Python están actualmente en vista previa. Las características, nombres de los paquetes y configuraciones pueden cambiar antes de la disponibilidad general.

Para comparar las vinculaciones de agentes con otras funciones relacionadas con IA, como las habilidades alojadas en Azure Functions y las herramientas Model Context Protocol (MCP), consulta las opciones de integración de IA para Azure Functions.

Un enlace de agente es un enlace de entrada propiedad de una extensión que proporciona un objeto completamente construido Agent a una función de Python. La extensión lee instrucciones del agente como texto en bruto de un .agent.md archivo. El código de tu aplicación mantiene la configuración específica de herramientas para clientes y proveedores, mientras que el proyecto de aplicación de funciones puede descubrir habilidades de agentes basados en archivos y servidores MCP remotos.

La arquitectura de enlace de agentes soporta objetos agente de diferentes SDKs a través de paquetes de extensión específicos de cada proveedor. Microsoft Agent Framework es el único agente SDK compatible con la vista previa actual. Para usarlo, instala el azurefunctions-agents-extensions-agent-framework paquete.

Cuándo usar enlaces de agentes

Utiliza enlaces de agentes cuando una función de Azure necesita razonamiento agente como parte de un flujo de trabajo, pero tu aplicación debe mantener el control sobre su disparador, validación, ramificación, manejo de errores y respuesta. Entre los escenarios habituales se incluyen los siguientes:

• Evalúa una solicitud HTTP. Validar un pedido con código determinista, pedir a un agente que evalúe el riesgo de cumplimiento y usar el resultado para construir la respuesta HTTP.
• Enriquecer o clasificar los eventos. Recibe un mensaje de cola, un evento de Event Grid u otra carga útil del desencadenador y utiliza un agente para clasificar, resumir o enriquecer los datos antes de que la función escriba el resultado.
• Añade razonamiento a un flujo de trabajo duradero. Llama a un agente desde un orquestador de Durable Functions mediante la API context.call_agent() apta para reproducción y, después, usa el resultado en pasos posteriores de la orquestación.

Las vinculaciones de agentes encajan bien cuando el código determinista de la función debe seguir siendo el coordinador. El agente realiza una tarea de razonamiento acotado y devuelve el control al controlador o al sistema de orquestación.

¿Por qué usar enlaces de agentes?

Muchos flujos de trabajo de producción combinan pasos que deben ser deterministas con pasos que se benefician del razonamiento de modelos. Las vinculaciones de agentes ofrecen los siguientes beneficios para estos flujos de trabajo híbridos:

• Añadir comportamiento agente a funciones existentes. Utiliza el razonamiento del agente en funciones desencadenadas por HTTP, temporizador, cola, Event Grid, Service Bus y otros desencadenadores.
• Controla de forma segura la invocación del agente en el código. Decide cuándo invocar el agente, inspecciona su respuesta y determina la salida de la función. La extensión cierra los recursos propiedad de la invocación tras el éxito, fracaso o cancelación.
• Reducir el código de configuración del agente. Recibir un Agent configurado como parámetro tipado de controlador en lugar de crearlo y configurarlo en cada invocación.
• Separe las instrucciones de la configuración en tiempo de ejecución. Almacenar instrucciones en lenguaje natural en un .agent.md archivo y configurar clientes y herramientas específicas de proveedores explícitamente en Python.
• Utiliza capacidades de agentes compartidos. La extensión descubre las habilidades de agentes basados en archivos y los servidores MCP basados en HTTP desde la raíz de la aplicación y los pone a disposición de cada enlace de agentes.
• Llamar a agentes desde orquestaciones duraderas. La extensión ejecuta el trabajo de agente en una actividad oculta para que la reproducción de orquestación siga siendo determinista.
• Depura localmente con herramientas familiares. Ejecuta y depura la app localmente como cualquier otra aplicación de funciones en Python. Puedes establecer puntos de interrupción y recorrer tanto la lógica de funciones deterministas como el código que invoca el agente.

Cómo funciona una unión de agentes

AgentFunctionApp extiende azure.functions.FunctionApp, por lo que tiene las mismas capacidades que FunctionApp. El markdown_agent decorador añade una entrada de agente a una función.

Para cada enlace de agentes, la extensión realiza las siguientes operaciones:

1. Resuelve el archivo solicitado .agent.md desde la raíz de la aplicación de funciones o su agents/ directorio.
2. Carga el archivo completo como instrucciones UTF-8 en bruto.
3. Combina las instrucciones con la factoría de cliente configurada, las herramientas del proveedor configuradas explícitamente y las habilidades de agente detectadas y los servidores MCP detectados.
4. Crea un nuevo Agent y abre los recursos propios de la invocación.
5. Inyecta el Agent en el parámetro del controlador.
6. Cierra los recursos pertenecientes a la invocación al finalizar la ejecución.

La extensión puede almacenar en caché el descubrimiento de proveedores y las definiciones de enlace compiladas. No almacena en caché ni reutiliza recursos de invocación en vivo entre invocaciones de funciones.

Defina una vinculación de agente

El siguiente ejemplo utiliza el proveedor actualmente soportado de Microsoft Agent Framework para añadir an Agent a una función activada por HTTP. La función construye la tarea en código, invoca al agente y devuelve la respuesta del agente:

import azure.functions as func
from agent_framework import Agent
from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.function_name(name="ProcessOrder")
@app.route(route="orders/{orderId}", methods=["POST"])
@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    task = (
        "Validate the order and return fulfillment guidance for "
        f"{req.route_params['orderId']}."
    )
    response = await order_agent.run(task)
    return func.HttpResponse(response.text)

El arg_name valor debe coincidir con el parámetro del handler inyectado. Para inyectar varios agentes en la misma función, apile los decoradores markdown_agent y use un arg_name único y un parámetro de controlador para cada vinculación de agente. El agent_name valor identifica el archivo de instrucciones. En este ejemplo, order-fulfillment debe corresponder exactamente a una de estas ubicaciones:

<app_root>/order-fulfillment.agent.md
<app_root>/agents/order-fulfillment.agent.md

Si ambos archivos existen, la definición es ambigua y el inicio de la app falla. Los nombres de agentes no pueden contener caminos absolutos, separadores de caminos ni componentes de recorrido. No se permiten archivos que resuelvan fuera de la raíz de la aplicación.

Configurar el cliente agente y las herramientas

Configura un argumento client_factory cero cuando construyas AgentFunctionApp. La fábrica devuelve un cliente nuevo compatible con el paquete del proveedor. También puedes pasar objetos de herramienta de Microsoft Agent Framework o elementos invocables de Python mediante el parámetro tools a nivel de aplicación. Un enlace puede invalidar la fábrica de cliente a nivel de aplicación y las herramientas si requiere un comportamiento diferente.

Por ejemplo, la siguiente función activada por HTTP utiliza un enlace de agentes que pone lookup_inventory a disposición como herramienta solo para order_agent:

def lookup_inventory(product_id: str) -> str:
    """Return the available inventory for a product."""
    return f"Inventory is available for {product_id}."


@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
    tools=[lookup_inventory],
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    response = await order_agent.run(req.get_body().decode())
    return func.HttpResponse(response.text)

Ten en cuenta estas consideraciones al configurar el cliente agente y las herramientas:

• La extensión base del agente es independiente del proveedor. Un paquete proveedor integra un SDK de agente específico y define los tipos de cliente y agente soportados.
• El paquete de proveedor actualmente compatible con el Microsoft Agent Framework no selecciona ni configura un proveedor de modelos para tu aplicación. Tu factoría de cliente determina qué cliente de chat y qué modelo compatibles con Microsoft Agent Framework usa el agente.
• La extensión pasa el archivo .agent.md completo al proveedor configurado como instrucciones para el agente. No analiza la configuración del modelo, las herramientas, el bloque de metadatos YAML ni otra configuración de tiempo de ejecución del archivo.

Habilidades de agente compartido y servidores MCP

La extensión descubre automáticamente capacidades de agentes compartidos a partir de la raíz de la aplicación:

Capacidad	Ubicación	Behavior
Aptitudes del agente	skills/<skill-name>/SKILL.md o Skills/<skill-name>/SKILL.md	El paquete proveedor carga y valida la habilidad del agente basado en archivos.
Servidores MCP remotos	mcp.json	La extensión configura servidores HTTP compatibles o servidores HTTP de transmisión, y opcionalmente listas de herramientas permitidas.
Herramientas para proveedores	Aplicación o configuración de enlace	Los objetos de la herramienta Microsoft Agent Framework o los llamables en Python se proporcionan explícitamente en lugar de ser descubiertos.

Ten en cuenta estas consideraciones cuando utilices capacidades de agente compartido:

• Cada enlace de agente de la aplicación de funciones recibe todas las habilidades de agente descubiertas y todos los servidores MCP.
• Las habilidades de agente basadas en archivos son capacidades que un agente puede cargar. No son habilidades alojadas en Azure Functions, que usan un modelo de ejecución separado.
• La vista previa actual de la extensión del agente no permite seleccionar un subconjunto de capacidades para una aplicación o una asignación individual.
• Las habilidades de los agentes y las herramientas MCP pueden realizar operaciones privilegiadas. Coloca solo capacidades que todos los agentes de la app puedan usar, y usa aplicaciones de funciones separadas cuando los agentes requieran límites de capacidades diferentes.

La configuración de MCP puede referenciar variables de entorno para URLs, cabeceras, ámbitos de autenticación e IDs de cliente. Las referencias se resuelven para cada invocación, antes de que la extensión se conecte al servidor. No almacenes secretos directamente en un archivo mcp.json bajo control de versiones.

No se soportan servidores MCP de procesos locales ni de entrada/salida estándar (stdio). El soporte MCP es una dependencia opcional y las importaciones normales de paquetes siguen siendo seguras cuando no está instalado.

Utiliza enlaces de agentes con Durable Functions

Los enlaces de agentes soportan flujos de trabajo híbridos y de larga duración mediante una integración opcional de Durable Functions. Un orquestador generador síncrono llama context.call_agent() y produce la tarea resultante:

from typing import Any

from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.orchestration_trigger(context_name="context")
def order_orchestrator(context: Any):
    assessment = yield context.call_agent(
        "order-fulfillment",
        {"order": context.get_input()},
    )
    return assessment

call_agent() programa una actividad oculta que resuelve la definición del agente y realiza todas las operaciones de modelo, sistema de archivos, credenciales, herramientas y red. El orquestador solo crea una solicitud schema-v1 determinista y serializable en JSON. Como resultado, la repetición de orquestación no repite las operaciones de agentes no deterministas.

Las llamadas de agente duraderas utilizan el proveedor y las capacidades compartidas configuradas por AgentFunctionApp. Las entradas y salidas deben ser serializables en JSON.

El soporte de Durable Functions es opcional. Las aplicaciones que no lo usan no necesitan instalar ni importar Durable Functions. Para usar orchestration_trigger y context.call_agent(), instala el paquete del proveedor compatible con el extra de dependencia Durable.

Archivos de proyecto

Una aplicación habilitada por agentes es una aplicación estándar de funciones en Python v2 con dependencias de extensiones de agente y uno o más archivos de instrucciones:

Archivo o carpeta	Purpose
function_app.py	Define AgentFunctionApp, activadores de funciones estándar, enlaces de agentes, fábricas de clientes y herramientas de proveedores configuradas explícitamente.
host.json	Configura el host de Azure Functions.
requirements.txt	Incluye un paquete de proveedor de agentes soportado y cualquier paquete cliente específico de SDK. Para la vista previa actual, usa azurefunctions-agents-extensions-agent-framework. Los extras opcionales habilitan la compatibilidad con Durable Functions y MCP.
*.agent.md o agents/*.agent.md	Contiene instrucciones UTF-8 en bruto para un agente. Cada nombre referenciado debe corresponder a un único archivo.
skills/ o Skills/	(Opcional) Contiene habilidades de agente basadas en archivos compartidas por todas las vinculaciones de agentes.
mcp.json	(Opcional) Define servidores MCP remotos basados en HTTP compartidos por todas las vinculaciones de agentes.

Para la estructura estándar Python del proyecto, consulta la guía para desarrolladores de Azure Functions Python.

Validación y diagnóstico

La extensión valida las definiciones de agentes antes o durante la compilación del enlace, de modo que los problemas de configuración provoquen errores claros que permitan actuar. La validación abarca:

• Archivos faltantes o ambiguos .agent.md .
• Firmas de manejadores inválidas, incluyendo un parámetro inyectado que falta o no coincide.
• Opciones o capacidades de proveedores no soportadas.
• Directorios de habilidades inválidos y configuración MCP mal formada.
• Transportes MCP no soportados y valores de entorno ausentes.
• Cargas útiles duraderas inválidas o valores que no son serializables en JSON.

Cuando está disponible, la extensión conserva el nombre de la función de Azure, el identificador de invocación y el identificador de instancia de Durable en el límite del proveedor para facilitar la correlación y el diagnóstico.

Artículos relacionados

• Opciones de integración de IA para Azure Functions
• Usa un agente de Microsoft Agent Framework en una función de Python
• Utiliza un enlace de agentes del Microsoft Agent Framework en una orquestación Durable
• Introducción a Microsoft Agent Framework