ai-agents-for-beginners

Desplegando Agentes Escalables con Microsoft Foundry

Desplegando Agentes Escalables

Hasta este punto en el curso has construido agentes que se ejecutan en tu portátil, dentro de un cuaderno, impulsados por az login y un puñado de variables de entorno. Esa es exactamente la manera correcta de aprender. No es la manera correcta de ejecutar un agente del que dependen miles de clientes a las 3 a.m.

Esta lección trata sobre la brecha entre “funciona en mi máquina” y “funciona, de forma confiable y asequible, en producción.” Cerramos esa brecha usando Microsoft Foundry y el Microsoft Foundry Agent Service, y lo hacemos construyendo un agente real de soporte al cliente que tiene herramientas, recuperación, memoria, evaluación y monitoreo.

Introducción

Esta lección cubrirá:

Objetivos de Aprendizaje

Al completar esta lección, sabrás cómo:

Requisitos Previos

Esta lección asume que has completado las lecciones anteriores y estás cómodo con:

También necesitarás:

De Prototipo a Producción: Lo que Realmente Cambia

Un agente prototipo y un agente de producción comparten el mismo bucle central — razonar, llamar herramientas, responder. Lo que cambia es todo lo que está envuelto alrededor de ese bucle. El modelo es quizá el 20% de un agente en producción; el 80% restante es el esqueleto operativo.

Preocupación Prototipo Producción
Alojamiento Se ejecuta en tu cuaderno Se ejecuta como un servicio alojado, versionado y desplegado
Identidad Tu token az login Identidad gestionada con RBAC con ámbito
Estado En memoria, perdido al reiniciar Externalizado (almacén de hilos, servicio de memoria)
Fallas Ves el rastreo de excepción Reintentos, alternativas, buzón para mensajes muertos, alertas
Costo “Son unos centavos” Rastreado por petición, enrutado, almacenado en caché, presupuestado
Calidad Evalúas la salida visualmente Evaluado automáticamente antes de cada lanzamiento
Confianza Apruebas cada acción Política + humano en el bucle para acciones riesgosas

Ten esta tabla en mente. Cada sección a continuación corresponde a una de estas filas.

Patrones de Despliegue de Agentes

Hay tres patrones que usarás, a menudo en combinación.

1. Agentes alojados en cliente

El objeto agente vive dentro del proceso de tu aplicación. Tu código llama directamente al proveedor del modelo; el bucle de razonamiento se ejecuta en tu servicio. Esto es lo que se ha hecho en cada lección previa.

2. Agentes Hospedados (Foundry Agent Service)

El agente está registrado como un recurso en Microsoft Foundry. Foundry aloja el bucle de razonamiento, almacena los hilos, aplica seguridad de contenido y RBAC, y hace visible el agente en el portal de Foundry. Tu aplicación se vuelve un cliente ligero que crea hilos y lee respuestas.

3. Flujos de Trabajo de Agentes

Múltiples agentes (y herramientas) se componen en un grafo con flujo de control explícito — pasos secuenciales, ramificaciones, nodos de aprobación humana y puntos de control duraderos que pueden pausar y reanudar. Esta es la capacidad de Flujos de Trabajo del Microsoft Agent Framework aplicada a escala de despliegue.

flowchart TB
    subgraph P1[Alojado en el Cliente]
        A1[Proceso de tu Aplicación] --> M1[Proveedor de Modelo]
    end
    subgraph P2[Agente Alojado]
        A2[Cliente Ligero] --> F2[Servicio de Agente Foundry]
        F2 --> M2[Modelo + Herramientas + Almacén de Hilos]
    end
    subgraph P3[Flujo de Trabajo del Agente]
        A3[Orquestador] --> S1[Agente de Clasificación]
        S1 --> S2[Agente Resolutor]
        S2 --> H[Nodo de Aprobación Humana]
        H --> S3[Agente de Acción]
    end

El Ciclo de Vida del Agente en Microsoft Foundry

Desplegar un agente no es un push de una sola vez. Es un ciclo, y se parece mucho a un ciclo de lanzamiento de software porque eso es exactamente lo que es.

flowchart LR
    Create[Crear / Autor] --> Version[Versión]
    Version --> Evaluate[Evaluar sin conexión]
    Evaluate -->|pasa la puerta| Deploy[Desplegar alojado]
    Evaluate -->|falla la puerta| Create
    Deploy --> Observe[Observar en línea]
    Observe --> Improve[Recopilar fallas]
    Improve --> Create
    Deploy --> Retire[Retirar versión antigua]

La idea clave, tomada de la Lección 10: la evaluación offline es una puerta, no un pensamiento posterior. Una nueva versión del agente no se lanza a menos que supere tus umbrales de evaluación. La observabilidad en línea luego alimenta las fallas reales de producción de vuelta a tu conjunto de pruebas offline. Ese es todo el ciclo.

Estrategias de Escalado

Escalar un agente es diferente de escalar una API web sin estado, porque cada petición puede desencadenar múltiples llamadas costosas a modelos y herramientas. Cuatro técnicas llevan la mayor carga.

Manejo de solicitudes sin estado. No mantengas estado por usuario en la memoria de tu proceso. Persiste los hilos de conversación en el almacén de hilos de Foundry o en un servicio de memoria para que cualquier instancia pueda manejar cualquier solicitud. Esto es lo que permite escalar horizontalmente — agrega instancias, sin sesiones pegajosas.

Enrutamiento de modelo. No todas las solicitudes necesitan tu modelo más capaz (y más caro). Enruta solicitudes simples — clasificación de intención, respuestas factuales cortas — a un modelo pequeño y rápido, y reserva el modelo grande para razonamiento genuino. El Model Router de Foundry puede hacer esto por ti, o puedes implementar un clasificador ligero tú mismo. Construirás la versión DIY en el laboratorio.

Caché de respuestas. Muchas consultas de soporte son casi duplicados (“¿cómo restablezco mi contraseña?”). Cachea respuestas a preguntas comunes y sírvelas sin consultar el modelo. Incluso una tasa modesta de aciertos en caché reduce significativamente el costo y la latencia.

Concurrencia y presión inversa. Los proveedores de modelos tienen límites de tasa. Limita tu concurrencia, usa reintentos con retroceso exponencial y falla con gracia (una respuesta en cola de “estamos en ello” es mejor que un 500).

flowchart LR
    Q[Consulta del usuario] --> C{¿Caché hit?}
    C -->|sí| R[Devolver respuesta en caché]
    C -->|no| Router{¿Complejidad?}
    Router -->|simple| SLM[Modelo pequeño]
    Router -->|complejo| LLM[Modelo grande]
    SLM --> Out[Respuesta]
    LLM --> Out
    Out --> Store[Caché + traza]

Observabilidad en Producción

No puedes operar lo que no puedes ver. Como se cubrió en la Lección 10, el Microsoft Agent Framework emite trazas OpenTelemetry de forma nativa — cada llamada a modelo, invocación de herramienta y paso de orquestación se convierte en un span. En producción exportas esos spans a Microsoft Foundry (o a cualquier backend compatible con OTel) para que puedas:

from agent_framework.observability import get_tracer

tracer = get_tracer()

with tracer.start_as_current_span("support_request") as span:
    span.set_attribute("customer.tier", "enterprise")
    span.set_attribute("routed.model", "gpt-5-nano")
    # la ejecución del agente se rastrea automáticamente dentro de este intervalo

Atributos como customer.tier y routed.model son lo que convierte un muro de trazas en preguntas respondibles (“¿los clientes empresariales están siendo enrutados demasiado a menudo al modelo pequeño?”).

Optimización de Costes

El costo en agentes de producción está dominado por tokens. Tres palancas, en orden de impacto:

  1. Tamaño adecuado del modelo. Un modelo pequeño que pase tu puerta de evaluación casi siempre es más barato que uno grande que también pase. Usa la evaluación para probar que el modelo pequeño es lo suficientemente bueno en lugar de optar por el modelo más grande por precaución.
  2. Ruta según complejidad. Como arriba — paga precios de modelo grande solo para solicitudes que necesitan razonamiento de modelo grande.
  3. Cachea agresivamente. La llamada a modelo más barata es la que nunca haces.

Las puertas de evaluación y el control de costos son la misma disciplina vista desde dos ángulos: la evaluación te dice el piso de calidad, el enrutamiento y la caché te mantienen lo más cerca posible del costo de ese piso.

Consideraciones de Despliegue Empresarial

Gobernanza. Los Agentes Hospedados heredan RBAC, seguridad de contenido y registro de auditoría de Foundry. Dale a cada agente una identidad gestionada con los privilegios mínimos que necesita — acceso solo lectura a la base de conocimiento, acceso con ámbito a la API de tickets, nada más.

Humano en el bucle. Algunas acciones son demasiado importantes para automatizar por completo — emitir un reembolso, eliminar una cuenta, escalar a un equipo legal. El Microsoft Agent Framework soporta herramientas de aprobación requerida: el agente propone la acción, la ejecución se pausa, un humano aprueba o rechaza, y el flujo de trabajo continúa. Viste este primitivo en la Lección 6; aquí lo desplegarás.

MCP en producción. MCP permite que tu agente consuma herramientas externas a través de una interfaz estándar. En producción, trata cada servidor MCP como un límite no confiable: fija la versión del servidor, ejecútalo con una identidad con ámbito, valida sus salidas, y nunca le expongas secretos. Un servidor MCP es una dependencia, y las dependencias se parchanean, auditan y limitan cuota.

flowchart TB
    subgraph Dev[Arquitectura de Desarrollo]
        D1[Cuaderno] --> D2[Marco de Agentes]
        D2 --> D3[Proveedor de Modelos]
        D2 --> D4[Herramientas locales]
    end
    subgraph Deploy[Arquitectura de Implementación]
        E1[Pipeline de CI] --> E2[Puerta de evaluación]
        E2 -->|aprobado| E3[Servicio de Agente Foundry]
        E3 --> E4[Agente alojado versionado]
    end
    subgraph Run[Arquitectura en tiempo de ejecución]
        F1[Aplicación cliente] --> F2[Agente alojado]
        F2 --> F3[Enrutador de modelos]
        F2 --> F4[Búsqueda AI de Azure RAG]
        F2 --> F5[Servicio de memoria]
        F2 --> F6[Herramientas MCP]
        F2 --> F7[OTel -> trazado Foundry]
        F2 --> F8[Aprobación humana]
    end

Esos tres diagramas — desarrollo, despliegue, tiempo de ejecución — son el mismo agente en tres etapas de su vida. El laboratorio que sigue te guía a construirlo.

Laboratorio Práctico: Un Agente de Soporte al Cliente Listo para Producción

Abre code_samples/16-python-agent-framework.ipynb y trabájalo de principio a fin. Armarás un agente de soporte al cliente Contoso con todas las preocupaciones de producción cableadas:

  1. Llamada a herramientas — consulta estado de pedidos y abre tickets de soporte.
  2. RAG — responde preguntas de política desde una base de conocimiento (Azure AI Search, con una solución de respaldo en memoria para que el cuaderno funcione sin un recurso Search).
  3. Memoria — recuerda al cliente a través de las vueltas de la conversación.
  4. Enrutamiento de modelo — un clasificador de complejidad enruta cada solicitud a un modelo pequeño o grande.
  5. Caché de respuestas — preguntas repetidas se atienden desde caché.
  6. Aprobación humana — reembolsos sobre un umbral se pausan para aprobación humana.
  7. Canalización de evaluación — un pequeño conjunto de pruebas offline califica al agente y actúa como puerta de lanzamiento.
  8. Observabilidad — trazas OpenTelemetry alrededor de cada solicitud.

Recorrido

El cuaderno está organizado para que cada preocupación de producción sea una sección auto-contenida y ejecutable. El corazón es el manejador de solicitudes con enrutamiento y caché:

async def handle_support_request(query: str, customer_id: str) -> str:
    # 1. Servir desde la caché cuando podamos.
    cached = response_cache.get(normalize(query))
    if cached:
        return cached

    # 2. Enrutar por complejidad para controlar el costo.
    model = "gpt-5-nano" if is_simple(query) else "gpt-5-mini"

    # 3. Ejecutar el agente dentro de un span de traza para la observabilidad.
    with tracer.start_as_current_span("support_request") as span:
        span.set_attribute("routed.model", model)
        span.set_attribute("customer.id", customer_id)
        response = await support_agent.run(query, model=model)

    # 4. Cachear y devolver.
    response_cache.set(normalize(query), response.text)
    return response.text

La puerta de evaluación que protege un lanzamiento es así:

async def evaluation_gate(agent, test_cases, threshold: float = 0.8) -> bool:
    passed = 0
    for case in test_cases:
        result = await agent.run(case["input"])
        if score_response(result.text, case["expected"]) >= 0.8:
            passed += 1
    pass_rate = passed / len(test_cases)
    print(f"Evaluation pass rate: {pass_rate:.0%} (gate: {threshold:.0%})")
    return pass_rate >= threshold  # desplegar solo si la puerta pasa

Lee cada línea — el cuaderno mantiene los primitivas deliberadamente pequeños para que nada esté oculto detrás de una llamada a framework.

Validando un Agente Desplegado con Pruebas de Humo

La puerta de evaluación arriba se ejecuta offline contra tu objeto agente. Una vez que el agente se despliega como un Agente Hospedado, necesitas una más, aún más barata: ¿el endpoint desplegado realmente responde?

Desplegar “con éxito” solo prueba que el plano de control aceptó la definición — no prueba que el agente responda. Una dependencia faltante, un enrutamiento de modelo erróneo o una conexión expirada pueden dejar un despliegue verde que no devuelve nada. Una prueba de humo detecta eso en segundos, en cada despliegue, sin el costo de una evaluación completa.

Este repositorio incluye una canalización de prueba de humo lista para usar construida sobre la Acción de GitHub AI Smoke Test:

- name: Smoke-test hosted agent
  uses: JFolberth/ai-smoketest@v1
  with:
    project_endpoint: $
    agent_name: ContosoSupportAgent
    tests_file: tests/lesson-16-smoke-tests.json

Ejecútalo desde la pestaña Actions una vez que tu agente esté desplegado, proporcionando el endpoint de tu proyecto Foundry y el nombre del agente. La identidad federada necesita el rol Azure AI User con alcance de proyecto Foundry. Piensa en las capas como una pirámide: las pruebas de humo (¿alcanzable y responde?) se ejecutan en cada despliegue, la evaluación offline (¿lo suficientemente bueno para lanzar?) se ejecuta antes de la promoción, y la evaluación online (¿cómo está funcionando en el entorno real?) se realiza continuamente.

Verificación de Conocimiento

Prueba tu comprensión antes de pasar a la tarea.

1. Aproximadamente, ¿qué parte de un agente en producción es “el modelo” y qué es el resto?

Respuesta El modelo es una minoría del sistema — a menudo citado como alrededor del 20%. El resto es el esqueleto operativo: alojamiento y versionado, identidad y RBAC, estado externalizado, gestión de fallos, seguimiento de costos, evaluación y controles humanos en el bucle. Pasar a producción es principalmente construir todo *alrededor* del ciclo de razonamiento.

2. ¿Cuándo elegirías un Agente Hospedado en lugar de un agente hospedado en cliente?

Respuesta Cuando quieres un entorno de ejecución gestionado con durabilidad incorporada (hilos que persisten y pueden reanudarse), observabilidad, seguridad de contenido y RBAC, y estás dispuesto a sacrificar algo de control a bajo nivel del ciclo de razonamiento para tener una menor superficie operativa. El hospedaje en cliente es preferible cuando necesitas control total sobre el ciclo o estás integrando el agente en un backend existente.

3. ¿Por qué un agente escalable debe ser sin estado en la memoria de su propio proceso?

Respuesta Para que cualquier instancia pueda manejar cualquier solicitud, lo que permite la escalabilidad horizontal sin sesiones pegajosas. El estado de la conversación por usuario se externaliza a una tienda de hilos o servicio de memoria. Si el estado residiera en la memoria del proceso, lo perderías al reiniciar y no podrías distribuir la carga libremente.

4. ¿Qué problema resuelve el enrutamiento de modelos y cómo se relaciona con la evaluación?

Respuesta El enrutamiento envía solicitudes simples a un modelo pequeño, barato y rápido, y reserva el modelo grande para razonamientos genuinos, controlando tanto la latencia como el costo. Se relaciona con la evaluación porque esta es lo que *demuestra* que el modelo pequeño es suficientemente bueno para una clase de solicitudes — el enrutamiento sin evaluación es una suposición.

5. ¿Qué es una “puerta de evaluación” y dónde se sitúa en el ciclo de vida?

Respuesta Una puerta de evaluación ejecuta un conjunto de pruebas offline contra una nueva versión del agente y bloquea el despliegue a menos que la tasa de aprobación supere un umbral. Se sitúa entre "versión" y "despliegue" en el ciclo de vida, haciendo de la calidad una condición previa para la liberación en lugar de algo que verificas después de lanzar.

6. ¿Por qué un servidor MCP debe tratarse como un límite no confiable en producción?

Respuesta Porque es una dependencia externa a la que tu agente llama. Debes fijar su versión, ejecutarlo con una identidad restringida, validar sus salidas, limitar su tasa y nunca exponerle secretos — la misma disciplina que aplicas a cualquier dependencia de terceros. Sus salidas fluyen hacia el razonamiento de tu agente, así que confiar sin validar es un riesgo de seguridad.

7. ¿Qué cambio único suele tener el mayor impacto en el costo de un agente en producción, y por qué?

Respuesta Ajustar el tamaño del modelo — usar el modelo más pequeño que aún pase la puerta de evaluación. El costo está dominado por los tokens, y un modelo más pequeño que cumple el nivel de calidad casi siempre es más barato que uno más grande. El almacenamiento en caché y el enrutamiento reducen aún más el costo, pero elegir el modelo base adecuado tiene el mayor efecto en primer orden.

8. ¿Qué papel juegan los atributos de span como customer.tier y routed.model en la observabilidad?

Respuesta Transforman rastreos crudos en preguntas de negocio respondibles. Sin atributos tienes una pared de spans; con ellos puedes preguntar "¿los clientes empresariales están siendo enrutados al modelo pequeño con demasiada frecuencia?" o "¿qué modelo maneja nuestras solicitudes más lentas?" Los atributos son cómo segmentas la telemetría por las dimensiones que importan para tu operación.

Tarea

Toma el agente de soporte al cliente del laboratorio y fortalécelo para un escenario específico: un agente de soporte de facturación por suscripción para una empresa SaaS.

Tu entrega debe:

  1. Reemplazar las herramientas por otras relevantes para facturación: get_subscription_status, get_invoice y issue_credit (los créditos superiores a $50 requieren aprobación humana).
  2. Agregar tres documentos RAG cubriendo la política de reembolso de la empresa, el ciclo de facturación y la política de cancelación.
  3. Extender el conjunto de evaluación a al menos ocho casos, incluyendo al menos dos que deberían activar la vía de aprobación humana, y confirmar que tu puerta de evaluación pasa o falla correctamente.
  4. Agregar un reporte de costos: tras ejecutar diez consultas mixtas a través del agente, imprime cuántas fueron al modelo pequeño, cuántas al modelo grande y cuántas se sirvieron desde caché.

Escribe un párrafo corto (en una celda markdown) explicando qué regla de enrutamiento de modelos elegiste y cómo la validarías con tráfico real. No hay una única respuesta correcta — se te evalúa en función de si las preocupaciones de producción están bien integradas de forma coherente.

Resumen

En esta lección moviste un agente de prototipo a producción con Microsoft Foundry:

La próxima lección toma el camino opuesto: en lugar de escalar agentes en la nube, los llevarás hacia abajo a una única máquina de desarrollo y los ejecutarás completamente de forma local.

Recursos Adicionales

Lección Anterior

Construyendo Agentes para Uso de Computadora (CUA)

Próxima Lección

Creando Agentes AI Locales

Descargo de responsabilidad: Este documento ha sido traducido utilizando el servicio de traducción automática Co-op Translator. Aunque nos esforzamos por la precisión, tenga en cuenta que las traducciones automatizadas pueden contener errores o inexactitudes. El documento original en su idioma nativo debe considerarse la fuente autorizada. Para información crítica, se recomienda una traducción profesional humana. No somos responsables de cualquier malentendido o interpretación errónea que surja del uso de esta traducción.

This site is open source. Improve this page.