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, los callbacks de OAuth.

Un agente es, en esencia, un AgentApplication. Tú lo configuras con controladores que describen lo que hace el agente. El SDK se encarga del enrutamiento, la administración de estado y la infraestructura necesaria para ejecutarlo.

Funcionamiento de AgentApplication

Cada agente tiene un ciclo de vida que se inicia cuando un canal (Microsoft Teams, un servicio de bot o un cliente personalizado) entrega una actividad al punto de conexión del agente. AgentApplication se encuentra en el centro de ese ciclo de vida:

Channel → Hosting layer → AgentApplication → Your handlers

Las capas de procesamiento en un agente compilado con el SDK de agentes funcionan de la siguiente manera:

La capa de hospedaje recibe la solicitud HTTP y la autentica.
AgentApplication procesa la actividad entrante a través de su tubería.
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

Activities

Todo lo que hay en el SDK de agentes fluye como una actividad. Una actividad es un mensaje estructurado que representa algo que ha ocurrido. Una actividad tiene un tipo, como mensaje (message), evento (event), invocar (invoke), actualización de conversación (conversationUpdate), etcétera. Lleva una carga útil relevante para ese tipo. AgentApplication recibe actividades y las enruta al controlador correcto.

Routes

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

Registre rutas al configurar el agente. Pueden coincidir con:

Mensaje que contiene texto específico o que coincide con una expresión regular
Cualquier actividad de un tipo determinado
Eventos del ciclo de vida de la conversación (miembro agregado, miembro quitado)
Acciones de tarjetas adaptativas
Condiciones personalizadas

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

Estado de turno

AgentApplication administra el estado de turno: 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
Temp	Solo turno actual: nunca se conserva

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

Cambiar contexto

Cuando se ejecuta un controlador, 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 de turno actúa como tu interfaz hacia la interacción en curso.

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. Entre los usos comunes se incluyen el registro, las comprobaciones de autenticación y la normalización de solicitudes.

Crear un agente

Subclase AgentApplication y registre los controladores en el constructor. El marco de hospedaje inserta AgentApplicationOptionsautomáticamente .

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 controladores en la instancia mediante la API fluida. Para iniciar el servidor, llame startServer desde el paquete de hospedaje 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 manejadores 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)

Registrar controladores de actividad

Gestionar mensajes

Coincidencia de mensajes por 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);
});

Coincidencia de mensajes mediante 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...")
})

Coincidencia de mensajes mediante 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...")

Coincidencia de mensajes mediante 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 las actualizaciones de conversación

Registre un controlador para los eventos del ciclo de vida de la conversación, como cuando los miembros se unen o salen.

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

Gestionar cualquier tipo de actividad

Coincide con cualquier actividad por su cadena de tipo para un control completo 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 ActivityTypes constantes en lugar de cadenas codificadas de forma rígida.

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 de evaluación fijo al registrarlas, no en tiempo de ejecución. La ordenación usa dos niveles:

Tipo de ruta: el sistema agrupa las rutas por tipo y siempre evalúa los tipos de prioridad superior antes de los tipos de prioridad inferior, independientemente de la clasificación:

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

Rank: dentro de cada grupo de tipos de ruta, el sistema ordena las rutas por su valor de clasificación. Los valores numéricos inferiores se evalúan primero.

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

Constante	Value	Meaning
`RouteRank.First`	`0`	Se evalúa antes de todas las demás rutas de su grupo
`RouteRank.Unspecified`	`32767`	Valor predeterminado cuando no se especifica ninguna clasificación
`RouteRank.Last`	`65535`	Se evalúa después de todas las demás rutas de su grupo

De forma predeterminada, la evaluación se detiene en la primera ruta coincidente. Se utiliza RouteRank.Last para un mecanismo catch-all que gestiona todo lo que no coincide 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

Registre la lógica que se ejecuta en cada turno, antes o después de la coincidencia 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, se anula el turno y no se ejecuta ninguna ruta. Cuando OnAfterTurn devuelve false, el estado de turno no se guarda.

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.")

Uso del estado de 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 manejadores le brinda acceso a los diferentes escopos, lo que le permite leer y escribir datos que se conservan 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 del Usuario: para los datos por usuario
Ámbito temporal: para los 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}")

Note

Se usa MemoryStorage para el desarrollo y las pruebas locales. En el caso de las implementaciones de producción, especialmente las implementaciones que se ejecutan en varias instancias, use un proveedor de almacenamiento persistente, como Azure Cosmos DB o Azure Blob Storage. Consulte Usar proveedores de almacenamiento en su agente.

Pasos siguientes

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-04-29

AgentApplication en SDK de agentes de Microsoft 365

Funcionamiento de AgentApplication

Conceptos principales

Activities

Routes

Estado de turno

Cambiar contexto

Middleware

Crear un agente

Registrar controladores de actividad

Gestionar mensajes

Controlar las actualizaciones de conversación

Gestionar cualquier tipo de actividad

Controlar el orden de evaluación de rutas

Enlaces de ciclo de vida de turnos

Uso del estado de turno

Pasos siguientes

Comentarios

Recursos adicionales