Início Rápido: Criar e testar um agente básico

Este início rápido orienta você em meio à criação de um agente de mecanismo personalizado que responde com a mensagem que você envia para ele.

Pré-requisitos

• Python 3.9 ou mais recente.

  • Para instalar o Python, vá até https://www.python.org/downloads/ e siga as instruções do sistema operacional.
  • Para verificar a versão, em uma janela de terminal, digite python --version.

• Um editor de código de sua preferência. Essas instruções usam o Visual Studio Code.

  Se você usar o Visual Studio Code, instale a extensão Python

Inicializar o projeto e instalar o SDK

Crie um projeto Python e instale as dependências necessárias.

1. Abrir um terminal e criar uma nova pasta

   mkdir echo
   cd echo
   

2. Abra a pasta usando o Visual Studio Code com este comando:

   code .
   

3. Crie um ambiente virtual pelo método de sua preferência e o ative por meio do Visual Studio Code ou em um terminal.

   Ao usar o Visual Studio Code, você pode seguir estas etapas com a extensão Python instalada.

   1. Pressione F1, digite Python: Create environment e pressione Enter.

      1. Selecione Venv para criar um ambiente virtual .venv no espaço de trabalho atual.

      2. Selecione uma instalação do Python para criar o ambiente virtual.

         O valor pode ter esta aparência:

         Python 1.13.6 ~\AppData\Local\Programs\Python\Python313\python.exe

4. Instalar o SDK de Agentes

   Use pip para instalar o pacote microsoft-agents-hosting-aiohttp com este comando:

   pip install microsoft-agents-hosting-aiohttp
   

Criar o aplicativo de servidor e importar as bibliotecas necessárias

1. Crie um arquivo chamado start_server.py, copie o código a seguir e o cole em:

   # start_server.py
   from os import environ
   from microsoft_agents.hosting.core import AgentApplication, AgentAuthConfiguration
   from microsoft_agents.hosting.aiohttp import (
      start_agent_process,
      jwt_authorization_middleware,
      CloudAdapter,
   )
   from aiohttp.web import Request, Response, Application, run_app
   
   
   def start_server(
      agent_application: AgentApplication, auth_configuration: AgentAuthConfiguration
   ):
      async def entry_point(req: Request) -> Response:
         agent: AgentApplication = req.app["agent_app"]
         adapter: CloudAdapter = req.app["adapter"]
         return await start_agent_process(
               req,
               agent,
               adapter,
         )
   
      APP = Application(middlewares=[jwt_authorization_middleware])
      APP.router.add_post("/api/messages", entry_point)
      APP.router.add_get("/api/messages", lambda _: Response(status=200))
      APP["agent_configuration"] = auth_configuration
      APP["agent_app"] = agent_application
      APP["adapter"] = agent_application.adapter
   
      try:
         run_app(APP, host="localhost", port=environ.get("PORT", 3978))
      except Exception as error:
         raise error
   

   Este código define a função start_server que usaremos no próximo arquivo.

2. No mesmo diretório, crie um arquivo chamado app.py com o seguinte código.

   # app.py
   from microsoft_agents.hosting.core import (
      AgentApplication,
      TurnState,
      TurnContext,
      MemoryStorage,
   )
   from microsoft_agents.hosting.aiohttp import CloudAdapter
   from start_server import start_server
   

Criar uma instância do agente como AgentApplication

Em app.py, adicione o seguinte código para criar AGENT_APP como uma instância de AgentApplication e implemente três rotas para responder a três eventos:

• Atualização da Conversa
• a mensagem /help
• qualquer outra atividade

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

async def _help(context: TurnContext, _: TurnState):
    await context.send_activity(
        "Welcome to the Echo Agent sample 🚀. "
        "Type /help for help or send a message to see the echo feature in action."
    )

AGENT_APP.conversation_update("membersAdded")(_help)

AGENT_APP.message("/help")(_help)


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

Iniciar o servidor web para escutar em localhost:3978

Ao final de app.py, inicie o servidor web usando start_server.

if __name__ == "__main__":
    try:
        start_server(AGENT_APP, None)
    except Exception as error:
        raise error

Executar localmente o agente em modo anônimo

No terminal, execute este comando:

python app.py

O terminal deve retornar o seguinte:

======== Running on http://localhost:3978 ========
(Press CTRL+C to quit)

Testar localmente o agente

1. Abra outro terminal (para manter o agente em execução) e instale o Microsoft 365 Agents Playground com este comando:

   npm install -g @microsoft/teams-app-test-tool
   

   Observação

   Este comando usa npm porque o Microsoft 365 Agents Playground não está disponível usando pip.

   O terminal deve retornar algo como:

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. Execute a ferramenta de teste para interagir com o agente usando este comando:

   teamsapptester
   

   O terminal deve retornar algo como:

   Telemetry: agents-playground-cli/serverStart {"cleanProperties":{"options":"{\"configFileOptions\":{\"path\":\"<REDACTED: user-file-path>\"},\"appConfig\":{},\"port\":56150,\"disableTelemetry\":false}"}}
   
   Telemetry: agents-playground-cli/cliStart {"cleanProperties":{"isExec":"false","argv":"<REDACTED: user-file-path>,<REDACTED: user-file-path>"}}
   
   Listening on 56150
   Microsoft 365 Agents Playground is being launched for you to debug the app: http://localhost:56150
   started web socket client
   started web socket client
   Waiting for connection of endpoint: http://127.0.0.1:3978/api/messages
   waiting for 1 resources: http://127.0.0.1:3978/api/messages
   wait-on(37568) complete
   Telemetry: agents-playground-server/getConfig {"cleanProperties":{"internalConfig":"{\"locale\":\"en-US\",\"localTimezone\":\"America/Los_Angeles\",\"channelId\":\"msteams\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"installationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"conversationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   

O comando teamsapptester abre o navegador padrão e se conecta ao agente.

Agora você pode enviar qualquer mensagem para ver a resposta de eco, ou enviar a mensagem /help para ver como essa mensagem é encaminhada para o manipulador _help.

Este início rápido orienta você em meio à criação de um agente de mecanismo personalizado que responde com a mensagem que você envia para ele.

Pré-requisitos

• Node.js v22 ou mais recente

  • Para instalar Node.js, vá até nodejs.org e siga as instruções para o sistema operacional.
  • Para verificar a versão, em uma janela de terminal, digite node --version.

• Um editor de código de sua preferência. Essas instruções usam o Visual Studio Code.

Inicializar o projeto e instalar o SDK

Use npm para inicializar um projeto node.js criando um package.json e instalando as dependências necessárias

1. Abrir um terminal e criar uma nova pasta

   mkdir echo
   cd echo
   

2. Inicializar o projeto node.js

   npm init -y
   

3. Instalar o SDK de Agentes

   npm install @microsoft/agents-hosting-express
   

4. Abra a pasta usando o Visual Studio Code com este comando:

   code .
   

Importar as bibliotecas necessárias

Crie o arquivo index.mjs e importe os seguintes pacotes NPM para o código de aplicativo:

• @microsoft/agents-hosting
• @microsoft/agents-hosting-express

// index.mjs
import { startServer } from '@microsoft/agents-hosting-express'
import { AgentApplication, MemoryStorage } from '@microsoft/agents-hosting'

Implementar EchoAgent como AgentApplication

Em index.mjs, adicione o seguinte código para criar EchoAgent estendendo AgentApplication e implementar três rotas para responder a três eventos:

• Atualização da Conversa
• a mensagem /help
• qualquer outra atividade

class EchoAgent extends AgentApplication {
  constructor (storage) {
    super({ storage })

    this.onConversationUpdate('membersAdded', this._help)
    this.onMessage('/help', this._help)
    this.onActivity('message', this._echo)
  }

  _help = async context => 
    await context.sendActivity(`Welcome to the Echo Agent sample 🚀. 
      Type /help for help or send a message to see the echo feature in action.`)

  _echo = async (context, state) => {
    let counter= state.getValue('conversation.counter') || 0
    await context.sendActivity(`[${counter++}]You said: ${context.activity.text}`)
    state.setValue('conversation.counter', counter)
  }
}

Iniciar o servidor web para escutar em localhost:3978

Ao final de index.mjs, inicie o servidor web usando startServer baseado em express usando MemoryStorage como o armazenamento do estado do turno.

startServer(new EchoAgent(new MemoryStorage()))

Executar localmente o agente em modo anônimo

No terminal, execute este comando:

node index.mjs

O terminal deve retornar:

Server listening to port 3978 on sdk 0.6.18 for appId undefined debug undefined

Testar localmente o agente

1. Abra outro terminal (para manter o agente em execução) e instale o Microsoft 365 Agents Playground com este comando:

   npm install -D @microsoft/teams-app-test-tool
   

   O terminal deve retornar algo como:

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. Execute a ferramenta de teste para interagir com o agente usando este comando:

   node_modules/.bin/teamsapptester
   

   O terminal deve retornar algo como:

   Telemetry: agents-playground-cli/serverStart {"cleanProperties":{"options":"{\"configFileOptions\":{\"path\":\"<REDACTED: user-file-path>\"},\"appConfig\":{},\"port\":56150,\"disableTelemetry\":false}"}}
   
   Telemetry: agents-playground-cli/cliStart {"cleanProperties":{"isExec":"false","argv":"<REDACTED: user-file-path>,<REDACTED: user-file-path>"}}
   
   Listening on 56150
   Microsoft 365 Agents Playground is being launched for you to debug the app: http://localhost:56150
   started web socket client
   started web socket client
   Waiting for connection of endpoint: http://127.0.0.1:3978/api/messages
   waiting for 1 resources: http://127.0.0.1:3978/api/messages
   wait-on(37568) complete
   Telemetry: agents-playground-server/getConfig {"cleanProperties":{"internalConfig":"{\"locale\":\"en-US\",\"localTimezone\":\"America/Los_Angeles\",\"channelId\":\"msteams\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"installationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"conversationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   

O comando teamsapptester abre o navegador padrão e se conecta ao agente.

Agora você pode enviar qualquer mensagem para ver a resposta de eco, ou enviar a mensagem /help para ver como essa mensagem é encaminhada para o manipulador _help.

Este início rápido orienta você em meio à criação de um agente de mecanismo personalizado que responde com a mensagem que você envia para ele.

Pré-requisitos

• SDK do .NET 8.0 ou mais novo

  • Para instalar o SDK do .NET, vá até dotnet.microsoft.com e siga as instruções do sistema operacional.
  • Para verificar a versão, em uma janela de terminal, digite dotnet --version.

• Um editor de código de sua preferência. Essas instruções usam o Visual Studio Code.

Inicializar o projeto e instalar o SDK

Use dotnet para criar um novo projeto web e instalar as dependências necessárias.

1. Abrir um terminal e criar uma nova pasta

   mkdir echo
   cd echo
   

2. Inicializar o projeto .NET

   dotnet new web
   

3. Instalar o SDK de Agentes

   dotnet add package Microsoft.Agents.Hosting.AspNetCore
   

4. Abra a pasta usando o Visual Studio Code com este comando:

   code .
   

Importar as bibliotecas necessárias

Em Program.cs, substitua o conteúdo existente e adicione as seguintes instruções using a fim de importar os pacotes do SDK para o código de aplicativo:

// Program.cs
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App;
using Microsoft.Agents.Builder.State;
using Microsoft.Agents.Core.Models;
using Microsoft.Agents.Hosting.AspNetCore;
using Microsoft.Agents.Storage;
using Microsoft.AspNetCore.Builder;

Implementar EchoAgent como AgentApplication

Em Program.cs, depois das instruções using, adicione o seguinte código para criar o EchoAgent estendendo AgentApplication e implementar rotas para responder a eventos:

• Atualização da Conversa
• Qualquer outra atividade

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

   private async Task WelcomeMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
   {
        foreach (ChannelAccount member in turnContext.Activity.MembersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text("Hello and Welcome!"), cancellationToken);
            }
        }
    }

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

Configurar o servidor web e registrar o aplicativo de agente

Em Program.cs, depois das instruções using, adicione o seguinte código para configurar o host web, registrar o agente e mapear o ponto de extremidade /api/messages:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient();
builder.AddAgentApplicationOptions();
builder.AddAgent<EchoAgent>();
builder.Services.AddSingleton<IStorage, MemoryStorage>();

var app = builder.Build();

app.MapPost("/api/messages", async (HttpRequest request, HttpResponse response, IAgentHttpAdapter adapter, IAgent agent, CancellationToken cancellationToken) =>
{
    await adapter.ProcessAsync(request, response, agent, cancellationToken);
});

app.Run();

Definir o servidor web para escutar em localhost:3978

Em launchSettings.json, atualize o applicationURL para http://localhost:3978, de maneira que o aplicativo escute na porta correta.

Executar localmente o agente em modo anônimo

No terminal, execute este comando:

dotnet run

O terminal deve retornar algo como:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:3978

Testar localmente o agente

1. De outro terminal (para manter o agente em execução), instale o Microsoft 365 Agents Playground com o seguinte comando:

   npm install -g @microsoft/teams-app-test-tool
   

   Observação

   Este comando usa npm porque o Microsoft 365 Agents Playground é distribuído como um pacote npm.

   O terminal deve retornar algo como:

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. Execute a ferramenta de teste para interagir com o agente usando este comando:

   teamsapptester
   

   O terminal deve retornar algo como:

   Telemetry: agents-playground-cli/serverStart {"cleanProperties":{"options":"{\"configFileOptions\":{\"path\":\"<REDACTED: user-file-path>\"},\"appConfig\":{},\"port\":56150,\"disableTelemetry\":false}"}}
   
   Telemetry: agents-playground-cli/cliStart {"cleanProperties":{"isExec":"false","argv":"<REDACTED: user-file-path>,<REDACTED: user-file-path>"}}
   
   Listening on 56150
   Microsoft 365 Agents Playground is being launched for you to debug the app: http://localhost:56150
   started web socket client
   started web socket client
   Waiting for connection of endpoint: http://127.0.0.1:3978/api/messages
   waiting for 1 resources: http://127.0.0.1:3978/api/messages
   wait-on(37568) complete
   Telemetry: agents-playground-server/getConfig {"cleanProperties":{"internalConfig":"{\"locale\":\"en-US\",\"localTimezone\":\"America/Los_Angeles\",\"channelId\":\"msteams\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"installationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"conversationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   

O comando teamsapptester abre o navegador padrão e se conecta ao agente.

Na entrada de texto, insira e envie qualquer mensagem para ver a resposta de eco.

Próximas etapas

• Confira amostras do SDK de Agentes no GitHub
• Saiba mais sobre as Atividades e como trabalhar com Atividades
• Analisar os eventos AgentApplication que você pode responder pelo cliente
• Analisar os eventos TurnContext que você pode reenviar para o cliente
• Provisionar recursos do Azure Bot a serem usados com o SDK de Agentes
• Configurar o Agente .NET para usar OAuth

O Agents Playground estará disponível por padrão se você já estiver usando o Kit de ferramentas de agentes do Microsoft 365. Você poderá usar um dos seguintes guias se quiser começar a usar o kit de ferramentas:

• Criar agentes do .NET no Visual Studio usando o Kit de ferramentas de agentes do Microsoft 365
• Criar agentes JavaScript no Visual Studio Code com o Kit de ferramentas de agentes do Microsoft 365