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.

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

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.

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

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

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.

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

Abra um terminal e crie uma nova pasta
```
mkdir echo
cd echo
```
Inicializar o projeto 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 .
```

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

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

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

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.

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

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

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

Teste o seu agente localmente

Instale o Agents Playground , se ainda não o fez.
```
winget install agentsplayground
```
Inicie o agente no Visual Studio ou Visual Studio Code
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.
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

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:

Feedback

Esta página foi útil?

Last updated on 2025-11-18

Partilhar via

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

Pré-requisitos

Inicialize o projeto e instale o SDK

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

Criar uma instância do Agent como um AgentApplication

Inicie o servidor Web para ouvir em localhost:3978

Faça correr o Agente localmente no modo anônimo

Testar o agente ao nível local

Próximos passos

Pré-requisitos

Inicialize o projeto e instale o SDK

Importar as bibliotecas necessárias

Implementar o EchoAgent como um AgentApplication

Inicie o servidor Web para ouvir em localhost:3978

Faça correr o Agente localmente no modo anônimo

Testar o agente ao nível local

Próximos passos

Pré-requisitos

Abra a solução

Teste o seu agente localmente

Como funciona o agente?

Crie o seu agente

Adicionar nova lógica personalizada em um método

Próximas Etapas

Feedback

Recursos adicionais