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
   

Criar uma instância do Agent como um 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

Faça correr o Agente localmente no 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.

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.

Próximos passos

Provisionar recursos de Bot do Azure para usar com o SDK de Agentes

Este início rápido orienta-o através da criação de um agente de motor personalizado que apenas responde com o que enviar para 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:

• @microsoft/agentes-de-hospedagem
• @microsoft/agentes-hosting-express

// 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()))

Faça correr o Agente localmente no 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.

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.

Próximos passos

Provisionar recursos de Bot do Azure para usar com o SDK de Agentes

Este quickstart mostra-te como descarregar e executar o exemplo do QuickStart/Empty Agent do GitHub.

Há duas maneiras principais de começar a usar o SDK do Microsoft 365 Agents:

• Clone e execute o exemplo de agente QuickStart/Empty Agent disponível no GitHub

• Utilize o Microsoft 365 Agents Toolkit. O Kit de Ferramentas de Agentes possui dois modelos internos para o Visual Studio e o Visual Studio Code que utilizam o SDK de Agentes Microsoft 365 para iniciar com um Agente de Início Rápido/Vazio ou um Agente Meteorológico que emprega o Azure Foundry ou os Serviços OpenAI, utilizando tanto o Kernel Semântico quanto o LangChain.

Pré-requisitos

Você precisa de algumas coisas antes de começar. Essas etapas usam o exemplo de início rápido/agente vazio no início rápido do .NET, mas você também pode usar qualquer exemplo do SDK de agentes.

• SDK do .NET 8.0
• Visual Studio ou Visual Studio Code
• Conhecimento de ASP.NET Core e programação assíncrona em C#
• Baixe o quickstart exemplo do GitHub

Abra a solução

1. Abra o arquivo de QuickStart.csproj solução no Visual Studio.

2. Execute o projeto.

Neste ponto, o seu agente está a ser executado localmente utilizando a porta 3978.

Teste o seu agente localmente

1. Instale o Agents Playground , se ainda não o fez.

   winget install agentsplayground
   

2. Inicie o agente no Visual Studio ou Visual Studio Code

3. Inicie o teste de aplicações do Teams. Numa linha de comandos: agentsplayground

   • A ferramenta abre um navegador da Web mostrando a Ferramenta de Teste do Aplicativo Teams, pronta para enviar mensagens ao seu agente.

4. Seu agente em execução na porta 3978 deve se conectar automaticamente ao playground do agente em seu navegador e você deve ser capaz de interagir com seu agente em execução localmente

Como funciona o agente?

Com o SDK de agentes, um agente é criado usando as classes AgentApplication e AgentApplicationOptions . Isso é construído no Program.cs arquivo do exemplo.

Crie o seu agente

Você pode ver no exemplo que, à medida que o agente está sendo construido, AgentApplicationOptions está carregado e a sua classe de agente personalizada MyAgent.cs que herda de AgentApplication.

// Add AgentApplicationOptions from appsettings section "AgentApplication".
builder.AddAgentApplicationOptions();

// Add the AgentApplication, which contains the logic for responding to
// user messages.
builder.AddAgent<MyAgent>();

Em seguida, o armazenamento é carregado por padrão usando a classe MemoryStorage. Isso permite o rastreamento de contexto entre turnos ao usar TurnState; no entanto, deve ser substituído na produção por um armazenamento mais persistente, como por exemplo, BlobsStorage ou CosmosDbPartitionedStorage.

builder.Services.AddSingleton<IStorage, MemoryStorage>();

O restante do aplicativo agente usa padrões de hospedagem .NET padrão e adiciona rotas para aceitar mensagens em um ponto de extremidade específico. Essas rotas usam a interface IAgent para aceitar a atividade do agente e fornecem aos desenvolvedores o AgentApplication objeto para trabalhar com a carga útil da atividade que foi passada para ele a partir do canal/cliente. Saiba mais sobre as Atividades e sobre como trabalhar com Atividades

// This receives incoming messages from Azure Bot Service or other SDK Agents
var incomingRoute = app.MapPost("/api/messages", async (HttpRequest request, HttpResponse response, IAgentHttpAdapter adapter, IAgent agent, CancellationToken cancellationToken) =>
{
    await adapter.ProcessAsync(request, response, agent, cancellationToken);
});

Adicionar nova lógica personalizada em um método

Os desenvolvedores adicionam lógica personalizada na classe MyAgent.cs que implementa AgentApplication. Essa classe utiliza o AgentApplicationOptions para configurar quaisquer definições específicas do seu ficheiro de configuração e Program.cs regista ouvintes de eventos do SDK de Agentes, disponível na classe que faz referência ao seu método personalizado respetivo quando esses eventos são acionados a partir do cliente.

No exemplo a seguir, OnConversationUpdate dispara o WelcomeMessageAsync método e OnActivity dispara o método OnMessageAsync.

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

Esses eventos são roteados através do ponto de extremidade configurado em seu MyProgram.cs e há vários eventos que você pode usar. O mais comum é OnActivity. Para saber mais sobre os eventos que o SDK implementa, confira mais sobre como trabalhar com atividades e a especificação do protocolo de atividade.

Depois que o seu método é ativado, por exemplo OnMessageAsync para encerrar o turno, você pode optar, na sua lógica personalizada, por enviar uma mensagem de volta ao cliente usando os métodos disponíveis em uma instância da classe TurnContext, que deve ser um parâmetro no seu método, conforme mostrado no exemplo a seguir:

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

Sugestão

Analise os outros métodos TurnContext disponíveis para retornar ao cliente.

Agora que você já sabe o básico, confira as próximas etapas e trabalhe para adicionar a lógica do manipulador personalizado ao seu agente e enviar de volta eventos diferentes.

Próximas Etapas

• Saiba mais sobre as Atividades e sobre como trabalhar com Atividades
• Revise os eventos do AgentApplication aos quais pode responder a partir do cliente
• Revise os eventos TurnContext que você pode enviar de volta ao cliente
• Provisionar recursos de Bot do Azure para usar com o SDK de Agentes
• Configure seu Agente .NET para usar OAuth

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:

• Criar agentes .NET no Visual Studio usando o Microsoft 365 Agents Toolkit
• Criar agentes JavaScript no Visual Studio Code com o Microsoft 365 Agents Toolkit