快速入门：创建并测试基本智能体

本快速入门将指导你创建一个自定义引擎智能体，它会回复你发送的任何消息。

必备条件

Python 3.9 或更高版本。
- 若要安装 Python，请前往 https://www.python.org/downloads/，并按照你的操作系统的说明进行操作。
- 若要验证版本，请在终端窗口中键入 python --version。
任意代码编辑器。这些说明使用 Visual Studio Code。

如果您使用 Visual Studio Code，请安装 Python 扩展

初始化项目并安装 SDK

创建 Python 项目并安装所需的依赖项。

打开一个终端并创建一个新文件夹
```
mkdir echo
cd echo
```
在 Visual Studio Code 中使用以下命令打开该文件夹：
```
code .
```
使用你选择的方法创建虚拟环境，并通过 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
安装智能体 SDK

使用 pip 安装 microsoft-agents-hosting-aiohttp 包，命令如下：
```
pip install microsoft-agents-hosting-aiohttp
```

创建服务器应用程序并导入所需的库

创建名为 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 函数，我们将在下一个文件中使用它。

在同一目录中，创建一个名为 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

将智能体实例创建为 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}")

启动 Web 服务器来在 localhost:3978 中侦听

在 app.py 文件的结尾，使用 start_server 启动 Web 服务器。

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

在本地以匿名模式运行智能体

在终端中，运行以下命令：

python app.py

终端应返回以下信息：

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

本地测试智能体

在另一个终端（以保持智能体运行）中，使用以下命令安装 Microsoft 365 智能体操场：
```
npm install -g @microsoft/teams-app-test-tool
```
备注

此命令使用 npm，因为无法通过 pip 使用 Microsoft 365 智能体操场。

终端应返回如下内容：
```
added 1 package, and audited 130 packages in 1s

19 packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities
```

运行测试工具，使用以下命令与你的智能体交互：

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 命令会打开你的默认浏览器并连接到你的智能体。

您在智能体操场中的智能体

现在你可以发送任何消息以查看回声回复，或者发送消息 /help，以了解该消息如何被路由到 _help 处理程序。

本快速入门将指导你创建一个自定义引擎智能体，它会回复你发送的任何消息。

必备条件

Node.js v22 或更高版本
- 要安装 Node.js，请转到 nodejs.org，并按照您的操作系统的说明进行操作。
- 若要验证版本，请在终端窗口中键入 node --version。
任意代码编辑器。这些说明使用 Visual Studio Code。

初始化项目并安装 SDK

使用 npm 初始化 node.js 项目，创建 package.json 并安装所需依赖项

打开一个终端并创建一个新文件夹
```
mkdir echo
cd echo
```
初始化 node.js 项目
```
npm init -y
```

安装智能体 SDK

npm install @microsoft/agents-hosting-express

在 Visual Studio Code 中使用以下命令打开该文件夹：
```
code .
```

导入所需的库

创建文件 index.mjs，并在你的应用程序代码中导入以下 NPM 包：

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

启动 Web 服务器来在 localhost:3978 中侦听

在 index.mjs 结束时，使用基于 express 的 startServer 启动 Web 服务器，使用 MemoryStorage 作为轮次状态存储。

startServer(new EchoAgent(new MemoryStorage()))

在本地以匿名模式运行智能体

在终端中，运行以下命令：

node index.mjs

终端应该会输出如下内容：

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

本地测试智能体

在另一个终端（以保持智能体运行）中，使用以下命令安装 Microsoft 365 智能体操场：

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

运行测试工具，使用以下命令与你的智能体交互：

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 命令会打开你的默认浏览器并连接到你的智能体。

您在智能体操场中的智能体

现在你可以发送任何消息以查看回声回复，或者发送消息 /help，以了解该消息如何被路由到 _help 处理程序。

本快速入门将指导你创建一个自定义引擎智能体，它会回复你发送的任何消息。

必备条件

.NET 8.0 SDK 或更高版本
- 要安装 .NET SDK，请转到 dotnet.microsoft.com，并根据你的操作系统说明进行操作。
- 若要验证版本，请在终端窗口中键入 dotnet --version。
任意代码编辑器。这些说明使用 Visual Studio Code。

初始化项目并安装 SDK

使用 dotnet 创建新的 Web 项目并安装所需的依赖项。

打开一个终端并创建一个新文件夹
```
mkdir echo
cd echo
```
初始化 .NET 项目
```
dotnet new web
```

安装智能体 SDK

dotnet add package Microsoft.Agents.Hosting.AspNetCore

在 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 语句之后，添加以下代码以创建 EchoAgent 扩展 AgentApplication，并实现路由以响应事件：

对话更新
任何其他活动

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 服务器并注册智能体应用程序

在 Program.cs 中，在 using 语句之后，添加以下代码以配置 Web 主机、注册智能体，并映射 /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();

设置 Web 服务器以在 localhost:3978 中侦听

在 launchSettings.json 中，将 applicationURL 更新为http://localhost:3978，以便应用监听正确的端口。

在本地以匿名模式运行智能体

在终端中，运行以下命令：

dotnet run

终端应返回如下内容：

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

本地测试智能体

在另一个终端（以保持智能体运行）中，使用以下命令安装 Microsoft 365 智能体操场：
```
npm install -g @microsoft/teams-app-test-tool
```
备注

此命令使用 npm，因为 Microsoft 365 智能体操场是以 npm 包的形式分发的。

终端应返回如下内容：
```
added 1 package, and audited 130 packages in 1s

19 packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities
```

运行测试工具，使用以下命令与你的智能体交互：

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 命令会打开你的默认浏览器并连接到你的智能体。

您在智能体操场中的智能体

在文本输入框中输入并发送任意消息，以查看回显回复。

后续步骤

如果您已经使用 Microsoft 365 智能体工具包，默认可以使用智能体操场。如果您想开始使用该工具包，可以参考以下任一指南：

反馈

此页面是否有帮助？

Last updated on 2026-07-29

快速入门：创建并测试基本智能体

必备条件

初始化项目并安装 SDK

创建服务器应用程序并导入所需的库

将智能体实例创建为 AgentApplication

启动 Web 服务器来在 localhost:3978 中侦听

在本地以匿名模式运行智能体

本地测试智能体

必备条件

初始化项目并安装 SDK

导入所需的库

将 EchoAgent 实现为 AgentApplication

启动 Web 服务器来在 localhost:3978 中侦听

在本地以匿名模式运行智能体

本地测试智能体

必备条件

初始化项目并安装 SDK

导入所需的库

将 EchoAgent 实现为 AgentApplication

设置 Web 服务器并注册智能体应用程序

设置 Web 服务器以在 localhost:3978 中侦听

在本地以匿名模式运行智能体

本地测试智能体

后续步骤

反馈

其他资源