AgentApplication en SDK de agentes de Microsoft 365

AgentApplication es el bloque de creación central de un agente compilado con el SDK de agentes. AgentApplication es el punto de entrada de toda la actividad entrante, incluidos los mensajes de los usuarios, los eventos del ciclo de vida de la conversación, las interacciones de tarjetas adaptativas, las devoluciones de llamada de OAuth.

Un agente es, en esencia, un AgentApplication. Se configura con controladores que describen lo que hace su agente. El SDK se encarga del enrutamiento, la gestión del estado y la infraestructura necesaria para ejecutarlo.

Cómo funciona AgentApplication

Cada agente tiene un ciclo de vida que comienza cuando un canal (Microsoft Teams, un Bot Service o un cliente personalizado) entrega una actividad al punto final de tu agente. AgentApplication está en el centro de ese ciclo de vida:

Channel → Hosting layer → AgentApplication → Your handlers

Las capas de procesamiento en un agente construido con el SDK de Agentes funcionan de la siguiente manera:

La capa de alojamiento recibe la solicitud HTTP y la autentica.
El AgentApplication procesa la actividad entrante a través de su flujo de procesamiento.
Se llama a los controladores en función de las rutas coincidentes.

El agente carga el estado de turno antes de que se ejecuten los controladores. Después, el agente guarda el estado del turno.

Conceptos principales

Actividades

Todo en el SDK de agentes fluye como una actividad. Una actividad es un mensaje estructurado que representa algo que ocurrió. Una actividad tiene un tipo, como mensaje, evento, invocar, conversationUpdate, entre otros. Lleva una carga útil relevante para ese tipo. AgentApplication recibe actividades y las enruta al controlador adecuado.

Rutas

Una ruta empareja un selector con un controlador. El selector determina si una ruta coincide con la actividad actual. El controlador ejecuta la lógica cuando la ruta coincide.

Registra rutas cuando configures tu agente. Pueden coincidir con:

Un mensaje que contiene texto específico o que coincide con una expresión regular
Cualquier actividad de un tipo específico
Eventos del ciclo de vida de la conversación (miembro añadido, miembro eliminado)
Acciones de la tarjeta adaptable
Condiciones personalizadas

Cuando llega una actividad, el sistema evalúa las rutas en orden hasta que encuentra una coincidencia. Por defecto, solo se ejecuta una ruta.

Estado de turno

AgentApplication gestiona _turn estado—almacenamiento estructurado particionado en ámbitos:

Tipo de ámbito	Description
Conversación	Compartido para todos los usuarios de una conversación, guardado entre turnos
Usuario	Limitado a un usuario individual en todas las conversaciones
Temperatura	Solo turno actual: nunca se conserva

El sistema carga automáticamente el estado antes de que los controladores se ejecuten y lo guarde automáticamente después.

Contexto de turno

Cuando un controlador se ejecuta, recibe un contexto de turno. El contexto de turno es una instantánea de la actividad actual, la conexión del adaptador y las utilidades para enviar respuestas. El contexto del turno es tu interfaz con la interacción actual.

Middleware

AgentApplication admite una canalización de middleware. El middleware es una cadena de componentes que procesan cada turno antes y después de que se ejecuten los controladores. El middleware puede inspeccionar, transformar o cortocircuitar el flujo de actividad. Los usos comunes incluyen el registro de actividades, comprobaciones de autenticación y la normalización de solicitudes.

Crear un agente

Subclasifique AgentApplication y registre los controladores en el constructor. El marco de hosting inyecta automáticamente AgentApplicationOptions.

public class MyAgent : AgentApplication
{
    public MyAgent(AgentApplicationOptions options) : base(options)
    {
        OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeAsync);
        OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
    }

    private async Task WelcomeAsync(ITurnContext context, ITurnState state, CancellationToken ct)
    {
        foreach (var member in context.Activity.MembersAdded)
        {
            if (member.Id != context.Activity.Recipient.Id)
            {
                await context.SendActivityAsync("Hello! How can I help you?", cancellationToken: ct);
            }
        }
    }

    private async Task OnMessageAsync(ITurnContext context, ITurnState state, CancellationToken ct)
    {
        await context.SendActivityAsync($"You said: {context.Activity.Text}", cancellationToken: ct);
    }
}

Registre el agente en Program.cs:

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient();
builder.Services.AddSingleton<IStorage, MemoryStorage>();
builder.Services.AddAgent<MyAgent>();
builder.Services.AddAgentAspNetAuthentication(builder.Configuration);

WebApplication app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
app.MapAgentApplicationEndpoints(requireAuth: !app.Environment.IsDevelopment());

app.Run();

Instancie AgentApplication y registre los controladores en la instancia usando la API fluida. Para iniciar el servidor, llame a startServer desde el paquete de hosting Express.

import { AgentApplication, MemoryStorage, TurnContext, TurnState } from '@microsoft/agents-hosting'
import { startServer } from '@microsoft/agents-hosting-express'

const app = new AgentApplication<TurnState>({ storage: new MemoryStorage() })

app.onConversationUpdate('membersAdded', async (context: TurnContext) => {
    await context.sendActivity('Hello! How can I help you?')
})

app.onActivity('message', async (context: TurnContext, state: TurnState) => {
    await context.sendActivity(`You said: ${context.activity.text}`)
})

startServer(app)

Para la configuración manual de Express sin startServer:

import express from 'express'
import { CloudAdapter, authorizeJWT, AuthConfiguration } from '@microsoft/agents-hosting'

const authConfig: AuthConfiguration = loadAuthConfigFromEnv()
const adapter = new CloudAdapter(authConfig)
const expressApp = express()

expressApp.use(express.json())
expressApp.use(authorizeJWT(authConfig))

expressApp.post('/api/messages', async (req, res) => {
    await adapter.process(req, res, async (context) => {
        await app.run(context)
    })
})

Instancie AgentApplication con un parámetro de tipo y registre controladores usando decoradores.

from microsoft_agents.hosting.core import AgentApplication, TurnState, TurnContext, MemoryStorage
from microsoft_agents.hosting.aiohttp import CloudAdapter, start_agent_process
from aiohttp.web import Request, Response, Application, run_app

AGENT_APP = AgentApplication[TurnState](
    storage=MemoryStorage(),
    adapter=CloudAdapter()
)

@AGENT_APP.conversation_update("membersAdded")
async def on_members_added(context: TurnContext, state: TurnState):
    await context.send_activity("Hello! How can I help you?")

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, state: TurnState):
    await context.send_activity(f"You said: {context.activity.text}")

if __name__ == "__main__":
    async def messages(req: Request) -> Response:
        return await start_agent_process(req, AGENT_APP, AGENT_APP.adapter)

    app = Application()
    app.router.add_post("/api/messages", messages)
    app["agent_app"] = AGENT_APP
    app["adapter"] = AGENT_APP.adapter
    run_app(app, host="localhost", port=3978)

Registre controladores de actividad

Manejar mensajes

Buscar mensajes con texto exacto (sin distinguir entre mayúsculas y minúsculas):

OnMessage("help", async (context, state, ct) =>
{
    await context.SendActivityAsync("Here's what I can do...", cancellationToken: ct);
});

Buscar los mensajes utilizando una expresión regular:

OnMessage(new Regex(@"^order\s+\d+$", RegexOptions.IgnoreCase), async (context, state, ct) =>
{
    await context.SendActivityAsync("Looking up your order...", cancellationToken: ct);
});

app.onMessage('help', async (context: TurnContext, state: TurnState) => {
    await context.sendActivity("Here's what I can do...")
})

Buscar los mensajes utilizando una expresión regular:

app.onMessage(/^order\s+\d+$/i, async (context: TurnContext, state: TurnState) => {
    await context.sendActivity('Looking up your order...')
})

@AGENT_APP.message("/help")
async def on_help(context: TurnContext, state: TurnState):
    await context.send_activity("Here's what I can do...")

Buscar los mensajes utilizando una expresión regular:

import re

@AGENT_APP.message(re.compile(r"^order\s+\d+$", re.IGNORECASE))
async def on_order(context: TurnContext, state: TurnState):
    await context.send_activity("Looking up your order...")

Controlar actualizaciones de conversación

Registre los controladores para los eventos del ciclo de vida de la conversación, como la incorporación o salida de miembros.

OnConversationUpdate(ConversationUpdateEvents.MembersAdded, async (context, state, ct) =>
{
    foreach (var member in context.Activity.MembersAdded)
    {
        if (member.Id != context.Activity.Recipient.Id)
        {
            await context.SendActivityAsync("Welcome!", cancellationToken: ct);
        }
    }
});

OnConversationUpdate(ConversationUpdateEvents.MembersRemoved, async (context, state, ct) =>
{
    // Called when participants leave the conversation
});

app.onConversationUpdate('membersAdded', async (context: TurnContext) => {
    for (const member of context.activity.membersAdded ?? []) {
        if (member.id !== context.activity.recipient.id) {
            await context.sendActivity('Welcome!')
        }
    }
})

app.onConversationUpdate('membersRemoved', async (context: TurnContext) => {
    // Called when participants leave the conversation
})

@AGENT_APP.conversation_update("membersAdded")
async def on_members_added(context: TurnContext, state: TurnState):
    for member in context.activity.members_added or []:
        if member.id != context.activity.recipient.id:
            await context.send_activity("Welcome!")

@AGENT_APP.conversation_update("membersRemoved")
async def on_members_removed(context: TurnContext, state: TurnState):
    pass  # Called when participants leave the conversation

Controlar cualquier tipo de actividad

Coincida con cualquier actividad mediante su cadena de tipo para tener un control total sobre el enrutamiento.

OnActivity(ActivityTypes.Message, async (context, state, ct) =>
{
    // Handles all message activities
});

OnActivity(ActivityTypes.Event, async (context, state, ct) =>
{
    // Handles event activities
});

Use constantes de ActivityTypes en lugar de cadenas codificadas de forma fija.

app.onActivity('message', async (context: TurnContext, state: TurnState) => {
    // Handles all message activities
})

app.onActivity('event', async (context: TurnContext, state: TurnState) => {
    // Handles event activities
})

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, state: TurnState):
    pass  # Handles all message activities

@AGENT_APP.activity("event")
async def on_event(context: TurnContext, state: TurnState):
    pass  # Handles event activities

Controlar el orden de evaluación de rutas

El sistema ordena las rutas en un orden fijo de evaluación cuando las registras, no en tiempo de ejecución. La ordenación se realiza en dos niveles:

Tipo de ruta: El sistema agrupa las rutas por tipo y siempre evalúa los tipos de mayor prioridad antes que los de menor prioridad, independientemente del rango:

Prioridad	Tipo de ruta
1 (el más alto)	Rutas de invocación agénticas
2	Invocar rutas (acciones de tarjeta adaptables, devoluciones de llamada de OAuth y otras invocaciones sensibles al tiempo)
3	Rutas agénticas
4 (el más bajo)	Todas las demás rutas

Rango: Dentro de cada grupo de tipos de rutas, el sistema ordena las rutas por su valor de rango. Los valores numéricos más bajos se evalúan primero.

Use RouteRank constantes para establecer la clasificación al registrar un controlador:

Constante	Valor	Significado
`RouteRank.First`	`0`	Se evalúa antes de todas las demás rutas de su grupo
`RouteRank.Unspecified`	`32767`	De forma predeterminada, cuando no se especifica ningún rango
`RouteRank.Last`	`65535`	Se evalúa después de todas las demás rutas de su grupo

Por defecto, la evaluación se detiene en la primera ruta coincidente. Utilice RouteRank.Last como opción de reserva general que gestione todo aquello que no coincida con una ruta más específica.

// Specific handlers use the default rank
OnMessage("status", HandleStatusAsync);
OnMessage("help", HandleHelpAsync);

// Catch-all — handles anything not matched above
OnActivity(ActivityTypes.Message, HandleUnknownMessageAsync, rank: RouteRank.Last);

// Specific handlers use the default rank
app.onMessage('status', handleStatusAsync)
app.onMessage('help', handleHelpAsync)

// Catch-all — handles anything not matched above
app.onActivity('message', handleUnknownMessageAsync, RouteRank.Last)

@AGENT_APP.message("/status")
async def on_status(context: TurnContext, state: TurnState):
    await context.send_activity("Status: OK")

@AGENT_APP.message("/help")
async def on_help(context: TurnContext, state: TurnState):
    await context.send_activity("Here's what I can do...")

# Catch-all — handles anything not matched above (registered last)
@AGENT_APP.activity("message")
async def on_unknown(context: TurnContext, state: TurnState):
    await context.send_activity("I didn't understand that. Type /help for options.")

Enlaces de ciclo de vida de turnos

Registrar lógica que se ejecuta en cada turno, antes o después del emparejamiento de rutas. Estos enlaces son útiles para el registro, los problemas transversales y el control de errores.

OnBeforeTurn(async (context, state, ct) =>
{
    logger.LogInformation("Turn started: {Type}", context.Activity.Type);
    return true; // Return false to abort the turn
});

OnAfterTurn(async (context, state, ct) =>
{
    logger.LogInformation("Turn completed");
    return true; // Return false to skip state saving
});

OnTurnError(async (context, state, exception, ct) =>
{
    logger.LogError(exception, "Turn error");
    await context.SendActivityAsync("Something went wrong. Please try again.", cancellationToken: ct);
});

Cuando OnBeforeTurn devuelve false, el turno se aborta y no se ejecuta ninguna ruta. Cuando OnAfterTurn devuelve false, no se guarda el estado de turno.

app.beforeTurn(async (context: TurnContext, state: TurnState) => {
    console.log(`Turn started: ${context.activity.type}`)
    return true // Return false to abort the turn
})

app.afterTurn(async (context: TurnContext, state: TurnState) => {
    console.log('Turn completed')
    return true // Return false to skip state saving
})

app.onError(async (context: TurnContext, error: Error) => {
    console.error('Turn error:', error)
    await context.sendActivity('Something went wrong. Please try again.')
})

@AGENT_APP.before_turn
async def on_before_turn(context: TurnContext, state: TurnState) -> bool:
    print(f"Turn started: {context.activity.type}")
    return True  # Return False to abort the turn

@AGENT_APP.after_turn
async def on_after_turn(context: TurnContext, state: TurnState) -> bool:
    print("Turn completed")
    return True  # Return False to skip state saving

@AGENT_APP.turn_error
async def on_turn_error(context: TurnContext, state: TurnState, error: Exception):
    print(f"Turn error: {error}")
    await context.send_activity("Something went wrong. Please try again.")

Usar el estado del turno

El agente carga automáticamente el estado de turno antes de que los controladores se ejecuten y lo guarde después. El objeto de estado de turno que se pasa a sus controladores le permite tener acceso a los distintos ámbitos, de modo que puede leer y escribir datos que persisten entre turnos o que son efímeros para el turno actual:

Ámbito de conversación: para los datos compartidos en todos los turnos de una conversación
Ámbito de usuario: Para datos por usuario
Ámbito temporal: Para datos que solo necesitan existir durante el turno actual

OnActivity(ActivityTypes.Message, async (context, state, ct) =>
{
    // Conversation scope — persisted per conversation
    var count = state.Conversation.GetValue<int>("messageCount", () => 0);
    state.Conversation.SetValue("messageCount", count + 1);

    // User scope — persisted per user
    var name = state.User.GetValue<string>("displayName");

    // Temp scope — current turn only
    state.Temp.SetValue("parsedInput", context.Activity.Text?.Trim());

    await context.SendActivityAsync($"Message #{count + 1}: {context.Activity.Text}", cancellationToken: ct);
});

app.onActivity('message', async (context: TurnContext, state: TurnState) => {
    // Conversation scope — persisted per conversation
    let count: number = state.getValue('conversation.messageCount') ?? 0
    state.setValue('conversation.messageCount', count + 1)

    // User scope — persisted per user
    const name: string = state.getValue('user.displayName')

    await context.sendActivity(`Message #${count + 1}: ${context.activity.text}`)
})

@AGENT_APP.activity("message")
async def on_message(context: TurnContext, state: TurnState):
    # Conversation scope — persisted per conversation
    count = state.get_value("conversation.message_count") or 0
    state.set_value("conversation.message_count", count + 1)

    # User scope — persisted per user
    name = state.get_value("user.display_name")

    await context.send_activity(f"Message #{count + 1}: {context.activity.text}")

Nota

Use MemoryStorage para desarrollo y pruebas locales. Para despliegues en producción, especialmente aquellos que se ejecutan en múltiples instancias, utiliza un proveedor de almacenamiento persistente como Azure Cosmos DB o Azure Blob Storage. Consulte Usar proveedores de almacenamiento en el agente.

Pasos siguientes

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-07-31

AgentApplication en SDK de agentes de Microsoft 365

Cómo funciona AgentApplication

Conceptos principales

Actividades

Rutas

Estado de turno

Contexto de turno

Middleware

Crear un agente

Registre controladores de actividad

Manejar mensajes

Controlar actualizaciones de conversación

Controlar cualquier tipo de actividad

Controlar el orden de evaluación de rutas

Enlaces de ciclo de vida de turnos

Usar el estado del turno

Pasos siguientes

Comentarios

Recursos adicionales