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

Este guia de início rápido orienta você na criação de um agente de mecanismo personalizado que responde de volta com qualquer mensagem que você enviar para ele.

Pré-requisitos

• Python 3.9 ou mais recente.

  • Para instalar o Python, acesse 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 escolha. Estas instruções usam o Visual Studio Code.

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

Inicializar o projeto e instalar o SDK

Crie um projeto do 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 usando este comando:

   code .
   

3. Crie um ambiente virtual com o método de sua escolha e ative-o por meio do Visual Studio Code ou em um terminal.

   Ao usar o Visual Studio Code, você pode usar essas etapas com a extensão python instalada.

   1. Pressione F1, digite Python: Create environmente pressione Enter.

      1. Selecione Venv para criar um .venv ambiente virtual no workspace 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 cole-o 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
   

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

2. No mesmo diretório, crie um arquivo nomeado app.py com o código a seguir.

   # 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
   

Crie uma instância do agente como AgentApplication

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

• Atualização de 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}")

Inicie o servidor Web para escutar em localhost:3978

No 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 o agente localmente no modo anônimo

No seu terminal, execute o seguinte 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. Em outro terminal (para manter o agente em execução), instale o Microsoft 365 Agents Playground com este comando:

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

   Observação

   Esse 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 seu 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 teamsapptester comando abre seu navegador padrão e se conecta ao seu agente.

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

Este guia de início rápido orienta você na criação de um agente de mecanismo personalizado que responde de volta com qualquer mensagem que você enviar para ele.

Pré-requisitos

• Node.js v22 ou mais recente

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

• Um editor de código de sua escolha. Estas instruções usam o Visual Studio Code.

Inicializar o projeto e instalar o SDK

Use npm para inicializar um projeto de 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 de 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 usando este comando:

   code .
   

Importe as bibliotecas necessárias

Crie o arquivo index.mjs e importe os seguintes pacotes NPM para o código do 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 o EchoAgent como um AgentApplication

In index.mjs, adicione o seguinte código para criar a EchoAgent extensão do AgentApplication e implemente três rotas para responder a três eventos:

• Atualização de 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)
  }
}

Inicie o servidor Web para escutar em localhost:3978

No final de index.mjs, inicie o servidor Web usando startServer, baseado no Express, utilizando MemoryStorage como armazenamento do estado de turno.

startServer(new EchoAgent(new MemoryStorage()))

Executar o agente localmente no modo anônimo

No seu terminal, execute o seguinte comando:

node index.mjs

O terminal deve retornar o seguinte:

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

Testar localmente o agente

1. Em outro terminal (para manter o agente em execução), 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 seu 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 teamsapptester comando abre seu navegador padrão e se conecta ao seu agente.

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

Este guia de início rápido orienta você na criação de um agente de mecanismo personalizado que responde de volta com qualquer mensagem que você enviar para ele.

Pré-requisitos

• SDK do .NET 8.0 ou mais recente

  • Para instalar o SDK do .NET, acesse 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 escolha. Estas 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 usando este comando:

   code .
   

Importe as bibliotecas necessárias

Em Program.cs, substitua o conteúdo existente e adicione as seguintes using instruções para importar os pacotes do SDK para o código do 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 o EchoAgent como um AgentApplication

Em Program.cs, após as using instruções, adicione o seguinte código para criar o EchoAgentAgentApplication de extensão e implemente rotas para responder a eventos:

• Atualização de 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 do agente

Em Program.cs, após as using instruções, adicione o seguinte código para configurar o hospedeiro web, registrar o agente e mapear o /api/messages endpoint:

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 para que o aplicativo escute na porta correta.

Executar o agente localmente no modo anônimo

No seu terminal, execute o seguinte 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. Em 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

   Esse 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 seu 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 teamsapptester comando abre seu navegador padrão e se conecta ao seu agente.

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

Próximas etapas

• Confira exemplos do SDK de Agentes no GitHub
• Saiba mais sobre as atividades e como trabalhar com atividades
• Examine os eventos AgentApplication aos quais você pode responder do cliente
• Examine os eventos TurnContext que você pode enviar de volta para o cliente
• Provisionar recursos do Bot do Azure para usar com o SDK de Agentes
• Configurar o .NET Agent para usar o OAuth

O Agents Playground estará disponível por padrão se você já estiver usando o Kit de Ferramentas do Microsoft 365 Agents. Você pode 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 do Microsoft 365 Agents
• Criar agentes JavaScript no Visual Studio Code com o Kit de Ferramentas do Microsoft 365 Agents