在 Teams 中创建代理配置体验

代理配置体验允许用户在安装后直接在频道或群聊范围内设置和重新配置其代理的设置。这从一开始就提高了代理的操作效率。代理配置体验无需重复的用户干预，这些干预以前会阻碍应用的及时优势，从而影响用户体验。

借助代理配置体验，可以确保代理的持续相关性和价值，因为用户可以：

在安装过程中，根据代理的特定工作流和首选项定制代理。
重新配置设置，以适应安装后不断变化的要求。

例如，最初可以设置跟踪和共享新闻主题或监视 GitHub 存储库的代理，以匹配用户工作流。稍后，可以轻松地重新配置它以直接从群组聊天响应新主题或存储库，从而简化内容管理和交互，而无需离开 Teams 环境。这种灵活的配置体验通过将代理无缝集成到日常操作中，显著提高了用户体验和工作效率。

下面是一个示例，其中用户将代理添加到群聊，然后将其配置为符合其特定要求。然后，用户重新配置代理以更改状态。

配置

显示向群聊添加代理并在安装期间配置代理设置的图形表示形式。

配置

显示消息撰写区域中代理的配置选项的图形表示形式。

若要将代理配置为支持机器人和选项卡功能的应用的默认登陆功能，请参阅配置默认登陆功能。

生成代理配置体验

注意

仅在频道或群组聊天中支持代理配置体验。

生成代理配置体验时，必须确保用户必须能够在首次安装时配置代理，并随时重新配置代理。

若要生成代理配置体验，请执行以下步骤：

更新应用清单
配置机器人

更新应用清单

在应用清单 (以前称为 Teams 应用清单) 文件中，按如下所示更新 fetchTask 对象下的 bots.configuration 属性：

"bots": [
    {
      "botId": "${{AAD_APP_CLIENT_ID}}",
     "needsChannelSelector": false,
      "scopes": [
        "personal",
        "team",
        "groupChat"
      ],
      "configuration":{
        "groupChat":{
          "fetchTask": true
        },
        "team":{
          "fetchTask": true
        }
      },
      "isNotificationOnly": false
    }
  ],

有关详细信息，请参阅应用清单架构。

我遇到了问题

配置代理

当用户在频道或群组聊天中安装代理时， fetchTask 应用清单文件中的属性将 config.fetch 启动或 config.submit。

如果将应用清单中的属性设置为 fetchTask ：

false：代理不提取对话或自适应卡片。相反，代理必须提供在调用代理时使用的静态对话或卡。有关详细信息，请参阅对话框。
true：代理按定义启动 config.fetch 或 config.submit 。调用代理时，可以根据 channelData 和 userdata 中提供的上下文返回自适应卡片或对话框。

下表列出了与调用请求关联的响应类型：

调用请求	响应类型
`config.fetch`	`Type: "continue"` 或 `Type = "auth"`
`config.submit`	`Type: "continue"` 或 `Type: "message"`

type: "continue"： type: "continue" 用于在代理配置中定义对话或自适应卡片的延续。当类型设置为 continue时，它指示代理希望用户进行进一步的交互，以继续执行配置过程。

当用户提交配置时，将 config.submit 触发调用。它读取用户的输入并返回不同的自适应卡片。还可以更新代理配置以返回对话框。


app.OnConfigFetch(async (context) =>
{
 var card = new AdaptiveCard
 {
     Body = new List<CardElement>
     {
         new TextBlock("Configure your agent")
         {
             Weight = TextWeight.Bolder
         }
     },
     Actions = new List<Action>
     {
         new SubmitAction
         {
             Title = "Submit"
         }
     }
 };
 var taskInfo = new TaskInfo
 {
     Title = "test card",
     Width = new Union<int, Size>(600),
     Height = new Union<int, Size>(500),
     Card = new Attachment
     {
         ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
         Content = card
     }
 };
 return new ConfigTaskResponse(
     new ContinueTask(taskInfo)
 );
});

app.on('config.fetch', async ({ activity }) => {
const card = new AdaptiveCard(
 {
   type: 'TextBlock',
   text: 'Configure your agent',
   weight: 'Bolder',
 }
).withActions(
 new SubmitAction().withTitle('Submit')
);
return {
 config: {
   type: 'continue',
   value: {
     card: cardAttachment('adaptive', card),
     height: 500,
     width: 600,
     title: 'test card',
   },
 },
};
});

@app.on_config_open
async def handle_config_open(
 ctx: ActivityContext[ConfigFetchInvokeActivity]
) -> ConfigInvokeResponse:
 card = AdaptiveCard(
     body=[
         TextBlock(text="Configure your agent", weight="Bolder")
     ],
     actions=[
         SubmitAction(title="Submit")
     ]
 )

 return ConfigResponse(
     config=TaskModuleContinueResponse(
         value=CardTaskModuleTaskInfo(
             card=card_attachment(AdaptiveCardAttachment(content=card)),
             height=500,
             width=600,
             title="test card",
         )
     )
 )

type: "auth"：还可以请求用户进行身份验证，作为对请求的 config.fetch 响应。该 type: "auth" 配置提示用户通过指定的 URL 登录，该 URL 必须链接到可在浏览器中打开的有效身份验证页。身份验证对于代理要求对用户进行身份验证的方案至关重要。它确保验证用户的标识，维护安全，并在代理的功能中提供个性化体验。

注意

仅 type: "auth" 支持第三方身份验证。不支持单一登录 (SSO) 。有关第三方身份验证的详细信息，请参阅添加身份验证。


app.OnConfigFetch(async (context) =>
{
 return new ConfigAuthResponse(
     new ConfigAuth
     {
         SuggestedActions = new SuggestedActions
         {
             Actions = new List<CardAction>
             {
                 new CardAction
                 {
                     Type = "openUrl",
                     Value = "https://example.com/auth",
                     Title = "Sign in to this app"
                 }
             }
         }
     }
 );
});

app.on('config.fetch', async ({ activity }) => {
return {
 config: {
   type: 'auth',
   suggestedActions: {
     actions: [
       {
         type: 'openUrl',
         value: 'https://example.com/auth',
         title: 'Sign in to this app',
       },
     ],
   },
 },
};
});

@app.on_config_open
async def handle_config_open(
 ctx: ActivityContext[ConfigFetchInvokeActivity]
) -> ConfigInvokeResponse:
 return ConfigResponse(
     config=ConfigAuth(
         suggested_actions=SuggestedActions(
             to=[],
             actions=[
                 CardAction(
                     type="openUrl",
                     value="https://example.com/auth",
                     title="Sign in to this app",
                 )
             ],
         )
     )
 )

type="message"：当类型设置为 message 时，它指示代理正在向用户发送一条简单的消息，指示交互的结束或提供信息，而无需进一步输入。


app.OnConfigSubmit(async (context) =>
{
 return new ConfigTaskResponse(
     new MessageTask("You have chosen to finish setting up agent")
 );
});

app.on('config.submit', async ({ activity, send }) => {
return {
 config: {
   type: 'message',
   value: 'You have chosen to finish setting up agent',
 },
};
});

@app.on_config_submit
async def handle_config_submit(
 ctx: ActivityContext[ConfigSubmitInvokeActivity]
) -> ConfigInvokeResponse:
 return ConfigResponse(
     config=TaskModuleMessageResponse(
         value="You have chosen to finish setting up agent",
     )
 )

当用户重新配置代理时， fetchTask 应用清单文件中的属性将在 config.fetch 代理逻辑中启动。用户可以在安装后通过两种方式重新配置代理设置：

@mention 消息撰写区域中的代理。选择邮件撰写区域上方显示的 “设置” 选项。对话框中将显示一个对话框，更新或更改代理的配置设置。
将鼠标悬停在代理上，将显示代理配置文件卡。若要更新或更改代理的配置设置，请选择代理配置文件卡中的设置图标。

我遇到了问题

最佳做法

如果想要具有代理的单个通道级配置，请确保根据通道跟踪配置。不会存储配置数据，并且调用有效负载包括足够的 channelData。
提供清晰且用户友好的对话框，提示用户输入代理正常运行所需的信息，例如 URL、区域路径或仪表板链接。
避免在安装后发送多个通知或配置请求，因为这可能会让用户感到困惑。

代码示例

示例名称	说明	.NET	Node.js	清单
代理配置应用	此示例演示用于在团队和群组聊天中配置和重新配置自适应卡片的代理。	View	View	View
具有身份验证的代理配置应用	此 Teams 代理支持在自适应卡片上使用动态搜索功能进行配置和重新配置。	View	View	View

另请参阅

反馈

此页面是否有帮助？

Last updated on 2026-07-28