Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Use Microsoft Foundry Toolkit para Visual Studio Code para crear un flujo de trabajo basado en código a partir de un ejemplo de Microsoft Agent Framework. Ejecútelo localmente con Agent Inspector y, a continuación, implemente su código fuente en Foundry Agent Service como agente hospedado. Mantienes el código y sus dependencias. Foundry administra la infraestructura de hospedaje y el escalado.
Los flujos de trabajo hospedados coordinan los agentes en el código. Se diferencian del servicio de flujo de trabajo declarativo de Foundry que se va a retirar. Para ver otras rutas de creación, consulte Creación de un agente.
Prerequisites
Seleccione un proyecto de Foundry con un modelo desplegado. Use una región de agente hospedado compatible.
Permiso para usar el modelo e implementar agentes hospedados. Para el despliegue de código fuente, el rol Foundry Project Manager en el ámbito del proyecto incluye permisos de operaciones del agente y de asignación de roles. Consulte Permisos del agente hospedado.
Importante
Recientemente se cambió el nombre de los roles RBAC de Foundry. Foundry User, Foundry Owner, Foundry Account Owner y Foundry Project Manager se llamaban anteriormente Usuario de Azure AI, Propietario de Azure AI, Propietario de la cuenta de Azure AI y Administrador de proyectos de Azure AI. Es posible que siga viendo los nombres anteriores en algunos lugares mientras se implementa el cambio de nombre. El cambio de nombre no modifica los identificadores de rol y los permisos principales.
CLI de Azure para los pasos de autenticación local de este artículo.
Para el despliegue de contenedores, el registro y el acceso a la imagen que requiere la configuración de Azure Container Registry. Estos requisitos del Registro no se aplican a una implementación de código fuente.
- Python 3.13 para el entorno de ejecución alojado configurado para el ejemplo.
- Extensión Python para Visual Studio Code.
- .NET 10 SDK.
- Kit de desarrollo de C# para Visual Studio Code.
La ruta principal de implementación usa Code con el modo de paquete Remote y no requiere una compilación local con Docker. La ejecución local sigue enviando solicitudes de modelo a Foundry y puede incurrir en cargos. Consulte los límites y la disponibilidad del servicio y las notas de la versión de Toolkit de las funciones que utiliza.
Creación de un flujo de trabajo de agente hospedado
Elija un ejemplo de framework de agente que use el protocolo Responses. No necesitas crear antes un agente de prompts independiente. Para comparar ejemplos, Agent Builder y codificación asistida por Copilot, consulte Elegir una ruta de creación.
Usa el flujo de trabajo multiagente (marco de agentes), que encadena un escritor, un revisor y un formateador. La respuesta final procede del formateador. Revise el ejemplo de flujo de trabajo de Python para obtener la implementación completa y su guía de modelo.
Use el flujo de trabajo de traducción, que encadena tres agentes de traducción: inglés a francés, francés a español y español a inglés. Revise el ejemplo de flujo de trabajo de C# para obtener la implementación completa.
En la vista Foundry Toolkit, seleccione Developer Tools>>.
En Codificar un agente de ejemplos, seleccione Examinar todos los ejemplos.
En Crear agente hospedado a partir de una muestra, filtra por idioma, marco = y tipo de protocolo = Respuestas. Busque
workflow.En la captura de pantalla siguiente se muestra la galería con el Agente hospedado básico seleccionado como ejemplo. Para esta guía, seleccione el ejemplo de flujo de trabajo para el idioma en su lugar.
Seleccione el ejemplo de flujo de trabajo para el idioma.
Seleccione Siguiente.
En Crear, elija la carpeta del área de trabajo. Si la carpeta ya contiene archivos, escriba un nombre de carpeta para una nueva carpeta secundaria.
Si aparece El programa de instalación del entorno, seleccione Setup with Microsoft Foundry (Configurar con Microsoft Foundry) y, a continuación, seleccione la suscripción y el proyecto. Cuando ya está seleccionado un proyecto predeterminado, el formulario usa ese proyecto.
Seleccione una implementación de modelo compatible existente.
En la captura de pantalla siguiente se muestra la configuración del proyecto de ejemplo con rutas de acceso locales ocultas. Use su propio destino y la implementación de modelo que requiera su ejemplo.
Revise el destino y, a continuación, seleccione Crear.
Abra el proyecto generado en Visual Studio Code y lea su
README.md.
Los mosaicos Agent Framework, Copilot SDK y LangGraph de Crear agente abren la pestaña Crear con una plantilla de inicio Hello World seleccionada. Usa Ver todos los ejemplos para elegir un flujo de trabajo en lugar de una de esas plantillas iniciales. También puede abrir la galería desde Mis recursos>Agentes>Agente hospedado>Agregar agente hospedado.
Los nombres de ejemplo y el contenido pueden cambiar con el catálogo. Algunas versiones etiquetan estos flujos de trabajo de ejemplo. Use el vínculo GitHub del ejemplo para confirmar que seleccionó el flujo de trabajo previsto.
Omitir por ahora genera el código sin completar la configuración del modelo. Si lo elige, configure los valores de proyecto y modelo necesarios antes de ejecutar el ejemplo. Implementar y usar nuevo modelo, cuando está disponible, aprovisiona una implementación del modelo, no el agente alojado. La creación de los archivos de proyecto local no implementa el agente.
Configuración del proyecto local
Mantenga la carpeta que contiene azure.yaml abierta como raíz del área de trabajo. Compruebe la ruta project del servicio hosted-agent en ese archivo para encontrar su directorio de origen.
| Artefacto | propósito |
|---|---|
azure.yaml |
Declara el servicio hosted-agent, el directorio de origen, el entorno de ejecución, los protocolos y la configuración de implementación. |
main.py o Program.cs en el directorio de origen |
Implementa el flujo de trabajo e inicia su servidor de respuestas. |
requirements.txt o el archivo .csproj |
Declara las dependencias para el idioma seleccionado. |
.env en el directorio de origen |
Contiene valores locales del proyecto y del modelo. El kit de herramientas lo crea a partir de .env.example cuando el ejemplo proporciona ese archivo. |
.vscode/launch.json y .vscode/tasks.json |
Configure el servidor local, los datos adjuntos del depurador y el Inspector del agente. |
Los diseños de ejemplo pueden cambiar. Utilice los README.md y azure.yaml generados en lugar de suponer que el código y el archivo del entorno están en la raíz del área de trabajo.
Instalación de dependencias
Use los archivos de dependencia del ejemplo generado. Mantenga el intérprete seleccionado o el SDK coherentes con su configuración en tiempo de ejecución.
Ejecute Python: Crear entorno... desde la paleta de comandos para crear un entorno virtual o Python: seleccione Intérprete para seleccionar un entorno de Python 3.13 existente. Para configurar y seleccionar entornos, consulte Entornos de Python en Visual Studio Code.
Abra un terminal con ese entorno activo. Cambie al directorio de origen que contiene
main.pyyrequirements.txt.Instale los paquetes del ejemplo:
python -m pip install -r requirements.txtLos requisitos incluyen
debugpy, que la configuración de F5 generada utiliza. Referencia: Python dependencias de flujo de trabajo.
Ejecute C#: Compruebe los requisitos del área de trabajo desde la paleta de comandos.
En un terminal, cambie al directorio de origen que contiene el
.csprojarchivo y restaure sus paquetes:dotnet restoreReferencia: dotnet restore.
Para ver los controles y la configuración del depurador, consulte Depuración de C# en Visual Studio Code.
Establecimiento del proyecto y el modelo
Revise el .env archivo en el directorio de origen. Si no existe, créela con los valores requeridos por el ejemplo.
| Variable | Value |
|---|---|
FOUNDRY_PROJECT_ENDPOINT |
El punto de conexión del proyecto, con el formato https://<resource-name>.services.ai.azure.com/api/projects/<project-name>. |
AZURE_AI_MODEL_DEPLOYMENT_NAME |
Nombre de la implementación del modelo en ese proyecto, no solo el nombre del catálogo del modelo. |
Ambos ejemplos de flujo de trabajo cargan .env durante el inicio. El punto de conexión del proyecto no es un punto de conexión de una cuenta de Azure OpenAI. Mantenga el archivo fuera del control de código fuente y no coloque las credenciales en el código de la aplicación.
Autenticación local
Los ejemplos usan DefaultAzureCredential. Para la ruta de acceso de credenciales de CLI de Azure, inicie sesión con una cuenta que pueda acceder al modelo del proyecto:
az login
Referencia: Inicie sesión con CLI de Azure.
Al iniciar sesión en el kit de herramientas, se selecciona el proyecto para las operaciones de la extensión. El proceso del agente local también necesita una credencial compatible. Para ver otras opciones, consulte DefaultAzureCredential para Python o cadenas de credenciales para .NET.
Ejecución local del flujo de trabajo hospedado
Utiliza la configuración de depuración generada para iniciar el servidor HTTP y abrir el Inspector del agente. Abrir Agent Inspector por sí solo no inicia el servidor.
Use esta solicitud de prueba:
Create a slogan for a new electric SUV that is affordable and fun to drive. El flujo de trabajo devuelve un eslogan con formato una vez que el redactor, el revisor y el formateador hayan terminado.
Use esta solicitud de prueba: The quick brown fox jumps over the lazy dog. el flujo de trabajo ejecuta su cadena de traducción y devuelve una respuesta.
- Vuelva al área de trabajo del proyecto generada.
- Establezca un punto de interrupción en el código de flujo de trabajo si desea inspeccionar la ejecución.
- Presione F5. Si se le solicita, seleccione Depurar servidor HTTP del Agente local.
- Espere a que el servidor se inicie y el Inspector del agente se abra.
- Envíe la solicitud de prueba para su muestra.
- Inspeccione la respuesta y repita con otra solicitud. Si establece un punto de interrupción, inspeccione los valores y continúe la ejecución.
Una vez que el ejemplo funcione, modifique el flujo de trabajo y repita la prueba local. Si agrega herramientas, envíe una solicitud que requiera un resultado real de la herramienta e inspeccione la llamada. Una respuesta de solo modelo o una respuesta ficticia no demuestra que la herramienta activa funciona.
En la captura de pantalla se muestra un agente local habilitado para herramientas, no un ejemplo de flujo de trabajo. Agent Inspector muestra la respuesta y las llamadas a herramientas en una cascada de latencia y una cronología de la ejecución. Los detalles de inspección disponibles dependen del agente en ejecución y de su instrumentación.
Si usa GitHub Copilot, puede ejecutar /validate-microsoft-foundry-hosted-agent en Copilot Chat para revisar el proyecto con los procedimientos recomendados de Foundry. Este comando Chat abre un informe; no es un comando de terminal ni un sustituto de ejecutar el flujo de trabajo.
Las tareas generadas usan el puerto 8088 para el servidor del agente. La depuración de Python también usa el puerto 5679. Si al iniciar se informa de un conflicto de puertos, detenga el proceso en conflicto que esté ejecutando o ajuste de manera coherente la configuración generada de la tarea.
Ejecución sin el depurador
Para ejecutarlo manualmente, abra una terminal en el directorio de origen del ejemplo con sus dependencias, variables de entorno y credenciales de Azure disponibles.
python main.py
Referencia: punto de entrada del flujo de trabajo de Python.
Establezca la dirección HTTP para el servidor local y, a continuación, ejecútela:
$env:ASPNETCORE_URLS = "http://localhost:8088"
dotnet run
Referencia: direcciones URL del servidor de ASP.NET Core y dotnet run.
A continuación, ejecute Foundry Toolkit: abra Agent Inspector desde la paleta de comandos y conéctese al servidor local en el puerto 8088. Ejecutar un ejemplo con python o dotnet run inicia un proceso local, no un contenedor.
Visualización de la ejecución del flujo de trabajo del agente hospedado
Utiliza Agent Inspector para inspeccionar los eventos, las respuestas y las llamadas a herramientas que emite tu agente en ejecución. Cuando el tiempo de ejecución emite eventos de flujo de trabajo, use la visualización del flujo de trabajo para inspeccionar la secuencia de pasos.
Los detalles disponibles dependen de la instrumentación de la muestra. Siga las instrucciones de configuración de telemetría del ejemplo para conocer los requisitos específicos del entorno de ejecución.
Estos pasos usan el protocolo de respuestas. Otros ejemplos necesitan clientes que coincidan con su protocolo: la vista de Invocaciones HTTP no es un cliente WebSocket, y los ejemplos de actividad de Python usan Microsoft 365 Agents Playground. Siga las instrucciones de prueba local del ejemplo seleccionado. Cambiar un nombre de protocolo en la configuración no agrega ese protocolo al servidor. Consulte Elección de un protocolo de agente hospedado.
Implementación del agente hospedado
Después de que el flujo de trabajo local se comporte según lo previsto, impleméntelo desde el área de trabajo del proyecto. Python y C# comparten el procedimiento de implementación. Comience con el código y el modo de paquete remoto para cargar las dependencias de origen y permitir que Foundry restaure las dependencias.
Preparación de la configuración de implementación
Revise y guarde el servicio de agente hospedado en azure.yaml. Conserve la configuración del protocolo del ejemplo y declare la implementación del modelo y otras opciones de tiempo de ejecución necesarias.
El despliegue resuelve los valores de entorno declarados a partir de .env del directorio de origen o del entorno del proceso. No reenvía todas las entradas locales .env .
La plataforma proporciona valores de tiempo de ejecución reservados como FOUNDRY_PROJECT_ENDPOINT; no vuelva a declararlos como configuración de implementación. Consulte Variables de entorno insertadas en la plataforma.
Revise las reglas de omisión del directorio de origen antes de empaquetar. Mantener .env, las credenciales, los entornos virtuales y las cachés fuera del paquete. Para la implementación de ZIP, una raíz .agentignore de origen reemplaza las reglas de .gitignore y .dockerignore, por lo que conserva las exclusiones necesarias si agrega ese archivo.
Importante
No confirme ni empaquete secretos. El inicio de sesión local no transfiere los permisos del usuario al agente implementado. Configura el acceso para la identidad del entorno de ejecución del agente y las conexiones admitidas. Consulte Permisos del agente hospedado.
Implementar el código fuente en modo de paquete remoto
Use la raíz del área de trabajo generada para que el kit de herramientas pueda leer la configuración del servicio y localizar su directorio de origen.
Detenga la sesión de depuración local.
Seleccione Herramientas para desarrolladores>Compilar>Implementar en Microsoft Foundry. También puede ejecutar Foundry Toolkit: Implementar agente hospedado desde la paleta de comandos.
Si aparece Configuración del proyecto de Foundry, seleccione la suscripción y el proyecto y, a continuación, seleccione Siguiente. De lo contrario, confirme que el proyecto predeterminado es el destino previsto.
En Aspectos básicos, seleccione Código como método de implementación y remoto como modo de paquete.
Seleccione Nuevo agente y escriba el nombre del agente hospedado. Para actualizar un agente implementado, seleccione Agente existente y elija ese agente en su lugar.
Seleccione Siguiente.
En Revisar e implementar, compruebe El lenguaje, la versión en tiempo de ejecución, el punto de entrada y la CPU y la memoria en el ejemplo. Confirme que el directorio de origen coincide con la ruta de acceso del
projectservicio.En la captura de pantalla siguiente se muestra un ejemplo con Python 3.14 y su punto de entrada oculto, no la configuración de estos ejemplos de flujo de trabajo. Para Python, use Python 3.13 con
python3 main.py. Para C#, use .NET 10 y el punto de entrada detectado para el proyecto generado.Seleccione Implementar. Siga el progreso de las notificaciones y la salida.
Continúe con Probar el flujo de trabajo implementado.
Haga coincidir el tiempo de ejecución con la configuración de ejemplo y el entorno local. No acepte un entorno de ejecución diferente solo porque es el valor predeterminado del asistente.
El kit de herramientas guarda las opciones de implementación al enviar el formulario. Esas configuraciones locales no demuestran que la implementación en la nube se realizó correctamente. La actualización de un agente existente crea una nueva versión en lugar de cambiar una versión anterior en su lugar.
Elige otro modo del paquete ZIP
El kit de herramientas ofrece estas opciones de empaquetado de código fuente:
| Modo de paquete | ¿Qué ocurre? | Qué preparar |
|---|---|---|
| Remoto | Toolkit empaqueta el código fuente. Foundry restaura los requisitos de Python o el proyecto .NET durante el aprovisionamiento. | Origen, declaraciones de dependencia y un punto de entrada compatible. |
| Agrupado | El kit de herramientas prepara el código fuente y ejecuta localmente el Comando Package antes de crear el archivo ZIP. Foundry ejecuta el paquete preparado. | Dependencias de Linux compatibles y las herramientas locales requeridas por el comando . El comando Python predeterminado instala dependencias compatibles en packages/; el comando .NET crea la salida de publicación. |
Los entornos de ejecución ZIP seleccionables son Python 3.13, Python 3.14 y .NET 10. Haz coincidir el entorno de ejecución con tu código y sus dependencias. Para conocer los diseños, los límites y los requisitos de servicio, consulte Implementación desde código fuente. Para obtener información sobre la política de soporte de los entornos de ejecución, consulte Entornos de ejecución alojados admitidos.
Implementar una imagen de contenedor
Elija Contenedor en Aspectos básicos cuando necesite una imagen en tiempo de ejecución personalizada o ya tenga una imagen compatible.
| Selección del registro | Comportamiento del kit de herramientas |
|---|---|
| ACR predeterminado | Crea o reutiliza un registro para el proyecto seleccionado y, a continuación, compila e inserta la imagen a través de Azure Container Registry (ACR). |
| ACR personalizado | Usa un registro existente que seleccione y, a continuación, compila e inserta la imagen a través de ACR. |
| Imagen de ACR personalizada | Usa una referencia a una imagen de ACR ya creada sin compilar ni publicar el código fuente. |
Para las opciones de compilación, revise el dockerfile y el contexto de compilación antes de la implementación. Si genera un Dockerfile en el asistente, revise el archivo y seleccione Continuar e implementar. Estas opciones usan compilaciones remotas de ACR, no compilaciones locales de Docker.
Las opciones del Registro personalizadas usan un registro en la suscripción seleccionada. El proceso de compilación del registro personalizado requiere acceso a la red pública; el proceso con imagen precompilada tiene requisitos independientes para redes privadas. Elegir una imagen no configura la conectividad de red.
Revise los requisitos de contenedor y las instrucciones de redes privadas antes de usar un registro personalizado. Estos despliegues se dirigen a Foundry Agent Service, no a la ruta del agente hospedado en Azure Container Apps ya retirada. Para migrar un agente antiguo, siga Migre desde la versión preliminar del agente hospedado.
Prueba del flujo de trabajo implementado
Una solicitud de creación exitosa no prueba que el entorno de ejecución esté listo ni que se pueda acceder a su modelo y a sus herramientas. Pruebe la versión implementada exacta.
- En Mis recursos>>, seleccione el nombre del agente.
- Seleccione la versión numerada que acaba de implementar.
- En Detalles, espere a que el estado de implementación indique que el agente está en ejecución. Si se produce un error, inspeccione la salida de implementación antes de volver a intentarlo.
- Abra Playground y envíe la misma solicitud que ha probado localmente.
- Revise la respuesta. Si ha agregado herramientas, envíe una solicitud que requiera esas herramientas e inspeccione las llamadas.
Las ejecuciones locales y en la nube usan credenciales diferentes, entornos de dependencia y rutas de acceso de red. Una respuesta local correcta no garantiza una respuesta remota correcta.
Inspección y actualización del agente implementado
Usa el entorno de pruebas remoto para probar e inspeccionar tu agente desplegado. A diferencia de las pruebas locales con Agent Inspector, las solicitudes de este entorno de pruebas se envían al agente alojado en Foundry.
En
Foundry Toolkit , seleccioneHerramientas de desarrollo Compilación Área de pruebas del agente hospedado. En la lista desplegable Agente hospedado , seleccione el agente implementado y la versión que se va a inspeccionar. Abra Playground para enviar una solicitud y ver los detalles de la respuesta y la sesión.
En la captura de pantalla siguiente se muestra una respuesta ilustrativa del agente implementado, no la salida esperada de ninguno de los ejemplos de flujo de trabajo. Los identificadores de agente y sesión están ocultos.
Use estos controles para inspeccionar y actualizar el agente. Las pestañas disponibles dependen de su protocolo y de los servicios conectados.
| Tarea | Action |
|---|---|
| Revisar los detalles de implementación | Abra Detalles para el estado, la configuración y el punto de conexión copiable. |
| Prueba de una versión | Seleccione una versión numerada para las solicitudes del área de juegos. Automático usa la misma selección de versión que el extremo de servicio, que no es necesariamente la más reciente. El selector no cambia el enrutamiento para otros clientes. |
| Revisar registros de tiempo de ejecución | Abra Sesiones, seleccione una sesión y vea sus registros. Los registros en tiempo de ejecución requieren una sesión; la salida de compilación es independiente. Detener una secuencia de registro o cancelar una solicitud no detiene el agente hospedado. |
| Recuperación del código implementado | Use Descargar recurso de código para una implementación ZIP. Un despliegue de imagen expone la referencia de la imagen en lugar de un proyecto fuente descargable. |
| Comportamiento de la actualización | Edite y pruebe el código local y repita el procedimiento de implementación con El agente existente para crear una nueva versión. |
Utiliza Trazas y Evaluación, cuando estén disponibles, para investigar y medir la calidad más allá de una única respuesta satisfactoria. Siga los requisitos previos para el seguimiento del agente hospedado y la evaluación del agente hospedado.
La implementación proporciona al agente un punto de conexión para su uso mediante programación. No se requiere un paso de publicación independiente para el acceso a la API. La publicación en Teams o Microsoft 365 es una tarea independiente. Consulte el punto de conexión del agente actual y el modelo de publicación.
Troubleshooting
Use el error notificado y la configuración de ejemplo para identificar el paso con errores.
| Síntoma | Action |
|---|---|
| Se produce un error en el inicio local porque falta un paquete. | Confirme el intérprete o el SDK seleccionados y, a continuación, instale las dependencias desde el directorio de origen del ejemplo. |
| No se encuentra el punto de conexión o el modelo del proyecto. | Compruebe FOUNDRY_PROJECT_ENDPOINT y AZURE_AI_MODEL_DEPLOYMENT_NAME. No sustituya un extremo de la cuenta ni el nombre de un catálogo de modelos. |
| Se produce un error de autenticación o autorización. | Compruebe la credencial local y el acceso al proyecto. Revise los permisos del agente hospedado para los requisitos de implementación e identidad en tiempo de ejecución. |
| Agent Inspector no puede conectarse. | Confirme que el servidor iniciado y el puerto 8088 están disponibles. Abrir Inspector solo no inicia el servidor. |
| Se produce un error en una implementación. | Revise el error de implementación y la salida de compilación. En el caso del código, compruebe el tiempo de ejecución, el punto de entrada, el modo de paquete y omita las reglas. Para un contenedor, compruebe los permisos de imagen y registro. |
| La respuesta local funciona, pero se produce un error en la versión implementada. | Compare los permisos de identidad y entorno implementados con la configuración local. Vuelva a probar la versión implementada exacta. |
Limpieza de recursos
Detenga la sesión de depuración local cuando haya terminado. Si ya no necesita el agente de prueba implementado, siga Administrar agentes hospedados para quitarlo.
Al eliminar el agente, se eliminan sus versiones y se finalizan las sesiones activas. No quita todos los recursos de Azure asociados.
Elimine solo los recursos en la nube creados para este ejercicio que no use ninguna otra aplicación. No elimine un proyecto de Foundry compartido, una implementación de modelos ni un registro de contenedor.
Contenido relacionado
Use estas guías para ampliar el flujo de trabajo: