Microsoft Agent Framework: Guia Completa 2026

📋 TL;DR

Microsoft Agent Framework permite construir agentes y orquestarlos con workflows tipo grafo, con session state, type-safety, tools y un pipeline de ejecucion pensados para produccion. En esta guia veras como pasar de un agente basico a un sistema multi-paso: herramientas (tools) con option de approval, streaming vs non-streaming, memoria/persistencia via sessions y, cuando toca, workflows con edges y executors. Tambien incluyo hosting practico (ASP.NET Core) y una lista de troubleshooting frecuente. Al final tendras un blueprint aplicable a entornos SRE donde necesitas control explicito y observabilidad.

Tiempo de lectura: ~12-18 minutos

Nivel: Intermedio-Avanzado

—

Introduccion

Si ya has trabajado con agentes LLM y herramientas (function calling) es facil caer en dos problemas clasicos en produccion: (1) la logica de ejecucion queda “dentro del prompt” y (2) el flujo no es controlable ni auditable. Microsoft Agent Framework (en adelante, MAF) ataca esto con una combinacion de abstracciones de agentes y un sistema de workflows basado en grafo. El resultado es un modo de construir sistemas agenticos donde el orden, el handoff y el estado tienen un modelo explicito.

En MAF, un agente puede tomar inputs, decidir invocaciones de tools y devolver respuestas, mientras que un workflow conecta nodos y funciones para procesos con pasos claros. Ademas, la documentacion define mecanismos para session state, memoria/persistencia y middleware/telemetry para observar ejecuciones y tool calls.

En las siguientes secciones aterrizamos todo esto para que puedas:

• construir un primer agente con un provider compatible,
• agregar tools y configurar approval_mode,
• usar streaming cuando la latencia importa,
• modelar un workflow sencillo con edges,
• preparar hosting en ASP.NET Core,
• y migrar desde Semantic Kernel o AutoGen sin romper tu arquitectura.

—

Que es Microsoft Agent Framework (MAF) y por que importa en 2026

Microsoft Agent Framework es un framework open-source para construir soluciones agenticas robustas y “future-proof”. La documentacion lo describe con dos categorias principales de capacidades:

1. Agents: un agente utiliza LLMs para procesar inputs, llamar tools (y, cuando aplique, tools via MCP servers) y generar respuestas.
2. Workflows: un workflow es una orquestacion tipo grafo donde conectas agentes y funciones para tareas multi-paso con routing tipado, checkpointing y soporte human-in-the-loop.

La frase clave para SRE es esta: en vez de tener un “monolito de prompt”, el framework te da una estructura donde la ejecucion es trazable y, sobre todo, controlable. Ademas, la base de integraciones soporta varios providers (por ejemplo, Azure OpenAI, OpenAI, Anthropic, Ollama y mas), y la arquitectura se apoya en conceptos como agent session, context providers y middleware.

Agentes vs workflows: decision rapida para no complicarte

La documentacion lo resume con una regla practica:

• Usa un agent cuando el task sea abierto/conversacional y necesites tool use y decision dinamica.
• Usa un workflow cuando el proceso tenga pasos con orden (o coordinacion multi-agente) y quieras control explicito del flujo.

En un sistema real, ambos se combinan: el workflow define el orden y el agente hace el trabajo “inteligente” dentro de cada nodo.

—

Instalacion y requisitos para Microsoft Agent Framework (Python)

Para Python, la documentacion muestra instalacion via pip con prerelease:

pip install agent-framework --pre

Requisitos recomendados (practicos)

• Python 3.11+
• Un provider compatible (Azure OpenAI Responses, OpenAI, Anthropic, Ollama, etc.)
• Variables de entorno con endpoints/deployment names segun tu provider
• Dependencias extra para integraciones locales (p. ej. python-dotenv si quieres cargar .env)

Primer agente (non-streaming) en Python

La guia “Your First Agent” y los ejemplos de la overview describen el patron general: creas un client para el provider, formas un agente con instrucciones, y ejecutas agent.run(...).

import os
import asyncio

from azure.identity import AzureCliCredential
from agent_framework.azure import AzureOpenAIResponsesClient


async def main():
    project_endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
    deployment_name = os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"]

    credential = AzureCliCredential()
    client = AzureOpenAIResponsesClient(
        project_endpoint=project_endpoint,
        deployment_name=deployment_name,
        credential=credential,
    )

    agent = client.as_agent(
        name="HelloAgent",
        instructions="You are a friendly assistant. Keep your answers brief.",
    )

    result = await agent.run("What is the capital of France?")
    print(f"Agent: {result.text}")


if __name__ == "__main__":
    asyncio.run(main())

Nota SRE: si tu servicio requiere configuracion segura, la documentacion menciona que el framework no carga .env automaticamente; debes cargarlo tu (por ejemplo con load_dotenv() al inicio) o setear variables en el shell/IDE.

—

Tools en Microsoft Agent Framework: function tools, tool approval y MCP

En MAF, “tools” son funciones que el agente puede invocar cuando ayudan a resolver el objetivo. La guia “Add Tools” define herramientas como metodos tipados con descripciones. En Python se usa el decorador @tool y se apoyan en inferencia de schema.

Tool approval en Microsoft Agent Framework (approval_mode)

La documentacion de tool approval explica approval_mode:

• always_require: el tool siempre requiere aprobacion.
• never_require: el tool nunca requiere aprobacion.
• (Tambien hay modos especificos para marcar solo ciertas tools con una regla.)

Esta capa es oro para operaciones: puedes dejar que el agente “piense” y use tools, pero obligar confirmacion cuando la tool sea de riesgo (p. ej. escribir datos, ejecutar acciones, o disparar operaciones contra sistemas externos).

Tool de ejemplo en Python (con tipos)

from typing import Annotated
from random import randint

from pydantic import Field
from agent_framework import tool


@tool(approval_mode="always_require")
def get_homelab_metric(
    metric_name: Annotated[
        str,
        Field(description="Nombre del metric, por ejemplo: cpu, ram, disk.")
    ]
) -> str:
    """
    Demo tool: en un articulo real, consultarias Prometheus/Grafana/LOKI o un endpoint interno.
    """
    m = metric_name.strip().lower()
    value = randint(1, 100)
    return f"{m} simulated value: {value}"

Agent usando tools

La overview y la guia “Add Tools” describen el patron: creas el agente con instrucciones y herramientas. En un servicio real, este punto es donde defines “quien puede llamar a que”.

—

Streaming y ejecucion: non-streaming vs stream en Microsoft Agent Framework

La documentacion de “Running Agents” explica que MAF soporta:

• non-streaming: agent.run(...) devuelve una respuesta completa
• streaming: iteras el resultado con async for ... usando stream=True

Tambien explica el pattern de response.text como una forma conveniente de acceder al texto agregado.

Ejemplo de streaming (Python)

import asyncio


async def run_stream(agent):
    print("Agent (streaming): ", end="", flush=True)
    async for chunk in agent.run(
        "Tell me a short plan for a homelab incident response. Use tools if needed.",
        stream=True,
    ):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print()

Por que importa en SRE: el streaming te permite empezar a ver progreso (y, si tu frontend o logs lo soportan, puedes reflejar avances parciales) y reducir la percepcion de latencia.

—

Memoria y persistencia: session state y context providers en Microsoft Agent Framework

La guia “Memory & Persistence” separa dos ideas:

• historial/almacenamiento de chat (history providers)
• contexto/instrucciones por run (context providers)
• estado persistido asociado a una session (AgentSession)

En vez de “inyectar memoria via prompt” de forma artesanal, la documentacion propone usar session state para mantener informacion entre ejecuciones. Esto es especialmente util cuando un workflow orquesta varios pasos y necesita consistencia.

Patron con session (Python)

async def run_with_session(agent):
    session = agent.create_session()

    await agent.run("My name is Alice.", session=session)
    result = await agent.run(
        "What is my name? Then propose a next action.",
        session=session,
    )

    print(result.text)

Context provider (idea aplicada)

La guia explica que puedes definir un BaseContextProvider que:

• lee estado (por ejemplo, state["user_name"])
• extiende instrucciones antes del run
• y luego actualiza ese estado despues del run.

En la practica, ese patron te permite implementar:

• preferencias por usuario,
• memoria operativa (p. ej. “este servicio es el principal”),
• o restricciones (p. ej. “siempre usar snapshot antes de cambios”).

—

Microsoft Agent Framework con workflows: edges, executors y multi-agente

Cuando tu proceso tiene estructura, el workflow te da una orquestacion explicita tipo grafo. La guia de workflows describe:

• definir executors (clases o funciones) con handler
• conectar nodos con edges
• ejecutar el workflow y recuperar outputs/final state

Workflow sencillo (executor + edges)

La documentacion incluye un ejemplo de workflow donde un executor transforma input y otro executor produce salida. Aqui aplicamos la idea con dos nodos: uno convierte a mayusculas y otro revierte el string.

from agent_framework.workflows import WorkflowBuilder, Executor, handler
from typing import Never


class UpperCase(Executor):
    def __init__(self, id: str):
        super().__init__(id=id)

    @handler
    async def to_upper_case(self, text: str, ctx) -> None:
        await ctx.send_message(text.upper())


async def reverse_text(text: str, ctx) -> None:
    await ctx.yield_output(text[::-1])


def create_workflow():
    upper = UpperCase(id="upper_case")
    return WorkflowBuilder(start_executor=upper).add_edge(upper, reverse_text).build()

Tabla: cuando usar agents vs workflows (en la practica)

—

Providers, integraciones y hosting productivo

MAF se apoya en “model clients” y un conjunto de integraciones para providers. En el enfoque de hosting, la documentacion (“Host Your Agent”) lista opciones de exposicion:

• A2A Protocol (multi-agent)
• OpenAI-compatible endpoints
• Azure Functions (durable, para tareas largas)
• AG-UI Protocol (para interfaces web)

Tambien documenta hosting en ASP.NET Core usando la libreria base Microsoft.Agents.AI.Hosting:

• registrar un IChatClient en DI
• registrar agentes via builder.AddAIAgent(...)
• configurar session store
• y construir workflows (y luego exponerlos como agent si lo necesitas)

Ejemplo de hosting en ASP.NET Core (C# skeleton)

using System;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting;

var builder = WebApplication.CreateBuilder(args);

// 1) Registrar un IChatClient (ejemplo Azure OpenAI)
// endpoint y deployment segun tu entorno
var endpoint = new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!);
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

builder.Services.AddSingleton<IChatClient>(sp =>
    new AzureOpenAIClient(endpoint, new DefaultAzureCredential())
        .GetChatClient(deploymentName)
        .AsIChatClient()
);

// 2) Registrar un agente
builder.AddAIAgent("pirate", instructions: "Speak like a pirate");

var app = builder.Build();
app.Run();

Idea SRE: aunque el snippet simplifique, la idea es clara: el agente vive dentro de tu infraestructura (DI, logging, configuracion) y lo expones con un adaptador de protocolo.

—

Seguridad, costes y observabilidad en Microsoft Agent Framework

En un pipeline real, el framework no es solo “poner un LLM”. Para entornos SRE necesitas:

• governance de tool calls
• limites de ejecucion (tiempos, retries)
• trazabilidad (latencia y herramientas)
• y control de session state

Observabilidad: pipeline y middleware/telemetry

La documentacion de middleware/agent pipeline indica que la arquitectura se compone por capas, incluyendo middleware y una capa de telemetry/instrumentacion. Esto permite:

• emitir spans o eventos por etapa,
• medir tool invocation,
• y conectar la ejecucion con una session.

En la practica, el articulo recomienda instrumentar para depurar (por ejemplo: por que se invoco una tool, que inputs tuvo, y que resultado devolvio).

Si en tu entorno ya usas Grafana y Prometheus (o similares), puedes conectar esas trazas con tus dashboards: la clave es que los eventos por tool call no se queden “solo en logs”, sino que se traduzcan a metricas/alertas que uses como SRE.

Tabla: practicas de seguridad para tool use

—

Migracion desde Semantic Kernel y AutoGen a Microsoft Agent Framework

Si vienes de Semantic Kernel o AutoGen, la migracion es un tema recurrente. La documentacion del migration guide enfatiza:

• cambios de namespaces (Semantic Kernel hacia Microsoft.Agents.AI)
• simplificacion de creacion de agentes usando provider extensions (por ejemplo, chatClient.AsAIAgent(...))
• manejo explicito de session/state desde el agente

La migracion desde AutoGen complementa con:

• adaptar patrones de agentes multi-agent,
• y aprovechar workflows/graph-based orchestration para replicar flujos existentes.

Checklist de migracion (practico, para SRE)

1. Inventario de tus agents existentes y sus tools.
2. Mapeo de tools a function tools (y decidir approval_mode segun riesgo).
3. Mapeo de memoria: que era thread/history vs que sera session + context providers.
4. Redisenar el flujo: si hay orden explicito, moverlo a workflows y edges.
5. Instrumentacion: asegurate de medir tool calls y errores por nodo.
6. Pruebas: compara outputs con tus tests actuales (aceptar diffs por cambios de modelo/formatos).

—

Troubleshooting comun en Microsoft Agent Framework

Error 1: KeyError en variables de entorno (AZURE_* missing)

Sintomas: falla al crear el client/proveedor.

Causa posible: no se setean AZURE_AI_PROJECT_ENDPOINT y/o AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME.

Solucion:

# Ejemplo: setea variables antes de ejecutar el demo
export AZURE_AI_PROJECT_ENDPOINT="https://<tu-endpoint>"
export AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME="gpt-4o-mini"

python -u src/python_agent_app/app.py

Error 2: streaming devuelve texto vacio o no aparece

Sintomas: el async for chunk in agent.run(..., stream=True) no imprime nada.

Causas posibles:

• el chunk no contiene text (puede contener otros content types)
• o el provider devuelve respuesta en un formato distinto.

Solucion (pattern):

async def stream_debug(agent):
    async for chunk in agent.run("consulta", stream=True):
        if getattr(chunk, "text", None):
            print(chunk.text, end="", flush=True)

Error 3: tool approval bloquea ejecucion

Sintomas: el workflow/agent se queda esperando aprobacion o la tool no se ejecuta.

Causas posibles: configuraste approval_mode="always_require" o una regla equivalente para esa tool.

Solucion:

• cambia el approval_mode en herramientas segun riesgo (solo las de write con always_require)
• agrega un canal de aprobacion en tu UI o tu capa de orquestacion.

Error 4: workflow edges no producen output esperado

Sintomas: el workflow final state no tiene outputs o la salida es incompleta.

Causas posibles: executor handler no llama a ctx.send_message(...) o ctx.yield_output(...) como en el ejemplo.

Solucion:

Revisa tu executor: en los patrones de la documentacion, cada nodo debe emitir mensajes/salida al contexto.

Error 5: memoria/persistencia inconsistente entre runs

Sintomas: el agente “olvida” el dato que esperabas que persistiera.

Causas posibles: no pasaste la session al run, o configuraste mal context/history providers.

Solucion:

• usa session en todas las ejecuciones que dependen de estado
• implementa context providers con lecturas/escrituras en state consistentes

—

Comparativa tecnica: Microsoft Agent Framework vs alternatives de agentes

No existe una unica alternativa “perfecta”, pero para decidir bien necesitas comparar por arquitectura.

Tabla: decision de arquitectura (MAF vs approaches previos)

Recomendacion rapida

• Si necesitas control de orden, edges, y una estructura clara para audit/observabilidad: MAF con workflows.
• Si tu problema es mas conversacional y te basta tool use con un agente: MAF con agents y tools.
• Si vienes de SK/AutoGen: migrar siguiendo la documentacion y validando tests por etapas.

—

📦 Descargar Ejemplos

Los ejemplos (Python y .NET) de este articulo estan en:

👉 Descargar ejemplos de Microsoft Agent Framework

Incluye:

• docker-compose.yml para ejecutar el demo Python
• src/python_agent_app/ con ejemplo de agente, tool y session
• src/dotnet_agent_app/ con skeleton .NET

—

🔗 Artículos Relacionados

Continúa aprendiendo con estas guías complementarias:

MCP (Model Context Protocol): Guía Completa para Conectar Herramientas con IA (2026)

MCP Model Context Protocol: conecta Cursor, Claude y ChatGPT con datos y herramientas. Guía paso a p…

AutoGPT: Agentes Autónomos con Auto-Loop | Guía Completa 2026

Descubre AutoGPT: el framework original de agentes autónomos con auto-loop. Instalación, configuraci…

Mem0: Memoria Persistente para Agentes de IA (Guía Completa 2026)

Implementa memoria persistente para agentes de IA con Mem0. Guía completa con Docker, integración Ol…

Immich Avanzado: Migración desde Google Photos, External Libraries y Optimización Profesional (Guía Completa 2026)

Migra desde Google Photos sin perder datos, configura external libraries para integrar fotos existen…

Memoria de Agentes de IA: Persistencia y Contexto para Sistemas Agénticos (Guía Completa 2025)

Implementa memoria en agentes de IA con LangChain y CrewAI: Buffer, Summary, Entity y Vector Memory….

OpenAI Agents SDK: Multi-Agent en Python (Guía 2026)

Monta flujos multi-agente con OpenAI Agents SDK en Python. Handoffs, agents-as-tools, MCP y Ollama. …

AutoGen: Multi-Agent en Homelab con Ollama (Guía 2026)

Monta Microsoft AutoGen en tu homelab: agentes conversacionales multi-agente con AutoGen Studio y Ol…

LangChain vs LlamaIndex: Framework RAG para Homelab (Guía Comparativa 2025)

Comparativa técnica completa entre LangChain y LlamaIndex para RAG en homelabs. Benchmarks reales, e…

🔗 Artículos Relacionados

Continúa aprendiendo con estas guías complementarias:

Memoria de Agentes de IA: Persistencia y Contexto para Sistemas Agénticos (Guía Completa 2025)

Implementa memoria en agentes de IA con LangChain y CrewAI: Buffer, Summary, Entity y Vector Memory….

Mem0: Memoria Persistente para Agentes de IA (Guía Completa 2026)

Implementa memoria persistente para agentes de IA con Mem0. Guía completa con Docker, integración Ol…

Immich Avanzado: Migración desde Google Photos, External Libraries y Optimización Profesional (Guía Completa 2026)

Migra desde Google Photos sin perder datos, configura external libraries para integrar fotos existen…

OpenAI Agents SDK: Multi-Agent en Python (Guía 2026)

Monta flujos multi-agente con OpenAI Agents SDK en Python. Handoffs, agents-as-tools, MCP y Ollama. …

AutoGen: Multi-Agent en Homelab con Ollama (Guía 2026)

Monta Microsoft AutoGen en tu homelab: agentes conversacionales multi-agente con AutoGen Studio y Ol…

AutoGPT: Agentes Autónomos con Auto-Loop | Guía Completa 2026

Descubre AutoGPT: el framework original de agentes autónomos con auto-loop. Instalación, configuraci…

LangGraph para Agents: Construye IA Agéntica con State Machines (Guía Práctica 2025)

Guía completa de LangGraph: construye AI agents con state machines, workflows complejos y control de…

MCP (Model Context Protocol): Guía Completa para Conectar Herramientas con IA (2026)

MCP Model Context Protocol: conecta Cursor, Claude y ChatGPT con datos y herramientas. Guía paso a p…

Preguntas Frecuentes

¿Que es Microsoft Agent Framework y para que sirve en un stack SRE?

Microsoft Agent Framework es un framework para construir agentes y workflows con ejecucion controlada, session state, tools y mecanismos de middleware/telemetry. En un stack SRE sirve para pasar de “prompt-driven automation” a una arquitectura donde puedes auditar tool calls y estructurar pasos con edges.

¿Microsoft Agent Framework reemplaza a Semantic Kernel y AutoGen?

La documentacion lo presenta como sucesor directo que combina patrones de AutoGen (abstracciones de agentes) con capacidades enterprise de Semantic Kernel (session-based state, type-safety y features de integracion). La migracion se apoya en guias especificas para cada ecosistema.

¿Como configurar tool approval en Microsoft Agent Framework?

La guia de tool approval describe approval_mode con always_require y never_require. Para herramientas con riesgo (write o acciones), usa always_require y gestiona el approval en tu capa de aplicacion/UI. Para herramientas de solo lectura o deterministicas, puedes usar never_require.

¿Se puede usar streaming con Microsoft Agent Framework?

Si. La guia “Running Agents” describe streaming con agent.run(..., stream=True) y patrones de async for. El framework permite consumir chunks de respuesta y usar chunk.text cuando exista.

¿Como funciona la memoria persistente (session) en Microsoft Agent Framework?

La documentacion de memory & persistence explica que el estado entre runs se maneja con session state y providers de contexto/historial. Pasando la session al run puedes conservar datos y personalizacion; el detalle depende del provider configurado.

¿Que problema resuelve un workflow en vez de un agente?

Un workflow define explicitamente el orden y la coordinacion de nodos (edges) y permite una orquestacion mas auditable. Si el proceso tiene pasos claros o coordinacion multi-funcion, el workflow reduce ambiguedad frente a una conversacion abierta.

¿Cuando conviene usar Hosted MCP tools con Microsoft Agent Framework?

Conviene cuando necesitas conectar un agent con herramientas remotas expuestas por MCP servers (por ejemplo en entornos tipo Foundry) y quieres que la integracion sea gestionada por el servicio. La documentacion cubre como definir herramientas MCP y sus allowed tools, junto con approval.

¿Como se migra un proyecto de AutoGen a Microsoft Agent Framework?

La documentacion de migration desde AutoGen describe como adaptar patrones de agentes multi-agent a la arquitectura de MAF y como aprovechar workflows/graph-based orchestration para replicar flujos. La recomendacion general es migrar por capas: agents -> tools -> orquestacion.

¿Que tipos de hosting soporta Microsoft Agent Framework?

La guia de hosting enumera opciones como A2A Protocol, endpoints compatibles con OpenAI, Azure Functions (durable) y AG-UI. Tambien hay ejemplos de hosting en ASP.NET Core registrando agentes y workflows con librerias de Microsoft.Agents.AI.Hosting.

¿Microsoft Agent Framework sirve para integrar herramientas externas con MCP?

Si. La documentacion de hosted MCP tools explica como conectar un agent con herramientas remotas mediante un MCP server y configurar que tools pueden ejecutarse, incluyendo mecanismos de approval.

¿Cuales son errores comunes al ejecutar Microsoft Agent Framework en local?

Los mas frecuentes son configuracion de variables de entorno faltantes, confusion sobre streaming vs non-streaming (o content types en chunks), y bloqueo por tool approval. Tambien aparecen problemas cuando los ejecutors de workflows no emiten output usando el patron del executor.

¿Como preparo un checklist de seguridad para herramientas en Microsoft Agent Framework?

Una estrategia practicamente util es: (1) clasifica tools por riesgo (read vs write), (2) aplica approval_mode segun riesgo, (3) instrumenta tool calls para trazabilidad, (4) define claramente session/state y valida inputs antes de ejecutar tools, y (5) revisa gobernanza de datos con providers externos.

—

Conclusión

Microsoft Agent Framework te da una base coherente para construir sistemas agenticos con control explicito: agents para decision y tool use, workflows para orden de ejecucion, session state para persistencia y middleware/telemetry para observabilidad. Si tu objetivo es pasar de experimentos a sistemas operables, la combinacion de edges + approval_mode + session state es el “triple” que mas suele marcar la diferencia.

Si vas a iniciar hoy: toma un agente basico con una tool de ejemplo, suma session state para mantener contexto y luego mueve el flujo a un workflow cuando detectes pasos con orden. Con eso, ya tienes un camino realista para implementar Microsoft Agent Framework en 2026.