Referencia en tiempo de ejecución de agentes serverless

Este artículo proporciona la referencia de configuración para el entorno de ejecución de los agentes serverless de Azure Functions. Para una visión general del tiempo de ejecución y orientación sobre cuándo utilizarlo, véase Tiempo de ejecución de agentes sin servidor en Azure Functions.

Importante

El tiempo de ejecución del agente serverless está actualmente en vista previa. Las características, los nombres de configuración y los conectores admitidos pueden cambiar antes de la disponibilidad general.

Referencia de archivo de agente

Un archivo agente (.agent.md) utiliza materia frontal YAML para configurar el agente, seguido de instrucciones de markdown.

Campos de materia frontal

Use estos campos de primera cuestión para configurar un agente:

Campo	Obligatorio	Description
name	Sí	Muestra el nombre del agente.
description	Sí	Descripción breve de lo que hace el agente y cuándo se debe usar.
trigger	Sí (a menos que builtin_endpoints esté activado)	Define cómo se invoca al agente. Solo se permite un desencadenador por archivo de agente.
builtin_endpoints	No	Habilita los extremos integrados de depuración y composición. Use true para habilitar todos los puntos de conexión integrados, o configurar debug_chat_ui, chat_apiy mcp individualmente. debug_chat_ui: true también habilita las rutas de backing chat y chatstreamendpoint porque la interfaz integrada llama a esas APIs.
input_schema	No	Esquema JSON usado para validar cuerpos de solicitud HTTP para agentes desencadenados por HTTP.
logger	No	Controla si el registro en tiempo de ejecución está habilitado para el agente. Tiene como valor predeterminado true.
mcp	No	Controla el acceso a los servidores MCP detectados desde mcp.json. Use false para deshabilitar los servidores MCP para este agente o para exclude quitar servidores específicos.
metadata	No	Metadatos personalizados para su propia organización o herramientas.
model	No	Anula el modelo predeterminado configurado en agents.config.yaml o en la configuración de la aplicación.
response_example	No	Estructura de respuesta de ejemplo utilizada para guiar las respuestas estructuradas de agentes activados por HTTP.
response_schema	No	Esquema JSON usado para validar las respuestas estructuradas devueltas por agentes desencadenados por HTTP.
skills	No	Controla el acceso a habilidades descubiertas. Use false para deshabilitar las aptitudes de este agente o para exclude quitar aptitudes específicas.
substitute_variables	No	Controla si se aplica sustitución de variables ambientales a la materia frontal y a las instrucciones. Tiene como valor predeterminado true.
system_tools	No	Permite a un agente optar por no usar herramientas de sistema configuradas, como la ejecución en formato sandbox.
timeout	No	Invalida el tiempo de espera de ejecución predeterminado, en segundos.
tools	No	Controla el acceso a herramientas personalizadas de Python descubiertas. Use false para deshabilitar herramientas personalizadas para este agente o para exclude quitar herramientas específicas.

Configuración del desencadenador

Cada archivo agente soporta un disparador, definido en el trigger objeto de la materia frontal.

Campo	Obligatorio	Description
type	Sí	El tipo de bloqueo de gatillo. Consulta la tabla de tipos soportados para los valores permitidos.
args	Depende del tipo	Ajustes específicos de trigger que configuran qué evento inicia el agente.

Tipos de desencadenadores admitidos

La siguiente tabla enumera los valores soportados trigger.type , sus requisitos argsy enlaces a la referencia completa por tipo:

trigger.type	Obligatorio args	Referencia
http_trigger	route	Desencadenador HTTP
timer_trigger	schedule	Desencadenador de temporizador
queue_trigger	queue_name, connection	Desencadenador de cola
blob_trigger	path, connection	Desencadenador de blobs
event_grid_trigger	(ninguno)	Desencadenador de Event Grid
event_hub_message_trigger	event_hub_name, connection	Disparador del Event Hub
service_bus_queue_trigger	queue_name, connection	Disparador de cola del Service Bus
service_bus_topic_trigger	topic_name, subscription_name, connection	Desencadenante de temas de Service Bus
cosmos_db_trigger	connection, database_name, container_name	Desencadenador de Cosmos DB
cosmos_db_trigger_v3	database_name, collection_name, connection_string_setting	Disparador de base de datos Cosmos v3
sql_trigger	table_name, connection_string_setting	Desencadenador de SQL
mysql_trigger	table_name, connection_string_setting	Disparador MySQL
kafka_trigger	topic, broker_list	Disparador de Kafka
dapr_binding_trigger	binding_name	Gatillo de unión Dapr
dapr_service_invocation_trigger	method_name	Disparador de invocación de servicio Dapr
dapr_topic_trigger	pub_sub_name, topic	Desencadenante temático Dapr
generic_trigger	type (nombre del tipo de encuadernación)	Disparador genérico
connector_trigger	Configurado en el espacio de nombres del Conector.	Disparador conector

Ejemplos de desencadenante

Los siguientes ejemplos muestran configuraciones comunes de disparadores:

Disparador temporizador (se ejecuta diariamente a las 15:00 UTC):

trigger:
  type: timer_trigger
  args:
    schedule: "0 0 15 * * *"

Disparador HTTP:

trigger:
  type: http_trigger
  args:
    route: summarize
    auth_level: FUNCTION

Disparador de cola:

trigger:
  type: queue_trigger
  args:
    queue_name: work-items
    connection: AzureWebJobsStorage

Disparador de masas:

trigger:
  type: blob_trigger
  args:
    path: uploads/{name}
    connection: AzureWebJobsStorage

Configuración a nivel de aplicación (agents.config.yaml)

Se usa agents.config.yaml para los valores predeterminados del entorno de ejecución de toda la aplicación que todos los agentes pueden heredar. El tiempo de ejecución puede cargar una aplicación sin este archivo. Añádalo cuando necesite configuraciones compartidas, como la implementación de un modelo, un tiempo de espera o un punto de conexión para la ejecución en entorno aislado.

Este archivo es una entrada de nivel de aplicación. El entorno de ejecución también detecta servidores MCP de mcp.json, aptitudes de skills/ y herramientas de Python personalizadas de tools/. Esas funcionalidades están habilitadas en agentes de forma predeterminada. Los metadatos iniciales del agente pueden anular los valores predeterminados del entorno de ejecución o filtrar los servidores MCP heredados, las habilidades y las herramientas.

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

model: $FOUNDRY_MODEL
timeout: 900

Los agentes individuales pueden anular los ajustes de ejecución compatibles en su propio encabezado.

Campos de configuración

Use estos campos de nivel superior en agents.config.yaml:

Campo	Obligatorio	Description
model	No	Modelo predeterminado o implementación del modelo que utilizan los agentes que no establecen model en su propio encabezado.
timeout	No	Tiempo de espera de ejecución predeterminado, en segundos. El valor predeterminado del tiempo de ejecución es de 900 segundos.
system_tools.dynamic_sessions_code_interpreter.endpoint	Al usar la ejecución en entorno aislado	Punto de conexión de administración del grupo de sesiones dinámico de Azure Container Apps usado por las herramientas de espacio aislado.
system_tools.dynamic_sessions_code_interpreter.client_id	No	Id. de cliente de la identidad administrada utilizada para llamar al grupo de sesiones.
tools.exclude	No	Lista de exclusión global para herramientas de Python personalizadas detectadas desde la carpeta tools/.

Orden de resolución

El tiempo de ejecución resuelve primero los valores de los metadatos iniciales del agente, luego agents.config.yaml y, después, la configuración de la aplicación y los valores predeterminados del tiempo de ejecución. Los valores de cadena de agents.config.yaml pueden hacer referencia a la configuración de la aplicación, como $AZURE_OPENAI_DEPLOYMENT o $ACA_SESSION_POOL_ENDPOINT.

Mantenga los valores predeterminados de modelo, tiempo de espera y herramienta del sistema en agents.config.yaml. Mantenga las definiciones remotas del servidor MCP, incluidos los puntos de conexión de servidor MCP desde espacios de nombres del conector, en mcp.json.

Sustitución de variables

El entorno de ejecución puede sustituir la configuración de la aplicación y las variables de entorno en los valores de cadena de los metadatos iniciales del agente, los cuerpos de las instrucciones del agente, agents.config.yaml y mcp.json.

Para sustituciones, puedes usar o $SETTING_NAME%SETTING_NAME%, que se gestionan igual por el tiempo de ejecución. Los nombres de variable deben comenzar con una letra o un carácter de subrayado y pueden contener letras, números y caracteres de subrayado.

model: $FOUNDRY_MODEL
system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: %ACA_SESSION_POOL_ENDPOINT%

Email the summary to $TO_EMAIL.

{
  "servers": {
    "office365": {
      "type": "http",
      "url": "$O365_MCP_SERVER_URL"
    }
  }
}

Reglas de sustitución:

• Se aplica a valores de cadena, incluyendo cadenas anidadas en objetos o listas. No se aplica a las teclas objeto.
• Los bloques de código delimitados en los cuerpos de las instrucciones del agente no se sustituyen, por lo que los ejemplos pueden incluir el texto literal $VALUE o %VALUE%.
• Uso $$SETTING_NAME o %%SETTING_NAME%% para marcadores de posición literales en contenido sustituido.
• Las variables que faltan permanecen sin cambios. Los valores vacíos se resuelven en cadenas vacías.
• La sustitución es una sola pasada. No se admite la ${SETTING_NAME} sintaxis.
• Para desactivar la sustitución por un agente, se configura substitute_variables: false en el archivo agente. Esto no desactiva la sustitución en agents.config.yaml ni mcp.json.

Configuración del servidor MCP (mcp.json)

Cuando una aplicación usa servidores MCP remotos, agregue mcp.json a la raíz del proyecto de aplicación de funciones. El entorno de ejecución detecta en este archivo servidores MCP HTTP remotos o HTTP transmisibles y pone sus herramientas a disposición de los agentes, con sujeción a los filtros definidos para cada agente.

Campos de entrada del servidor

Use estos campos en cada servers entrada:

Campo	Obligatorio	Description
type	Sí	Utilice http o streamable-http. El entorno de ejecución no admite servidores MCP locales stdio .
url	Sí	Punto de conexión remoto del servidor MCP. Se admite la sustitución de variables de entorno.
headers	No	Encabezados estáticos para un servidor MCP remoto genérico. No almacene secretos estáticos en mcp.json.
auth.scope	Al usar la autenticación de Microsoft Entra	Ámbito del token de Microsoft Entra usado para autenticar las llamadas al servidor MCP.
auth.client_id	No	Identificador de cliente de la identidad administrada que se va a usar al autenticarse con este servidor MCP. Omita este campo para usar la identidad administrada asignada por el sistema de la aplicación de funciones en Azure.

Autenticación

Use el ámbito de Azure API Hub cuando el agente usa un servidor MCP administrado desde un espacio de nombres de un conector. No almacene secretos de usuario en mcp.json.

{
  "servers": {
    "office365-outlook": {
      "type": "http",
      "url": "$O365_MCP_SERVER_URL",
      "auth": {
        "scope": "https://apihub.azure.com/.default",
        "client_id": "$O365_MCP_CLIENT_ID"
      }
    }
  }
}

La auth.client_id configuración selecciona qué identidad administrada se autentica con el servidor MCP. Establézcalo en el identificador de cliente de una identidad administrada asignada por el usuario. Omítalo para utilizar la identidad administrada asignada por el sistema de la aplicación de funciones en Azure. La identidad seleccionada o la identidad del desarrollador local cuando se ejecuta localmente debe tener permiso para llamar al servidor MCP.

Conectores de Azure

Los conectores permiten a los agentes trabajar con servicios externos sin código de cliente de API personalizado. Por ejemplo, un conector de Microsoft 365 Outlook puede enviar correo electrónico, un conector de Teams puede trabajar con mensajes y otros conectores pueden llamar a acciones en sistemas como Salesforce, SAP o SQL. Un espacio de nombres del conector hospeda las conexiones, desencadenadores y servidores MCP que hacen que esas integraciones estén disponibles para la aplicación.

Para usar las funcionalidades de los conectores en una aplicación de agentes sin servidor, primero cree un recurso de espacio de nombres de conectores, cree una conexión con el servicio y autorice esa conexión. A continuación, elija cómo usa el agente la conexión:

• Los desencadenadores del conector inician agentes cuando sucede algo en un servicio conectado, como un nuevo correo electrónico, un mensaje de Teams o un evento de calendario. Para usar uno, cree un desencadenador en el espacio de nombres del conector que use la conexión autorizada y, a continuación, configure el agente con el nombre del desencadenador y los argumentos de esa definición del desencadenador del conector.
• Las herramientas de MCP del conector permiten a los agentes llamar a acciones de servicio, como enviar correo electrónico o actualizar un registro. Para usarlos, cree un servidor MCP en el espacio de nombres del conector que use la conexión autorizada y agregue el punto de conexión del servidor MCP a mcp.json.

Para más información, véase Usar conectores en Azure Functions.

Habilidades

Guarda los recursos de prompt reutilizables bajo skills/. Ayudan a mantener pequeñas instrucciones del agente base al hacer que las instrucciones específicas del dominio estén disponibles cuando sea necesario. El entorno de ejecución usa el formato Agent Skills.

Formato de habilidad

El runtime escanea skills/ en la raíz del proyecto de la aplicación de funciones y descubre recursivamente carpetas que contienen SKILL.md.

skills/
  incident-response/
    SKILL.md
    triage-checklist.md
    escalation-policy.md

El SKILL.md archivo contiene material inicial YAML seguido de instrucciones de marcado.

---
name: incident-response
description: Triage production incidents, summarize impact, and recommend next steps. Use when the task mentions incidents, outages, alerts, or severity levels.
---

Follow the incident response checklist in [triage-checklist.md](triage-checklist.md).

Reglas de autoría

Sigue estas pautas al crear tus archivos de agente y otros recursos del proyecto:

• Cada carpeta de aptitudes debe contener un SKILL.md archivo.
• Los name campos y description son obligatorios.
• Usa letras minúsculas, números y guiones simples para los nombres de las habilidades. No use espacios, caracteres de subrayado, letras mayúsculas, guiones iniciales, guiones finales ni guiones repetidos.
• Los nombres de las habilidades deben ser únicos en toda la aplicación.
• La descripción debe explicar lo que hace la aptitud y cuándo debe usarlo el agente. El tiempo de ejecución carga primero los nombres y descripciones de las aptitudes para que el agente pueda decidir cuándo cargar la aptitud completa.
• Las habilidades pueden incluir varios archivos de Markdown en la misma carpeta de habilidades. Haga referencia a los archivos Markdown auxiliares desde SKILL.md usando enlaces relativos.
• El entorno de ejecución de los agentes sin servidor solo admite archivos Markdown como contenido de habilidades. Si una habilidad necesita comportamiento ejecutable, empaqueta ese código como una herramienta Python personalizada y refírete a la herramienta por su nombre a partir de las instrucciones de habilidad.

Habilidades de filtrado por agente

Los agentes heredan todas las aptitudes detectadas de forma predeterminada. Deshabilite o excluya aptitudes en un archivo de agente cuando un agente específico no debe usarlos:

skills: false

skills:
  exclude:
    - incident-response

Ejecución en espacio aislado

Para la ejecución de código o la automatización del explorador, el entorno de ejecución puede usar Azure Container Apps sesiones dinámicas. Las sesiones dinámicas proporcionan entornos aislados de grupos de sesiones. El entorno de ejecución usa sesiones de intérprete de código para poner la herramienta execute_python a disposición de los agentes.

Configuración

Configure la ejecución aislada en agents.config.yaml:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Requirements

• El grupo de sesiones debe ser un grupo de sesiones de intérprete de código Python, como un grupo creado con --container-type PythonLTS.
• El valor endpoint es el punto de conexión de administración del grupo de sesiones.
• En Azure, la identidad gestionada utilizada por la aplicación de funciones debe tener las asignaciones de roles necesarias para ejecutar código en el pool de sesiones. Las sesiones de intérprete de código de Azure Container Apps requieren tener los roles de Azure ContainerApps Session Executor y Contributor en el grupo de sesiones.
• Cuando se ejecuta localmente, la identidad del desarrollador debe tener el mismo acceso necesario al grupo de sesiones.
• Para usar una identidad administrada asignada por el usuario para la ejecución en espacio aislado, establezca system_tools.dynamic_sessions_code_interpreter.client_id en el identificador de cliente de la identidad que tiene las asignaciones de rol necesarias. Si no se establece esta configuración, el entorno de ejecución usa AZURE_CLIENT_ID, la cadena de credenciales predeterminada.

La herramienta de entorno aislado ejecuta Python en una sesión aislada. Las variables, las importaciones y los archivos pueden persistir en las llamadas a herramientas en la misma sesión del agente. Cuando no hay ningún ID de sesión del agente disponible, el entorno de ejecución usa una nueva sesión aislada para que las ejecuciones no relacionadas no compartan estado.

Desactivación por agente

Los agentes heredan la ejecución en entorno aislado cuando está configurada globalmente. Puedes desactivar la ejecución para un agente específico configurando dynamic_sessions_code_interpreter como false en el archivo del agente.

system_tools:
  dynamic_sessions_code_interpreter: false

Herramientas de Python personalizadas

Usa herramientas Python personalizadas cuando necesites lógica específica de una app que las capacidades integradas del runtime no cubren. Las herramientas personalizadas se ejecutan en el proceso de la app de funciones, no en una sesión sandbox.

Descubrimiento de herramientas

Agregue archivos de herramientas a la tools/ carpeta en la raíz del proyecto de aplicación de funciones:

tools/
  submit_ticket.py
  lookup_customer.py

El tiempo de ejecución detecta .py archivos en tools/ cuyos nombres de archivo no empiezan por _. En la versión preliminar actual, el runtime registra la primera herramienta admitida de cada archivo. Use una herramienta por archivo para mantener la detección predecible.

Definición de herramientas

Defina una herramienta decorando una función con @tool del paquete de tiempo de ejecución:

from azure_functions_agents import tool


@tool(name="submit_ticket", description="Create a support ticket with a title and summary.")
async def submit_ticket(title: str, summary: str) -> str:
    return f"Created ticket for {title}: {summary}"

Para obtener descripciones y validación de parámetros más enriquecidas, use un modelo pydantic como esquema de herramientas:

from pydantic import BaseModel, Field
from azure_functions_agents import tool


class LookupCustomerParams(BaseModel):
    customer_id: str = Field(description="Customer identifier from the CRM system.")


@tool(schema=LookupCustomerParams, description="Look up customer details by customer ID.")
async def lookup_customer(params: LookupCustomerParams) -> str:
    return f"Customer details for {params.customer_id}"

También puede definir una función Python sin el decorador. El entorno de ejecución encapsula la primera función simple que encuentra en el archivo, usa el nombre de la función como nombre de la herramienta y la cadena de documentación como descripción de la herramienta.

def summarize_order(order_id: str) -> str:
    """Summarize an order by order ID."""
    return f"Summary for order {order_id}"

Los nombres de las herramientas, las descripciones, las anotaciones de tipo y las descripciones de los campos de Pydantic ayudan al modelo a decidir cuándo y cómo llamar a la herramienta. Agregue las dependencias de paquete que usan las herramientas personalizadas para requirements.txt, igual que lo haría con otro código de Python en una aplicación de Azure Functions.

Herramientas de filtrado por agente

Los agentes heredan las herramientas personalizadas detectadas de forma predeterminada. Deshabilite o excluya herramientas personalizadas en un archivo de agente cuando un agente específico no debe usarlos:

tools: false

tools:
  exclude:
    - submit_ticket

Configuración del proveedor de modelos

El entorno de ejecución usa Microsoft Agent Framework para invocar proveedores de modelos. La compatibilidad con la versión preliminar incluye Azure OpenAI, Fundición de IA de Azure y OpenAI.

Selección del proveedor

Debes configurar al menos una señal de proveedor para el tiempo de ejecución y así crear un cliente de chat. Puedes configurar explícitamente el proveedor usando la AZURE_FUNCTIONS_AGENTS_PROVIDER configuración o dejar que el tiempo de ejecución infiera el proveedor desde la otra configuración de la app.

Utiliza estos ajustes de proveedor:

Provider	AZURE_FUNCTIONS_AGENTS_PROVIDER valor	Configuración requerida	Configuración opcional	Comportamiento de configuración de modelos
Azure AI Foundry	foundry	FOUNDRY_PROJECT_ENDPOINT	AZURE_CLIENT_ID Cuando quieres una identidad gestionada asignada por el usuario	Establece FOUNDRY_MODEL el nombre de despliegue del modelo que debe usar el proyecto Foundry.
Azure OpenAI	azure_openai	AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT	AZURE_OPENAI_API_KEY, AZURE_OPENAI_API_VERSION, AZURE_CLIENT_ID cuando quieres una identidad gestionada asignada por el usuario	Configura AZURE_OPENAI_DEPLOYMENT el nombre de despliegue de Azure OpenAI.
OpenAI	openai	OPENAI_API_KEY	None	Configura AZURE_FUNCTIONS_AGENTS_MODEL el nombre del modelo OpenAI cuando no pases un modelo en configuración de agente o runtime.

Cuando no configuras AZURE_FUNCTIONS_AGENTS_PROVIDER, el tiempo de ejecución detecta automáticamente al proveedor en este orden:

1. AZURE_OPENAI_ENDPOINTselecciona Azure OpenAI.
2. FOUNDRY_PROJECT_ENDPOINTselecciona Fundición de IA de Azure.
3. OPENAI_API_KEY selecciona OpenAI.

Cuando se utiliza la detección automática, la configuración específica del proveedor que identificó al proveedor debe ir acompañada de la configuración del modelo requerida por el proveedor. Por ejemplo, todavía necesita FOUNDRY_MODEL, y AZURE_OPENAI_ENDPOINT sigue necesitando AZURE_OPENAI_DEPLOYMENT. FOUNDRY_PROJECT_ENDPOINT

AZURE_FUNCTIONS_AGENTS_MODEL es un ajuste de modelo de respaldo a nivel de ejecución. Sus valores válidos dependen del proveedor activo:

• Para Fundición de IA de Azure, utiliza un nombre de despliegue de modelo que exista en el proyecto Foundry, como gpt-5.4.
• Para Azure OpenAI, usa el nombre del despliegue solo si quieres intencionadamente el respaldo a nivel de ejecución. En la mayoría de las apps, pon en su lugar AZURE_OPENAI_DEPLOYMENT .
• Para OpenAI, utiliza el nombre de modelo aceptado por la API de OpenAI, como gpt-4o-mini.

Prioridad del modelo

La selección de modelos usa esta precedencia general:

1. Modelo solicitado por el agente o la llamada en tiempo de ejecución.
2. Configuración específica del proveedor, como AZURE_OPENAI_DEPLOYMENT o FOUNDRY_MODEL.
3. El modelo estableció en AZURE_FUNCTIONS_AGENTS_MODEL.
4. El modelo predeterminado integrado del proveedor activo.

Configuración de identidad administrada

El runtime utiliza identidades gestionadas al conectarse a recursos de Azure que soportan autenticación Microsoft Entra. Úsalo AZURE_CLIENT_ID como selector de identidad predeterminado de la app, o utiliza ajustes específicos de función para un control más preciso:

Función en tiempo de ejecución	Configuración de identidad	Reserva1
Azure OpenAI modelprovider 2	AZURE_CLIENT_ID	DefaultAzureCredential
proveedor de modelos de Fundición de IA de Azure	AZURE_CLIENT_ID	DefaultAzureCredential
Azure Container Apps: entorno aislado para sesiones dinámicas	system_tools.dynamic_sessions_code_interpreter.client_id	AZURE_CLIENT_ID, entonces DefaultAzureCredential
Servidores MCP alojados en espacios de nombres de conectores	El valor auth.client_id de la entrada del servidor en mcp.json	AZURE_CLIENT_ID, entonces DefaultAzureCredential
Historial de sesiones respaldadopor blobs 3	AzureWebJobsStorage__clientId	AZURE_CLIENT_ID, entonces DefaultAzureCredential

1. Cuando no se configura ninguna configuración de identidad, el entorno de ejecución utiliza DefaultAzureCredential, que se resuelve a la identidad gestionada asignada por el sistema en Azure y a tu identidad de desarrollador (CLI de Azure o Visual Studio) localmente.
2. Cuando una clave API está configurada en Azure OpenAI (usando AZURE_OPENAI_API_KEY), el proveedor del modelo utiliza la clave en lugar de una identidad gestionada. Para más información, consulta la extensión Azure OpenAI para Azure Functions.
3. El historial de sesiones utiliza la misma configuración predeterminada de identidad de almacenamiento del host que el host de Azure Functions. Use AzureWebJobsStorage, AzureWebJobsStorage__blobServiceUri y AzureWebJobsStorage__clientId para configurar el almacenamiento basado en identidades para el historial respaldado por blobs. El entorno de ejecución no usa una configuración de identidad independiente y específica del agente para el historial de la sesión. Para más información, consulte Definir conexiones en la guía para desarrolladores de Funciones.

Puntos de conexión integrados

El tiempo de ejecución expone los endpoints incorporados opcionales cuando un agente se activa a través de los builtin_endpoints ajustes en su materia inicial. Estos endpoints son útiles para el desarrollo, las pruebas y el diagnóstico. No están diseñados como la interfaz principal de la aplicación de producción.

Habilitar endpoints integrados en la materia frontal del agente:

builtin_endpoints:
  debug_chat_ui: true
  chat_api: true
  mcp: true

La configuración debug_chat_ui: true también activa las chat APIs de y chatstream porque la interfaz depende de ellas. Se configura chat_api: true solo cuando quieres acceso al chat programático sin la interfaz de depuración.

Rutas de punto de conexión

El <AGENT_NAME> segmento de ruta proviene del nombre del .agent.md archivo, no del campo de visualización name . Por ejemplo, main.agent.md usa /agents/main/.

Superficie	Route	Requisito clave
Interfaz de usuario de chat	/agents/<AGENT_NAME>/	Tecla de función (solicitada en el navegador).
HTTP chat API	POST /agents/<AGENT_NAME>/chat	Tecla de función.
Streaming chat API	POST /agents/<AGENT_NAME>/chatstream	Tecla de función.
Punto de conexión de MCP	/runtime/webhooks/mcp	mcp_extension clave del sistema.

Recuperación de las llaves

Cuando alojas la interfaz de chat en Azure, te pide una tecla de función antes de enviar mensajes. Puedes usar la clave al llamar directamente a las APIs de chat HTTP.

Utiliza el siguiente az functionapp keys list comando para recuperar la tecla de función predeterminada de tu aplicación:

az functionapp keys list \
  --resource-group <RESOURCE_GROUP> \
  --name <FUNCTION_APP_NAME> \
  --query "functionKeys.default" \
  --output tsv

En este ejemplo, sustituye <RESOURCE_GROUP> y <FUNCTION_APP_NAME> por los nombres de tu grupo y de la app. Puedes incluir la clave devuelta en la x-functions-key cabecera o un code parámetro de cadena de consulta en la petición HTTP al punto final.

Al conectarte a un cliente MCP, solicita en su lugar el sistema de extensiones MCP usando el siguiente comando:

az functionapp keys list \
  --resource-group <RESOURCE_GROUP> \
  --name <FUNCTION_APP_NAME> \
  --query "systemKeys.mcp_extension" \
  --output tsv

El endpoint MCP requiere esta clave de sistema.

Flujo de solicitudes de la API de chat

Ambas APIs de chat integradas esperan un cuerpo JSON con un prompt campo:

{
  "prompt": "Summarize today's failures."
}

Úsalo POST /agents/<AGENT_NAME>/chat cuando quieras una respuesta JSON. El cuerpo de respuesta incluye session_id, response, y tool_calls. El tiempo de ejecución también refleja el mismo ID de sesión en la x-ms-session-id cabecera de respuesta.

Úsalo POST /agents/<AGENT_NAME>/chatstream cuando quieras Server-Sent Eventos (SSE). El flujo comienza con un session evento que contiene el ID de sesión resuelto, seguido de cero o más delta, intermediate, tool_start, y tool_end eventos, y termina con o doneerrorbien .

Para continuar una conversación multiturno, envía el ID de sesión de la respuesta anterior en la x-ms-session-id cabecera de la solicitud en llamadas posteriores chat o chatstream . Si omites ese encabezado, el tiempo de ejecución crea automáticamente una nueva sesión.

POST /agents/main/chatstream HTTP/1.1
Content-Type: application/json
Accept: text/event-stream
x-ms-session-id: <SESSION_ID_FROM_A_PREVIOUS_RESPONSE>

{"prompt":"Continue the last summary and add blockers."}

Sesiones y estado

Las interacciones de agentes en varios turnos requieren historial de sesión. El tiempo de ejecución gestiona el almacenamiento de sesión automáticamente en función del entorno:

Environment	Storage	Configuración
Azure	Blob Storage en la cuenta predeterminada de almacenamiento del host (AzureWebJobsStorage)	Cadena de conexión o basada en identidad (preferida). Consulta Configuración de identidad gestionada.
Desarrollo local	Basado en archivos en el directorio de configuración de agentes locales	No hace falta configuración.

El tiempo de ejecución no requiere una base de datos de sesión separada. La ejecución sandboxed también es consciente de sesión: cuando no hay un ID de sesión explícito disponible, el runtime utiliza una sesión sandbox aislada y nueva para que las invocaciones no relacionadas no compartan estado.

Planes de alojamiento con apoyo

El entorno de ejecución de los agentes sin servidor soporta estos planes de alojamiento de Azure Functions:

Plan	Escalado sin servidor	Notas
Consumo flexible	Sí	Escala a cero, facturación por segundo y escalado automático. Recomendado para la mayoría de las cargas de trabajo de los agentes.
Dedicado (App Service)	No	Instancias siempre activas con escalado manual o basado en reglas. Úsala cuando ya tengas instancias de planes de App Service con capacidad disponible.

Ambos planes soportan identidad gestionada, integración de redes virtuales y Application Insights.

Contenido relacionado

• Entorno de ejecución de agentes sin servidor en Azure Functions
• Crea agentes sin servidor con Azure Functions
• Compara el runtime de los agentes serverless con otras opciones de agentes de Microsoft
• Hospedaje del plan de consumo flexible