De tu primer ChatAgent con Microsoft Agent Framework, hasta un workflow multi-agente en producción sobre Microsoft Foundry, con balanceo de carga.
0 / 10 completado
Nivel 1 · Fundamentos
Tu primer ChatAgent
Objetivo: instalar Microsoft Agent Framework y crear tu primer agente conectado a un modelo alojado en Microsoft Foundry.
Microsoft Agent Framework (GA desde abril de 2026) es la convergencia oficial de Semantic Kernel y AutoGen en un solo SDK de producción, disponible en Python y .NET. ChatAgent es su abstracción principal: un agente que usa un "chat client" para hablar con cualquier modelo, incluyendo los desplegados en Microsoft Foundry.
1. Instala las dependencias
TERMINAL
pip install agent-framework agent-framework-azure-ai azure-identity
az login # autenticación contra tu suscripción de Azure
2. Tu primer agente
agente.py
import asyncio
from agent_framework import ChatAgent
from agent_framework.azure import AzureAIAgentClient
from azure.identity.aio import DefaultAzureCredential
async def main():
async with DefaultAzureCredential() as cred:
async with ChatAgent(
chat_client=AzureAIAgentClient(async_credential=cred),
name="asistente",
instructions="Respondé de forma breve y clara.",
) as agent:
respuesta = await agent.run("¿Qué es un agente de IA, en una frase?")
print(respuesta.text)
asyncio.run(main())
AzureAIAgentClient conecta directo con un proyecto de Microsoft Foundry — el modelo, la autenticación y el endpoint ya están gestionados del lado de Azure, vos solo referenciás el proyecto.
Reto
Corré el mismo agente con agent-framework devui para inspeccionar la ejecución en el debugger visual local.
Nivel 2 · Personalidad
Instructions y parámetros del modelo
Objetivo: controlar el comportamiento del agente con instructions y parámetros de generación.
agente.py
agent = ChatAgent(
chat_client=AzureAIAgentClient(async_credential=cred),
name="soporte",
instructions=(
"Sos un asistente técnico de soporte. Respondé en español, "
"breve y con pasos numerados. Si no sabés algo, decilo."
),
temperature=0.3,
max_tokens=400,
)
respuesta = await agent.run("La app se cierra al abrir la cámara")
Los parámetros temperature y max_tokens se pasan directo al ChatAgent, sin necesidad de configurar un objeto de modelo aparte.
Reto
Escribí instrucciones para un agente que solo responde sobre un dominio específico y rechaza cortésmente cualquier otra pregunta.
Nivel 3 · Herramientas
Tools: funciones Python normales
Objetivo: darle herramientas al agente pasando funciones Python directamente en tools.
agente.py
def clima_actual(location: str) -> str:
"""Devuelve el clima actual reportado para una ubicación dada."""
datos = {"Ciudad de Guatemala": "22°C, parcialmente nublado"}
return datos.get(location, "sin datos para esa ubicación")
agent = ChatAgent(
chat_client=AzureAIAgentClient(async_credential=cred),
name="asistente-clima",
instructions="Ayudás a consultar el clima de ciudades.",
tools=clima_actual, # también acepta una lista: tools=[clima_actual, otra_tool]
)
respuesta = await agent.run("¿Cómo está el clima en Ciudad de Guatemala?")
Igual que en otros frameworks modernos, el docstring y los type hints de la función son lo que el modelo usa para decidir cuándo y cómo llamarla — no hace falta declarar un schema JSON a mano.
Reto
Agregá HostedCodeInterpreterTool() a la lista de tools y pedile al agente que calcule estadísticas básicas de una lista de números.
Nivel 4 · Memoria
Threads: memoria conversacional
Objetivo: mantener contexto entre turnos usando un thread de conversación explícito.
En Agent Framework, cada conversación con estado vive en un thread — lo creás una vez y se lo pasás a cada llamada de agent.run() para que el agente recuerde los turnos anteriores.
chat_con_memoria.py
thread = agent.get_new_thread()
r1 = await agent.run("Busco una laptop para diseño gráfico", thread=thread)
r2 = await agent.run("¿Cuál es la más barata de las que me mencionaste?", thread=thread)
print(r2.text) # el agente recuerda las laptops mencionadas en r1
Cada thread es independiente — es lo que te permite atender a varios usuarios en paralelo con el mismo objeto agent, simplemente creando un thread distinto por usuario o sesión.
Reto
Simulá dos usuarios distintos con dos threads separados y confirmá que sus conversaciones no se mezclan entre sí.
Nivel 5 · Salida estructurada
Respuestas tipadas con Pydantic
Objetivo: forzar que el agente devuelva un objeto validado en vez de texto libre.
agente.py
from pydantic import BaseModel
class TicketSoporte(BaseModel):
categoria: str
urgencia: str
resumen: str
agent = ChatAgent(
chat_client=AzureAIAgentClient(async_credential=cred),
name="clasificador",
instructions="Clasificá el ticket de soporte que te llega.",
response_format=TicketSoporte,
)
resultado = await agent.run("Se cierra la app al subir foto de perfil, es urgente")
ticket: TicketSoporte = resultado.value
print(ticket.categoria, ticket.urgencia, ticket.resumen)
Reto
Definí un modelo Pydantic para extraer rating, sentimiento y si menciona un problema específico de una reseña de producto.
Nivel 6 · Streaming
run_stream para respuestas en vivo
Objetivo: mostrar la respuesta del agente en tiempo real, token por token.
stream.py
async for actualizacion in agent.run_stream("Explicame qué es RAG en 3 pasos", thread=thread):
if actualizacion.text:
print(actualizacion.text, end="", flush=True)
ChatAgent soporta tanto respuestas streaming como no-streaming con la misma API base — cambiás run() por run_stream() sin reestructurar el resto del código.
Reto
Envolvé run_stream en un endpoint de FastAPI con StreamingResponse para un chat en vivo.
Nivel 7 · Multi-agente
Varios ChatAgents especializados
Objetivo: crear agentes especializados independientes como paso previo a orquestarlos.
Antes de armar un workflow completo, el primer paso multi-agente es simplemente tener varios ChatAgent con instrucciones distintas, cada uno bueno en una sola cosa — la composición entre ellos la vas a resolver con un workflow en el próximo nivel.
especialistas.py
agente_ventas = ChatAgent(
chat_client=AzureAIAgentClient(async_credential=cred),
name="ventas",
instructions="Especialista en preguntas de precios y productos.",
)
agente_soporte = ChatAgent(
chat_client=AzureAIAgentClient(async_credential=cred),
name="soporte",
instructions="Especialista en errores técnicos y bugs.",
)
# Un agente puede usar a otro como tool, igual que en otros frameworks:
async def consultar_ventas(pregunta: str) -> str:
"""Delegar una pregunta de ventas al especialista de ventas."""
r = await agente_ventas.run(pregunta)
return r.text
Reto
Agregá consultar_ventas como tool de un tercer agente "recepción" y confirmá que delega correctamente.
Nivel 8 · Orquestador
Workflows: orquestación basada en grafos
Objetivo: construir un orquestador explícito con WorkflowBuilder, el sistema de workflows basado en grafos de Agent Framework.
Para orquestación multi-agente predecible en producción, Agent Framework aporta workflows basados en grafos — heredados del lado "Semantic Kernel" de la fusión — donde cada agente es un nodo y las aristas definen el flujo de datos entre ellos, con patrones ya soportados para orquestación secuencial, concurrente y por handoff.
orquestador.py
from agent_framework import WorkflowBuilder
supervisor = ChatAgent(
chat_client=AzureAIAgentClient(async_credential=cred),
name="supervisor",
instructions="Analizá el mensaje y decidí a qué especialista enviarlo.",
)
workflow = (
WorkflowBuilder()
.add_node(supervisor)
.add_node(agente_ventas)
.add_node(agente_soporte)
.add_edge(supervisor, agente_ventas, condition=lambda r: "precio" in r.text.lower())
.add_edge(supervisor, agente_soporte, condition=lambda r: "error" in r.text.lower())
.set_start(supervisor)
.build()
)
resultado = await workflow.run("Me cobraron dos veces la suscripción")
Esto te da control explícito y trazable sobre el ruteo (a diferencia de dejar que un solo agente "decida solo" con tools) — clave cuando necesitás auditar por qué el sistema tomó cada decisión.
Reto
Agregá un tercer nodo de facturación con su propia condición de ruteo, y probá un mensaje ambiguo para ver cómo se resuelve el desempate.
Nivel 9 · Producción
DevUI, telemetría y guardrails
Objetivo: depurar visualmente el workflow y trazar su ejecución con OpenTelemetry.
TERMINAL
agent-framework devui
# Debugger local en el navegador: muestra traces de ejecución,
# flujo de mensajes entre agentes, tool calls y decisiones de ruteo en tiempo real
Telemetría nativa vía OpenTelemetry — cada paso del workflow, cada tool call, queda trazado y exportable a tu backend de observabilidad
Middleware de Semantic Kernel heredado: podés interceptar cada llamada al modelo para logging, rate limiting o validación de contenido
State management con tipado fuerte — el estado que fluye entre nodos del workflow está validado, no es un diccionario libre
Reto
Agregá un middleware que registre en un log estructurado cuánto tardó cada nodo del workflow del Nivel 8 en responder.
Nivel 10 · Arquitectura final
Microsoft Foundry Agent Service + balanceo de carga
Objetivo: desplegar el workflow como agentes hospedados en Microsoft Foundry, escalados y balanceados.
Microsoft Foundry Agent Service es la capa hospedada de Azure para correr agentes en producción sin administrar tu propia infraestructura de cómputo — pero cuando necesitás controlar el escalado horizontal vos mismo (por ejemplo, para workflows con lógica custom del Nivel 8), lo hospedás en Azure Container Apps o App Service detrás de un load balancer.
Con esto tenés el camino completo: de un ChatAgent de pocas líneas en el Nivel 1, a un workflow multi-agente en producción sobre Azure, con colas, réplicas balanceadas y telemetría de punta a punta.
Reto final
Empaquetá el especialista de soporte del Nivel 7 como contenedor, desplegalo con 2 réplicas en Azure Container Apps, y ponelo detrás de Application Gateway.