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

Este início rápido orienta-o através da criação de um agente de motor personalizado que apenas responde com a que lhe enviar.

Pré-requisitos

  • Python 3.9 ou mais recente.

    • Para instalar o Python, aceda a https://www.python.org/downloads/ e siga as instruções para o seu sistema operativo.
    • Para verificar a versão, numa janela de terminal digite python --version.

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

    Se utilizar o Visual Studio Code, instale a extensão do Python

Inicializar o projeto e instalar o SDK

Crie um projeto no 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 no Visual Studio Code com este comando:

    code .

  3. Crie um ambiente virtual com o método à sua escolha e ative-o pelo Visual Studio Code ou num terminal.

    Quando utilizar o Visual Studio Code, pode seguir estes passos com a extensão do Python instalada.

    1. Prima F1, escreva Python: Create environment e prima Enter.

      1. Selecione Venv para criar um .venv ambiente virtual na área de trabalho atual.

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

        O valor pode ter o seguinte formato:

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

  4. Instalar o SDK de Agentes

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

    pip install microsoft-agents-hosting-aiohttp

Criar a aplicação de servidor e importar as bibliotecas necessárias

  1. Crie o ficheiro chamado start_server.py, copie o seguinte código 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

    Este código define uma função start_server que vamos usar no próximo ficheiro.

  2. No mesmo diretório, crie o , crie um ficheiro com o nome 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 uma AgentApplication

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

  • Atualização da conversação
  • 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

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 este comando:

python app.py

O terminal deve devolver o seguinte:

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

Testar o agente localmente

  1. Num outro terminal (para manter o agente em execução), instale o Ambiente de Demonstração de Agentes do Microsoft 365 com este comando:

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

    Nota

    Este comando usa npm porque o Ambiente de Demonstração de Agentes do Microsoft 365 não está disponível usando pip.

    O terminal deve devolver 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 seu agente usando este comando:

    teamsapptester

    O terminal deve devolver 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 browser predefinido e conecta-se ao agente.

O seu agente no ambiente de demonstração de agentes

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

Este início rápido orienta-o através da criação de um agente de motor personalizado que apenas responde com a que lhe enviar.

Pré-requisitos

  • Node.js v22 ou mais recente

    • Para instalar Node.js, aceda a nodejs.org e siga as instruções para o seu sistema operativo.
    • Para verificar a versão, numa janela de terminal digite node --version.

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

Inicializar o projeto e instalar o SDK

Utilize npm para iniciar um projeto Node.js, criando o ficheiro package.json e instalando as dependências necessárias

  1. Abrir um terminal e criar uma nova pasta

    mkdir echo
cd echo

  2. Inicialize o projeto node.js

    npm init -y

  3. Instalar o SDK de Agentes

    npm install @microsoft/agents-hosting-express

  4. Abra a pasta no Visual Studio Code com o seguinte comando:

    code .

Importar as bibliotecas obrigatórias

Crie o ficheiro index.mjs e importe os seguintes pacotes NPM para o seu código de aplicação:

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

Implementar o EchoAgent como AgentApplication

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

  • Atualização da conversação
  • 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

No final de index.mjs inicie o servidor web usando startServer baseado no Express utilizando MemoryStorage como armazenamento de estado de repetições.

startServer(new EchoAgent(new MemoryStorage()))

Executar o agente localmente no modo anónimo

No seu terminal, execute este comando:

node index.mjs

O terminal deve devolver o seguinte:

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

Testar o agente localmente

  1. Num outro terminal (para manter o agente em execução), instale o Ambiente de Demonstração de Agentes do Microsoft 365 com este comando:

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

    O terminal deve devolver 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 seu agente usando este comando:

    node_modules/.bin/teamsapptester

    O terminal deve devolver 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 browser predefinido e conecta-se ao agente.

O seu agente no ambiente de demonstração de agentes

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

Este início rápido orienta-o através da criação de um agente de motor personalizado que apenas responde com a que lhe enviar.

Pré-requisitos

  • .NET 8.0 SDK ou superior

    • Para instalar o SDK do .NET, aceda a dotnet.microsoft.com e siga as instruções para o seu sistema operativo.
    • Para verificar a versão, numa janela de terminal digite dotnet --version.

  • Um editor de código à sua escolha. Estas instruções utilizam 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 no Visual Studio Code com este comando:

    code .

Importar as bibliotecas obrigatórias

Em Program.cs, substitua o conteúdo existente e adicione as seguintes instruções using para importar os pacotes do SDK na sua aplicação:

// 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 AgentApplication

Em Program.cs, após as instruções using, adicione o seguinte código para criar a classe EchoAgent que expande o AgentApplication e implemente o encaminhamento para responder a eventos:

  • Atualização da conversação
  • 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 registar a aplicação de agente

Em Program.cs, depois das instruções using, adicione o seguinte código para configurar o servidor web, registar o agente e mapear o ponto final /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();

Configurar o servidor web para escutar no localhost:3978

Em launchSettings.json, atualize o applicationURL para http://localhost:3978 para que a aplicação escute na porta correta.

Executar o agente localmente no modo anónimo

No seu terminal, execute este comando:

dotnet run

O terminal deve devolver algo como:

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

Testar o agente localmente

  1. Num outro terminal (para manter o agente a funcionar), instale o Ambiente de Demonstração de Agentes do Microsoft 365 com o seguinte comando:

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

    Nota

    Este comando usa npm porque o Ambiente de Demonstração de Agentes do Microsoft 365 é distribuído como um pacote npm.

    O terminal deve devolver 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 seu agente usando este comando:

    teamsapptester

    O terminal deve devolver 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 browser predefinido e conecta-se ao agente.

O seu agente no ambiente de demonstração de agentes

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

Passos seguintes

O Ambiente de Demonstração está disponível por predefinição se já estiver a usar o Toolkit do Microsoft 365. Pode utilizar um dos seguintes guias caso queira começar a utilizar o Toolkit:

  • Last updated on