AgentApplication no SDK de Agentes do Microsoft 365

AgentApplication é o componente central de um agente criado com o Agents SDK. AgentApplication é o ponto de entrada para todas as atividades de entrada, incluindo mensagens de usuários, eventos de ciclo de vida de conversa, interações de cartão adaptável, retornos de chamada do OAuth.

Um agente é, em sua essência, um AgentApplication. Configure-o com manipuladores que descrevem o que seu agente faz. O SDK cuida do roteamento, do gerenciamento de estado e da infraestrutura necessária para executá-lo.

Como o AgentApplication funciona

Cada agente tem um ciclo de vida que começa quando um canal (Microsoft Teams, um serviço de bot ou um cliente personalizado) entrega uma atividade ao ponto de extremidade do agente. AgentApplication fica no centro desse ciclo de vida:

Channel → Hosting layer → AgentApplication → Your handlers

As camadas de processamento em um agente criado com o SDK de Agentes funcionam da seguinte maneira:

A camada de hospedagem recebe a solicitação HTTP e a autentica.
Processa AgentApplication a atividade de entrada por meio de seu pipeline.
Seus controladores são chamados com base em rotas correspondentes.

O agente carrega o estado do turno antes de executar os manipuladores. Depois, o agente salva o estado do turno.

Conceitos principais

Atividades

Tudo no SDK de Agentes flui como uma atividade. Uma atividade é uma mensagem estruturada que representa algo que aconteceu. Uma atividade tem um tipo, como mensagem, evento, invocação, conversationUpdate e assim por diante. Ele transporta uma carga útil relevante para esse tipo de operação. AgentApplication recebe atividades e as roteia para o manipulador correto.

Routes

Uma rota emparelha um seletor com um manipulador. O seletor determina se uma rota corresponde à atividade atual. O controlador executa sua lógica quando a rota coincide.

Registre rotas ao configurar seu agente. Eles podem corresponder:

Uma mensagem que contém um texto específico ou uma expressão regular correspondente
Qualquer atividade de um determinado tipo
Eventos do ciclo de conversa (membro adicionado, membro removido)
Ações do cartão adaptável
Condições personalizadas

Quando uma atividade chega, o sistema avalia as rotas em ordem até encontrar uma correspondência. Por padrão, apenas uma rota é executada.

Estado do turno

AgentApplication gerencia o estado de turno—armazenamento estruturado particionado em âmbitos:

Tipo de escopo	Description
Conversa	Compartilhado entre todos os usuários em uma conversa, persistido entre turnos
Usuário	Restringido a um usuário individual em todas as conversas
Temporário	Somente turno atual – nunca persistido

O sistema carrega automaticamente o estado antes que seus manipuladores sejam executados e o salve automaticamente posteriormente.

Contexto de turno

Quando um manipulador é executado, ele recebe um contexto de turno. O contexto de turno é um resumo instantâneo da atividade atual, da conexão do adaptador e dos utilitários para enviar respostas. O contexto de turno é sua interface para a interação atual.

Middleware

AgentApplication dá suporte a um pipeline de middleware. Middleware é uma cadeia de componentes que processam cada fase antes e depois da execução dos manipuladores. O middleware pode inspecionar, transformar ou interromper o fluxo de atividade. Os usos comuns incluem registro em log, verificações de autenticação e normalização de solicitação.

Criar um agente

Subclasse AgentApplication e registre seus manipuladores no construtor. A estrutura de hospedagem injeta AgentApplicationOptionsautomaticamente .

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 seu agente em 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 e registre manipuladores na instância usando a API fluente. Para iniciar o servidor, chame startServer do pacote de hospedagem 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 configuração manual do Express sem 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 com um parâmetro de tipo e registre manipuladores 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 manipuladores de atividade

Manipular mensagens

Corresponder mensagens por texto exato (não diferencia maiúsculas de minúsculas):

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

Combine mensagens usando uma expressão 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...")
})

Combine mensagens usando uma expressão 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...")

Combine mensagens usando uma expressão 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...")

Gerenciar atualizações de conversação

Registre manipuladores para eventos de ciclo de vida de conversa, como membros entrando ou saindo.

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

Gerenciar qualquer tipo de atividade

Corresponda a qualquer atividade por sua cadeia de caracteres de tipo para controle completo sobre o roteamento.

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

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

Use ActivityTypes constantes em vez de cadeias de caracteres codificadas.

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 a ordem de avaliação das rotas

O sistema classifica as rotas em uma ordem de avaliação fixa no momento em que você as registra, e não em tempo de execução. A classificação usa dois níveis:

Tipo de rota: o sistema agrupa rotas por tipo e sempre avalia tipos de prioridade mais alta antes dos tipos de prioridade mais baixa, independentemente da classificação:

Prioridade	Tipo de rota
1 (mais alto)	Rotas de invocação de agente
2	Invocar rotas (ações de cartão adaptável, retornos de chamada de OAuth e outras invocações urgentes)
3	Rotas do agente
4 (mais baixo)	Todas as outras rotas

Classificação: dentro de cada grupo de tipos de rota, o sistema ordena rotas por seu valor de classificação. Valores numéricos mais baixos são avaliados primeiro.

Use RouteRank constantes para definir a classificação ao registrar um manipulador:

Constante	Valor	Significado
`RouteRank.First`	`0`	Avaliado antes de todas as outras rotas em seu grupo
`RouteRank.Unspecified`	`32767`	Padrão quando nenhuma classificação é especificada
`RouteRank.Last`	`65535`	Avaliado depois de todas as outras rotas do seu grupo

Por padrão, a avaliação é interrompida na primeira rota correspondente. Use RouteRank.Last para um fallback geral que manipula qualquer coisa que não corresponda a uma rota mais 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.")

Ganchos de ciclo de vida do turno

Registre a lógica que é executada em cada turno, antes ou depois da correspondência de rotas. Esses ganchos são úteis para registro em log, preocupações transversais e tratamento de erros.

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);
});

Quando OnBeforeTurn retorna false, o ciclo é anulado e nenhuma rota é executada. Quando OnAfterTurn retorna false, o estado de turno não é salvo.

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 o estado do turno

O agente carrega automaticamente o estado do turno antes que seus manipuladores sejam executados e salve-o posteriormente. O objeto de estado do turno passado para seus manipuladores fornece acesso aos diferentes escopos para que você possa ler e gravar dados que persistem entre turnos ou que sejam efêmeros para o turno atual.

Escopo da conversa: para dados compartilhados em todos os turnos de uma conversa
Escopo do usuário: para dados por usuário
Escopo temporário: para dados que só precisam existir durante o turno atual

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

Use MemoryStorage para desenvolvimento e teste locais. Para implantações de produção, especialmente implantações em execução em várias instâncias, use um provedor de armazenamento persistente, como Azure Cosmos DB ou Armazenamento de Blobs do Azure. Consulte Como usar provedores de armazenamento no seu agente.

Próximas etapas

Comentários

Esta página foi útil?

Last updated on 2026-04-29

AgentApplication no SDK de Agentes do Microsoft 365

Como o AgentApplication funciona

Conceitos principais

Atividades

Routes

Estado do turno

Contexto de turno

Middleware

Criar um agente

Registrar manipuladores de atividade

Manipular mensagens

Gerenciar atualizações de conversação

Gerenciar qualquer tipo de atividade

Controlar a ordem de avaliação das rotas

Ganchos de ciclo de vida do turno

Usar o estado do turno

Próximas etapas

Comentários

Recursos adicionais