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.

Abrir um terminal e criar uma nova pasta
```
mkdir echo
cd echo
```
Abra a pasta usando o Visual Studio Code usando este comando:
```
code .
```
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
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

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.

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 Agente como um 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

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
```

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.

Seu agente na área de testes de 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.

Próximas etapas

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

Este guia de início rápido orienta você na criação de um agente de mecanismo personalizado que apenas responde com o 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

Abrir um terminal e criar uma nova pasta
```
mkdir echo
cd echo
```
Inicializar o projeto de node.js
```
npm init -y
```

Instalar o SDK de Agentes

npm install @microsoft/agents-hosting-express

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:

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

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

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.

Seu agente na área de testes de 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.

Próximas etapas

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

Este quickstart mostra como baixar e executar o exemplo QuickStart/Empty Agent do GitHub.

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

Clonar e executar o exemplo de agente do QuickStart/Empty Agent disponível no GitHub
Use o Kit de Ferramentas do Microsoft 365 Agents. O Kit de Ferramentas de Agentes tem dois modelos internos para Visual Studio e Visual Studio Code que usam o SDK dos Agentes do Microsoft 365 para começar com um Agente de Inicialização Rápida/Agente Vazio e um Agente Climático que usa o Azure Foundry ou os Serviços OpenAI com Kernel Semântico ou 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 do ASP.Net Core e da programação assíncrona em C#
Baixar o quickstart exemplo do GitHub

Abrir a solução

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

Neste ponto, seu agente está sendo executado localmente usando a porta 3978.

Testar localmente o agente

Instale o Agents Playground se você ainda não fez isso.
```
winget install agentsplayground
```
Iniciar o agente no Visual Studio ou no Visual Studio Code
Inicie o Testador de Aplicativos do Teams. Em um prompt de comando: agentsplayground
- A ferramenta abre um navegador da Web mostrando a Ferramenta de Teste de Aplicativo do Teams, pronta para enviar mensagens ao seu agente.
Seu agente em execução na porta 3978 deve se conectar automaticamente ao playground do agente em seu navegador e você deve poder 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 é compilado no Program.cs arquivo do exemplo.

Criar seu agente

Você pode ver no exemplo que, à medida que o agente está sendo criado, AgentApplicationOptions é carregado e sua classe de agente personalizada MyAgent.cs 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 que o contexto seja rastreado em turnos ao usar TurnState, no entanto, deve ser substituído na produção por um armazenamento mais persistente, como BlobsStorage ou CosmosDbPartitionedStorage.

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

O restante do aplicativo de 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 objeto AgentApplication para trabalhar com o payload Activity, que foi passado para ele através do canal/cliente. Saiba mais sobre as atividades e 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 uma nova lógica personalizada em um método

Os desenvolvedores adicionam lógica personalizada na MyAgent.cs classe que implementa AgentApplication. Essa classe usa o AgentApplicationOptions para configurar quaisquer configurações específicas do seu config e o Program.cs, registrando os ouvintes de eventos do SDK de Agentes, disponíveis na AgentApplication classe, que referencia seu método personalizado respectivo quando esses eventos são acionados pelo 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);
   }

Os eventos são roteados através do endpoint configurado em seu MyProgram.cs e há inúmeros eventos que você pode utilizar. 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 método é acionado, por exemplo OnMessageAsync para encerrar a jogada, você pode optar em sua lógica personalizada por responder enviando uma mensagem de volta ao cliente usando os métodos disponíveis em uma instância da classe TurnContext, que deve ser passada como 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);
}

Dica

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

Agora você conhece as noções básicas, confira as próximas etapas e trabalhe para adicionar lógica de manipulador personalizado ao seu agente e enviar eventos diferentes.

Próximas etapas

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:

Comentários

Esta página foi útil?

Last updated on 2025-11-18

Compartilhar via

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

Pré-requisitos

Inicializar o projeto e instalar o SDK

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

Criar uma instância do Agente como um AgentApplication

Inicie o servidor Web para escutar em localhost:3978

Executar o Agente localmente no modo anônimo

Testar localmente o agente

Próximas etapas

Pré-requisitos

Inicializar o projeto e instalar o SDK

Importe as bibliotecas necessárias

Implementar o EchoAgent como um AgentApplication

Inicie o servidor Web para escutar em localhost:3978

Executar o Agente localmente no modo anônimo

Testar localmente o agente

Próximas etapas

Pré-requisitos

Abrir a solução

Testar localmente o agente

Como funciona o agente?

Criar seu agente

Adicionar uma nova lógica personalizada em um método

Próximas etapas

Comentários

Recursos adicionais