Guía para desarrolladores de habilidades alojadas en Azure Functions

Las habilidades alojadas en Azure Functions utilizan un modelo de programación Markdown-first en el tiempo de ejecución de Python de Azure Functions. Defines cada habilidad alojada en un .agent.md archivo. El front matter YAML establece su configuración. El cuerpo Markdown da instrucciones al modelo.

La mayoría del trabajo de desarrollo modifica estas definiciones y sus archivos de herramientas y de configuración. Normalmente no necesitas cambiar el código de inicio de las funciones generadas. Sin embargo, la app sigue necesitando los ajustes correctos de host, dependencias de Python, acceso al modelo y permisos de servicio.

Esta guía utiliza el paquete azurefunctions-agents-runtimede vista previa pública . Para una configuración local completa, empieza con el canvas quickstart. Para crear recursos de Azure y desplegar una muestra, utiliza el inicio rápido de Azure Developer CLI.

Estructura del proyecto

Utiliza la siguiente estructura en la raíz del proyecto de la app de funciones. Añade los archivos opcionales solo cuando tu app los necesite.

<project_root>/
├── function_app.py
├── host.json
├── requirements.txt
├── local.settings.json
├── summarize.agent.md
├── agents.config.yaml
├── mcp.json
├── skills/
│   └── report-writing/
│       ├── SKILL.md
│       ├── references/
│       │   └── report-format.md
│       └── assets/
│           └── example-report.md
└── tools/
    └── get_policy.py

El código function_app.py de inicio puede ser tan pequeño como este:

from azure_functions_agents import create_function_app

app = create_function_app()

El runtime detecta las habilidades alojadas y sus capacidades configuradas cuando el host de Functions carga la app. Guarda los archivos de host y dependencias de tu proyecto inicial. Para los archivos estándar de aplicaciones en Python, consulta la guía para desarrolladores de Python.

Definir una skill

Crea summarize.agent.md en la raíz del proyecto:

---
name: Request summary
description: Summarize a request and identify missing information.
trigger:
  type: http_trigger
  args:
    route: summarize
    methods: [POST]
    http_auth: function
builtin_endpoints:
  debug_chat_ui: true
  http_auth: function
---

Summarize the request supplied in the HTTP request body.

Return these sections:

- Summary: State the purpose of the request.
- Missing information: List the facts needed to complete the request.
- Questions: Ask specific questions for the missing facts.

Use only the supplied facts. Do not invent names, dates, or approvals.
If the request is empty or unclear, explain what information is needed.

Esta definición acepta solicitudes HTTP POST en la summarize ruta. En Azure, http_auth: function requiere una clave de función o de host. El prefijo estándar de la ruta de Functions es api, por lo que la ruta normalmente es /api/summarize. No use una prueba local para confirmar la autenticación implementada. Para más detalles, véase autorización de disparo HTTP.

El nombre del archivo proporciona la identidad de la habilidad alojada. Para summarize.agent.md, el nombre de la función Azure generada es summarize, y el segmento de ruta del extremo incorporado es summarize. El name campo es un nombre de visualización. Un cambio en ese campo no cambia el nombre de la función. Un HTTP routeexplícito, como en este ejemplo, establece la ruta de disparo HTTP.

El bloque builtin_endpoints habilita la ventana de chat y sus APIs subyacentes del chat para pruebas locales. Para ver los endpoints disponibles y la configuración de autenticación, consulta endpoints incorporados.

Escribe instrucciones claras

Indica el objetivo, la entrada, las herramientas a usar y la salida requerida. Explica qué hacer cuando falten datos o una herramienta falla. Indica qué acciones no debe realizar la habilidad alojada.

Las instrucciones no son controles de autorización. Valida las reglas exactas de negocio, permisos y aprobaciones requeridas en código o en el servicio que realiza la acción. Por ejemplo, un aviso que dice "enviar solo informes aprobados" no reemplaza una comprobación de aprobación en la herramienta que envía el informe.

Configurar los valores predeterminados compartidos y las anulaciones

Establecer modelos compartidos y tiempos de espera por defecto en agents.config.yaml:

model: $FOUNDRY_MODEL
timeout: 900

Establezca FOUNDRY_MODEL en una implementación de modelo disponible a través de su proveedor configurado. Para un ejemplo completo de configuración de la app Foundry, consulta Configurar ajustes locales. Para otros proveedores, véase configuración del proveedor de modelos.

Añadir sobreescrituras soportadas para los valores predeterminados definidos agents.config.yaml en el front matter cuando la habilidad alojada necesite diferentes configuraciones:

timeout: 120
mcp:
  exclude:
    - office365-outlook
skills: false

Este ejemplo establece un tiempo de espera de ejecución de 120 segundos, elimina un servidor MCP y desactiva habilidades reutilizables para esta habilidad alojada. El nombre del servidor excluido debe coincidir con una clave en mcp.json.

Usa $SETTING_NAME para insertar una configuración de app en un valor de cadena compatible. Por ejemplo, model: $FOUNDRY_MODEL lee la configuración del modelo. Esta sintaxis no es la sintaxis completa de expresiones de shell. Para las reglas de sustitución, véase sustitución de variables.

Establecer un desencadenador

Usa un disparador explícito en cada .agent.md archivo que empiece con un evento. Para procesar mensajes de la cola de Azure Storage en lugar de solicitudes HTTP, reemplaza el trigger bloque:

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

También cambia las instrucciones para que describan la entrada del mensaje de cola en lugar de un cuerpo de solicitud HTTP.

El connection valor es el nombre de una configuración de aplicación o el prefijo de una colección de configuración basada en identidad, no un secreto incrustado. Configura la conexión de almacenamiento y los permisos por separado. Para más información, consulta Conexiones del desencadenador de cola.

Elige un disparador para la fuente del evento:

Para la lista completa y los argumentos requeridos, véase tipos de disparadores soportados.

Los endpoints opcionales integrados de chat y MCP son independientes del disparador explícito. Consulta endpoints integrados para más información. Una definición de servidor MCP remoto en mcp.json no expone la aptitud hospedada como servidor MCP.

Conecta un servidor MCP

Usa un servidor MCP remoto cuando otro servicio ya te suministre las herramientas que necesitas. Añadir mcp.json a la raíz del proyecto de la app de funciones:

{
  "servers": {
    "microsoft-learn": {
      "type": "http",
      "url": "https://learn.microsoft.com/api/mcp"
    }
  }
}

El entorno de ejecución admite los transportes remotos http y streamable-http. No inicia servidores MCP locales basados en stdio ni en comandos.

Las habilidades alojadas heredan los servidores MCP descubiertos a menos que los excluyas. Para excluir al servidor de una habilidad alojada, define mcp.exclude en el .agent.md archivo. Para limitar un servidor a herramientas específicas, agregue una matriz tools a su entrada en mcp.json. Utilice los nombres exactos de las herramientas publicados por ese servidor. Esta selección se aplica a la definición del servidor.

Para la autenticación de Microsoft Entra, establezca auth.scope en el ámbito del token del servidor. También puedes configurar auth.client_id para seleccionar una identidad gestionada asignada por el usuario. La identidad seleccionada debe tener permiso para llamar al servidor. No pongas secretos en mcp.json. Para más detalles, véase configuración del servidor MCP.

La ejecución alojada no es interactiva. Esta configuración basada en identidad no realiza automáticamente un flujo de OAuth interactivo para el usuario. Si un servicio empresarial requiere autorización delegada de usuario, considera un conector compatible y su conexión gestionada. Confirma que el conector soporta el modelo de autorización requerido por el servicio. Consulte Usar conectores de Azure.

Reutilizar instrucciones con aptitudes

Usa una habilidad reutilizable para la guía que varias habilidades alojadas necesiten, o para material de referencia que no sea necesario en cada solicitud.

Creación de skills/report-writing/SKILL.md:

---
name: report-writing
description: Write a review report from supplied facts. Use when a task requests a review report.
---

Read [the report format](references/report-format.md) before you write.
Use [the example report](assets/example-report.md) as a format example,
not as a source of facts.

State the result, the supporting facts, and the questions that remain.
If required facts are missing, list them. Do not invent a result.

En references/report-format.md, definan las secciones requeridas del informe. En assets/example-report.md, proporciona un informe de ejemplo que muestre el formato.

El valor de name de la aptitud debe coincidir con el nombre del directorio que la contiene, como report-writing. El runtime proporciona nombres de habilidades y descripciones para que se puedan descubrir y carga instrucciones y recursos completos bajo demanda. Mencione los recursos complementarios en SKILL.md para que la aptitud hospedada sepa cuándo debe consultarlos.

Mantén cada habilidad en su propia carpeta justo debajo de skills/. Para obtener instrucciones de creación, consulte Aptitudes.

Los archivos de skill no registran automáticamente herramientas ejecutables. Utilice una herramienta configurada para ejecutar acciones. No asumas que un script en una habilidad da permiso al modelo o una forma de ejecutarlo.

Agregar herramientas

En primer lugar, utilice una herramienta MCP remota o una herramienta del sistema del entorno de ejecución si cumple el requisito. Añadir herramientas personalizadas de Python para lógica específica de cada aplicación.

Herramientas del sistema del entorno de ejecución

El entorno de ejecución habilita la herramienta del sistema web_request de forma predeterminada. Realiza solicitudes salientes a direcciones web públicas. HTTPS es obligatorio por defecto. Para restringir las solicitudes a un nombre de host exacto, añade esta configuración a agents.config.yaml:

system_tools:
  web_request:
    allowed_hosts:
      - example.com

Establezca system_tools.web_request: false para deshabilitar la herramienta en toda la aplicación o en una sola aptitud hospedada. Una lista de autorización restringe los destinos. No concede permiso para usar un servicio ni enviar datos confidenciales.

Para la ejecución aislada de Python, configura un pool de intérpretes de código Python de sesiones dinámicas de Azure Container Apps:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Configure ACA_SESSION_POOL_ENDPOINT como el endpoint de gestión del pool. Conceda a la identidad de la aplicación los permisos necesarios sobre el grupo antes de utilizarlo. Para la configuración y requisitos de identidad, véase ejecución en formato sandbox.

Herramientas de Python personalizadas

Creación de tools/get_policy.py:

from azure_functions_agents import tool


@tool
def get_policy_version() -> str:
    """Return the version of the sample review policy."""
    return "2026-10"

Utilice una herramienta pública por cada archivo .py de tools/. El runtime registra la primera herramienta ordinaria soportada que encuentra en cada archivo. Utiliza anotaciones de tipo y un docstring claro para que el modelo pueda entender el propósito y las entradas de la herramienta. Añadir cualquier paquete necesario a requirements.txt.

Una herramienta personalizada de Python se ejecuta en el worker de Functions Python. No está automáticamente aislado en un sandbox. Valida las entradas, hace cumplir los permisos y reporta los fallos explícitamente. Para herramientas que cambian el estado externo, haz que las llamadas repetidas sean seguras, por ejemplo usando una clave de idempotencia.

Las herramientas de flujo de trabajo duraderas utilizan un contrato separado @workflow_tool . Para ese modelo, consulta flujos de trabajo dinámicos.

Gestionar la configuración

La configuración local no se copia automáticamente a la configuración de la app de Azure. Configura ambos entornos. Mantén los secretos fuera de Git, usa la identidad gestionada donde sea compatible y utiliza el almacenamiento secreto adecuado para las credenciales que aún se requieren. Consulte Configuración local y Administrar la configuración de la aplicación.

El valor de timeout de la aptitud hospedada y el valor de functionTimeout son límites independientes. Configura ambos ajustes para tu carga de trabajo. Un timeout de skill alojada no anula los límites del plan de alojamiento ni los límites de respuesta HTTP. Consulte Duración del tiempo de espera de una aplicación de función.

Utiliza conectores de Azure

Los conectores de Azure permiten que las habilidades alojadas llamen a operaciones externas autorizadas y reciban eventos de servicio sin necesidad de código de cliente y autenticación personalizados. Esta sección asume que los recursos del conector ya existen.

Para configurar un servidor MCP y su conexión, véase Crear un conector de servidor MCP.

Para un servidor MCP Microsoft 365 Outlook existente, añade una entrada a mcp.json:

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

Establezca O365_MCP_SERVER_URL en el punto de conexión del servidor implementado, en la configuración de la aplicación local o de Azure. Conceda a la identidad de la aplicación de funciones acceso a ese servidor MCP. Para seleccionar una identidad gestionada asignada por el usuario, añade auth.client_id con su ID de cliente.

Configura ambos límites de autorización:

Los permisos concedidos en un límite no otorgan permisos en el otro. La autorización de la conexión no se convierte automáticamente en la identidad de cada llamante de tu habilidad alojada.

Para iniciar una habilidad alojada desde un evento conector, primero crea y autoriza una conexión. A continuación, utilice este bloque de desencadenador en su archivo .agent.md:

trigger:
  type: connector_trigger

También debes configurar el evento upstream, el enrutamiento de callback y la autenticación de callback en el espacio de nombres del Connector. Una definición de servidor en mcp.json no se suscribe a eventos. Para requisitos de extensión y configuración de eventos, véase Usar conectores gestionados en Azure Functions.

Ejecución en modo local

Utiliza Azure Functions Core Tools para iniciar la app en tu ordenador. También necesitas Python 3.13 o posterior y acceso a un despliegue de modelo.

Configuración de valores locales

Crear local.settings.json en la raíz del proyecto de la app de funciones. Para un modelo de Foundry y Azure Storage local, utiliza esta estructura:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "python",
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "AZURE_FUNCTIONS_AGENTS_PROVIDER": "foundry",
    "FOUNDRY_PROJECT_ENDPOINT": "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
    "FOUNDRY_MODEL": "<model-deployment-name>"
  }
}

Sustituye los marcadores de posición de endpoint y modelo por tus valores de despliegue. Utilice una implementación de modelo que exista en su proyecto de Foundry y conceda a su identidad de desarrollador local acceso a ella. Agregue los valores de configuración que utilicen los servidores MCP, las herramientas o los desencadenadores. Mantén local.settings.json fuera del control de versiones.

Utiliza un emulador como fuente de datos cuando haya un emulador compatible disponible. Por ejemplo, Azurite suministra almacenamiento local de Blob, Queue y Table. Inicia Azurite antes del host de Functions cuando uses UseDevelopmentStorage=true. Para Service Bus, véase el emulador Service Bus.

Los espacios de nombres de conectores, conexiones y servidores MCP de conectores requieren recursos reales de Azure. La ejecución local sigue llamando a esos recursos. Las llamadas de modelo y las sesiones dinámicas de Azure Container Apps también utilizan sus servicios configurados y pueden generar cargos.

Iniciar el host de funciones

Crea y activa un entorno virtual en Python tal y como se describe en la guía de desarrollo local de Python. En el directorio raíz del proyecto de la aplicación de funciones, instale los paquetes desde requirements.txt:

python -m pip install -r requirements.txt

Para Foundry con acceso basado en identidad, inicia sesión con una identidad que tenga permiso para usar el modelo:

az login

Inicia el host desde el mismo directorio:

func start

El host lista la summarize función y los endpoints integrados habilitados por el ejemplo. Con el prefijo de ruta 7071 y el puerto api predeterminados, la salida es similar a:

Functions:

    agent_summarize_builtin_chat: [POST] http://localhost:7071/api/agents/summarize/chat

    agent_summarize_builtin_chatstream: [POST] http://localhost:7071/api/agents/summarize/chatstream

    agent_summarize_builtin_chat_page: [GET] http://localhost:7071/api/agents/summarize/

    agent_summarize_builtin_history: [GET] http://localhost:7071/api/agents/summarize/history

    summarize: [POST] http://localhost:7071/api/summarize

Mantén el host activo mientras pruebas. Lee la salida del terminal para detectar errores de configuración y las URLs de funciones registradas. Para obtener más información, consulte Ejecutar una función local.

Prueba con la ventana de chat

El summarize.agent.md ejemplo ya habilita la ventana de chat integrada y las APIs subyacentes del chat.

Abra http://localhost:7071/api/agents/summarize/ en el navegador cuando host.json use el prefijo de ruta predeterminado api. Si tu proyecto inicial establece extensions.http.routePrefix en una cadena vacía, usa http://localhost:7071/agents/summarize/ en su lugar. Usa el puerto host real si difiere de 7071.

Introduce una solicitud de ejemplo, envíala e inspecciona la respuesta y el registro del host. Por ejemplo, pide a la habilidad alojada que resuma una solicitud con una fecha de entrega faltante. Comprueba que la respuesta identifique la fecha que falta en lugar de inventarse una. Pruebe también los casos de ausencia de datos de entrada y errores de las herramientas.

La ejecución de Local Core Tools normalmente omite las comprobaciones de tecla de función. Mantén http_auth: function en la definición y prueba la autenticación por separado en Azure. Para una ventana de chat implementada, proporcione la clave de función cuando se le solicite. Activa los endpoints de depuración solo cuando sea necesario. Para obtener información sobre las rutas y la recuperación de claves, consulte Puntos de conexión integrados.

Implementar en Azure

Elige un método de despliegue para tu proyecto:

Tras el despliegue, confirma que la configuración de la app de Azure contiene los valores requeridos, que la identidad de la app tiene acceso al modelo y las herramientas, y que cada conexión de conector está autorizada. Prueba el disparador desplegado y su autenticación con una solicitud controlada antes de usar los datos de producción.

Ver ejemplos de principio a fin

Utiliza estos ejemplos para ver cómo las habilidades alojadas combinan desencadenantes, herramientas y servicios de Azure en una aplicación completa. Cada repositorio incluye instrucciones de instalación y despliegue.

Contenido relacionado

• Resumen de habilidades alojadas en Azure Functions
• Referencia de configuración de habilidades alojada
• Construye y prueba con el lienzo de habilidades alojado
• Implementar una aplicación de aptitudes hospedadas controlada por eventos
• Crear flujos de trabajo dinámicos
• Guía de observabilidad en tiempo de ejecución
• Ejemplos de aptitudes hospedadas