快速入門：建立和測試基本 Agent

本快速入門將引導您建立一個自訂引擎 Agent，它會回覆您傳送的任何訊息。

先決條件

• Python 3.9 或更新版本。

  • 若要安裝 Python，請移至https://www.python.org/downloads/，並依照作業系統的指示操作。
  • 若要確認版本，請在終端機視窗中輸入 python --version。

• 您可以自行選擇程式碼編輯器。 這些指示使用 Visual Studio Code。

  如果您使用 Visual Studio Code，請安裝 Python 擴充功能

初始化專案並安裝 SDK

建立一個 Python 專案並安裝所需的相依性。

1. 開啟終端機並建立新資料夾

   mkdir echo
   cd echo
   

2. 使用以下命令在 Visual Studio Code 中開啟資料夾：

   code .
   

3. 使用您選擇的方法建立虛擬環境，然後在 Visual Studio Code 或終端機中啟用它。

   在使用 Visual Studio Code 時，如果已安裝 Python 擴充功能，即可使用這些步驟。

   1. 按 F1，輸入 Python: Create environment，然後按 Enter。

      1. 選取 Venv 以在目前工作區中建立 .venv 虛擬環境。

      2. 選取一個 Python 安裝版本來建立虛擬環境。

         該值可能如下所示：

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

4. 安裝 Agents SDK

   使用 pip 並透過以下命令來安裝 microsoft-agents-hosting-aiohttp 套件：

   pip install microsoft-agents-hosting-aiohttp
   

建立伺服器應用程式並匯入所需的函式庫

1. 建立一個名為 start_server.py 的檔案，複製以下程式碼，再貼到：

   # 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
   

   這段程式碼定義一個我們將會在下一個檔案中使用的 start_server函式。

2. 在相同目錄中，使用以下程式碼，建立名為 app.py 的檔案。

   # 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
   

將 Agent 的執行個體建立為 AgentApplication

在 app.py 中，新增以下程式碼以建立 AGENT_APP 作為 AgentApplication 的執行個體，並實作三個路由以回應三個事件：

• 交談更新
• 訊息 /help
• 任何其他活動

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

啟動網頁伺服器以在 localhost:3978 監聽

在app.py結尾，使用 start_server 啟動網頁伺服器。

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

以匿名模式在本機執行 Agent

在終端機中，執行以下命令：

python app.py

終端機應傳回以下內容：

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

在本機測試 Agent

1. 從另一個終端機 (讓 Agent 持續執行)，使用下列命令安裝 Microsoft 365 Agents 遊樂場：

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

   注意

   此命令使用 npm，因為 Microsoft 365 Agents 遊樂場無法透過使用 pip 提供。

   終端機應該會傳回類似這樣的訊息：

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. 執行測試工具，使用以下命令與您的 Agent 互動：

   teamsapptester
   

   終端機應該會傳回類似這樣的訊息：

   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\"}"}}
   

teamsapptester 命令會開啟您的預設瀏覽器並連接到您的 Agent。

現在您可以發送任何訊息來查看回聲回覆，或發送訊息 /help 來查看該訊息如何路由到 _help 處理常式。

本快速入門將引導您建立一個自訂引擎 Agent，它會回覆您傳送的任何訊息。

先決條件

• Node.js v22 或更新版本

  • 若要安裝 Node.js，請移至 nodejs.org，並根據您的作業系統指示進行操作。
  • 若要驗證版本，請在終端機視窗中輸入 node --version。

• 您可以自行選擇程式碼編輯器。 這些指示使用 Visual Studio Code。

初始化專案並安裝 SDK

使用 npm 來初始化 node.js 專案，方法是建立一個 package.json 並安裝所需的相依性

1. 開啟終端機並建立新資料夾

   mkdir echo
   cd echo
   

2. 初始化 Node.js 專案

   npm init -y
   

3. 安裝 Agents SDK

   npm install @microsoft/agents-hosting-express
   

4. 請使用以下命令以 Visual Studio Code 開啟資料夾：

   code .
   

匯入必要的程式庫

建立檔案 index.mjs 並匯入以下 NPM 套件到您的應用程式碼中：

• @microsoft/agents-hosting
• @microsoft/agents-hosting-express

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

將 EchoAgent 實作為 AgentApplication

在 index.mjs 中，新增以下程式碼已建立 EchoAgent，延伸 AgentApplication，並實作三個路由以回應三個事件：

• 交談更新
• 訊息 /help
• 任何其他活動

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

啟動網頁伺服器以在 localhost:3978 監聽

在 index.mjs 結尾，根據使用 MemoryStorage 做為交談回合狀態儲存體的運算式，使用 startServer 來啟動 Web 伺服器。

startServer(new EchoAgent(new MemoryStorage()))

以匿名模式在本機執行 Agent

在終端機中，執行以下命令：

node index.mjs

終端機應該會傳回以下訊息：

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

在本機測試 Agent

1. 從另一個終端機 (讓 Agent 持續執行)，使用下列命令安裝 Microsoft 365 Agents 遊樂場：

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

   終端機應該會傳回類似這樣的訊息：

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. 執行測試工具，使用以下命令與您的 Agent 互動：

   node_modules/.bin/teamsapptester
   

   終端機應該會傳回類似這樣的訊息：

   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\"}"}}
   

teamsapptester 命令會開啟您的預設瀏覽器並連接到您的 Agent。

現在您可以發送任何訊息來查看回聲回覆，或發送訊息 /help 來查看該訊息如何路由到 _help 處理常式。

本快速入門將引導您建立一個自訂引擎 Agent，它會回覆您傳送的任何訊息。

先決條件

• .NET 8.0 SDK 或更新版本

  • 若要安裝.NET SDK，請移至 dotnet.microsoft.com，並依照作業系統的指示操作。
  • 若要驗證版本，請在終端機視窗中輸入 dotnet --version。

• 您可以自行選擇程式碼編輯器。 這些指示使用 Visual Studio Code。

初始化專案並安裝 SDK

使用 dotnet 來建立新的 Web專案並安裝必要的相依性。

1. 開啟終端機並建立新資料夾

   mkdir echo
   cd echo
   

2. 初始化 .NET 專案

   dotnet new web
   

3. 安裝 Agents SDK

   dotnet add package Microsoft.Agents.Hosting.AspNetCore
   

4. 使用以下命令在 Visual Studio Code 中開啟資料夾：

   code .
   

匯入必要的程式庫

在 Program.cs 中取代現有內容，並新增以下 using 語句以將 SDK 套件匯入您的應用程式碼：

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

將 EchoAgent 實作為 AgentApplication

在 Program.cs 中，於 using 語句之後，加入以下程式碼以建立繼承自 AgentApplication 的 EchoAgent，並實作路由以回應事件：

• 交談更新
• 其他任何活動

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);
   }
}

設定 Web 伺服器並註冊 Agent 應用程式

在 Program.cs 中，於 using 語句之後，新增以下程式碼以設定網頁伺服器、註冊 Agent，並對應 /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();

設定網頁伺服器以監聽 localhost:3978

在 launchSettings.json 中，將 applicationURL 更新為 http://localhost:3978，以便應用程式能監聽正確的埠號。

以匿名模式在本機執行 Agent

在終端機中，執行以下命令：

dotnet run

終端機應該會傳回類似這樣的訊息：

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

在本機測試 Agent

1. 從另一個終端機 (讓 Agent 持續執行)，透過下列命令安裝 Microsoft 365 Agents 遊樂場：

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

   注意

   此命令使用 npm，因為 Microsoft 365 Agent 遊樂場是以 npm 套件形式發行。

   終端機應該會傳回類似這樣的訊息：

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. 執行測試工具，使用以下命令與您的 Agent 互動：

   teamsapptester
   

   終端機應該會傳回類似這樣的訊息：

   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\"}"}}
   

teamsapptester 命令會開啟您的預設瀏覽器並連接到您的 Agent。

在文字輸入方塊中輸入並發送任何訊息，即可看到回聲回覆。

後續步驟

• 在 GitHub 上檢視 Agents SDK 樣本
• 深入了解 Activities 以及 Activities 的操作方法
• 審查您可以從用戶端回應的 AgentApplication 事件
• 審查您可以回傳至用戶端的 TurnContext 事件
• 佈建要與 Agents SDK 搭配使用的 Azure 機器人資源
• 設定您的 .NET Agent 使用 OAuth

如果您已經使用 Microsoft 365 Agent 工具組，Agent 遊樂場預設啟用。 如果您想開始使用工具組，您可以參考以下任一指南：

• 使用 Microsoft 365 Agent 工具組建立 Visual Studio 中的 .NET Agent
• 使用 Microsoft 365 Agent 工具組建立 Visual Studio Code 中的 JavaScript Agent