Partilhar via

Guia de início rápido: criar e testar um agente básico

Este guia de início rápido orienta você através da criação de um agente de mecanismo personalizado que responde com qualquer mensagem que você enviar a ele.

Pré-requisitos

  • Python 3.9 ou mais recente.

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

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

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

Inicialize o projeto e instale o SDK

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

  1. Abra um terminal e crie 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 espaço de trabalho atual.

      2. Selecione uma instalação 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

Crie o aplicativo de servidor e importe as bibliotecas necessárias

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

    # 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 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 uma AgentApplication

No 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}")

Inicie o servidor Web para ouvir em localhost:3978

No final do app.py, inicie o servidor Web usando start_server.

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

Execute o agente localmente em modo anónimo

A partir do 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 ao nível local

  1. A partir de 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

    Este comando usa npm porque o Microsoft 365 Agents Playground 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 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 teamsapptester comando abre o navegador padrão e se conecta ao agente.

O seu agente no parque de diversões dos agentes

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ê através da criação de um agente de mecanismo personalizado que responde com qualquer mensagem que você enviar a ele.

Pré-requisitos

  • Node.js v22 ou mais recente

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

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

Inicialize o projeto e instale o SDK

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

  1. Abra um terminal e crie 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 usando este comando:

    code .

Importar as bibliotecas necessárias

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

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

Implementar o EchoAgent como um AgentApplication

No index.mjs, adicione o seguinte código para criar a EchoAgent extensão do AgentApplication e implementar 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)
  }
}

Inicie o servidor Web para ouvir 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()))

Execute o agente localmente em modo anónimo

A partir do seu terminal, execute este comando:

node index.mjs

O terminal deve devolvê-lo:

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

Testar o agente ao nível local

  1. A partir de 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 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 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 teamsapptester comando abre o navegador padrão e se conecta ao agente.

O seu agente no parque de diversões dos agentes

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ê através da criação de um agente de mecanismo personalizado que responde com qualquer mensagem que você enviar a ele.

Pré-requisitos

  • .NET 8.0 SDK ou mais recente

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

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

Inicialize o projeto e instale o SDK

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

  1. Abra um terminal e crie 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 .

Importar as bibliotecas necessárias

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

Em Program.cs, após as using instruções, adicione o seguinte código para criar a EchoAgentextensão AgentApplication e implemente rotas 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 agente

Em Program.cs, após as using instruções, adicione o seguinte código para configurar o alojamento web, registar 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();

Configure o servidor web para ouvir no localhost:3978

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

Execute o agente localmente em modo anónimo

A partir do 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 ao nível local

  1. A partir de outro terminal (para manter o agente a funcionar), 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 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 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 teamsapptester comando abre o navegador padrão e se conecta ao agente.

O seu agente no parque de diversões dos agentes

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

Próximos passos

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

  • Last updated on