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

本快速入门将指导你创建一个自定义引擎代理，该代理会回复你向其发送的任何消息。

先决条件

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 Agents Playground ：
```
npm install -g @microsoft/teams-app-test-tool
```
注释

此命令使用 npm，因为 Microsoft 365 Agents Playground 无法使用 pip。

终端应返回如下所示的内容：
```
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 处理程序的。

后续步骤

预配 Azure 机器人服务以与代理 SDK 配合使用

本快速入门将指导你创建一个自定义引擎代理，该代理只需答复发送给它的任何内容。

先决条件

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

初始化项目并安装 SDK

用于 npm 通过创建 package.json 并安装所需的依赖项来初始化 node.js 项目

打开终端并创建新文件夹
```
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 Agents Playground ：

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 处理程序的。

后续步骤

预配 Azure 机器人服务以与代理 SDK 配合使用

这个快速入门工具展示了如何从GitHub下载并运行QuickStart/Empty Agent示例。

可通过两种主要方法开始使用 Microsoft 365 代理 SDK：

克隆并运行 GitHub 上提供的快速入门/空代理代理示例
使用 Microsoft 365 代理工具包。 Agents Toolkit 有两个适用于 Visual Studio 和 Visual Studio Code 的内置模板，这些模板使用 Microsoft 365 代理 SDK，以便从快速入门/空代理开始，以及将 Azure Foundry 或 OpenAI 服务与语义内核或 LangChain 配合使用的天气代理。

先决条件

在开始之前你需要一些东西。这些步骤使用 .NET 快速入门中的快速入门/空代理示例，但也可以使用任何代理 SDK 示例。

打开解决方案

在 Visual Studio 中打开解决方案文件 QuickStart.csproj 。
启动项目。

此时您的智能体已在本地端口 3978 运行。

在本地测试代理

安装 Agents Playground （如果尚未安装）。
```
winget install agentsplayground
```
在 Visual Studio 或 Visual Studio Code 中启动代理
启动 Teams 应用测试器。在命令提示：agentsplayground
- 该工具将打开一个 Web 浏览器，其中显示了 Teams 应用测试工具，可以向代理发送消息。
端口 3978 上运行的代理应自动连接到浏览器中的代理场，并且应该能够与本地运行的代理进行交互

代理的工作原理是什么？

使用 Agents SDK 时，代理是使用 AgentApplication 和 AgentApplicationOptions 类生成的。这是在 Program.cs 示例文件中生成的。

生成智能体

您可以在示例中看到，在AgentApplicationOptions代理生成过程中，它会被加载，同时自定义代理类MyAgent.cs从AgentApplication继承。

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

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

然后，默认情况下使用 MemoryStorage 类加载存储。这允许在使用 TurnState 时跨轮次跟踪上下文，但在生产环境中应切换为更为持久的存储解决方案，例如 BlobsStorage 或 CosmosDbPartitionedStorage。

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

代理应用程序的其余部分使用标准 .NET 托管模式，并添加路由以接受特定终结点的消息。这些路由使用 IAgent 接口来接受代理活动，并向开发人员提供 AgentApplication 对象，以便处理从通道或客户端传递来的 Activity 有效负载。进一步了解活动及与活动的交互

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

在方法中添加新的自定义逻辑

开发人员在实现MyAgent.cs的AgentApplication类中添加自定义逻辑。此类使用来配置您配置中的任何特定设置，并从中注册事件监听器，当从客户端触发这些事件时，类会引用您相应的自定义方法。

在以下示例中， OnConversationUpdate 触发 WelcomeMessageAsync 该方法， OnActivity 触发该方法 OnMessageAsync。

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

这些事件通过配置在 MyProgram.cs 的终端中进行路由，并且有许多事件可以使用。最常见的是 OnActivity。若要详细了解 SDK 实现的事件，请查看有关使用活动和活动协议规范的详细信息。

触发方法（例如 OnMessageAsync 结束轮次）后，可以在自定义逻辑中选择，以使用在方法中可用的方法和 TurnContext 类的实例（应为方法中的参数）来响应将消息发送回客户端，如以下示例所示：

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

小窍门

查看可用于返回到客户端的其他 TurnContext 方法。

现在，你已了解基础知识，请查看后续步骤，并努力将自定义处理程序逻辑添加到代理中并发送回不同的事件。

后续步骤

如果已在使用 Microsoft 365 代理工具包，则默认情况下可以使用 Agents Playground。若要开始使用工具包，可以使用以下指南之一：

反馈

此页面是否有帮助？

Last updated on 2025-11-18

通过

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

先决条件

初始化项目并安装 SDK

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

将代理创建为AgentApplication实例

启动 Web 服务器以在 localhost:3978 上侦听

以匿名模式在本地运行代理

在本地测试代理

后续步骤

先决条件

初始化项目并安装 SDK

导入所需的库

将 EchoAgent 作为 AgentApplication 实现

启动 Web 服务器以在 localhost:3978 上侦听

以匿名模式在本地运行代理

在本地测试代理

后续步骤

先决条件

打开解决方案

在本地测试代理

代理的工作原理是什么？

生成智能体

在方法中添加新的自定义逻辑

后续步骤

反馈

其他资源