add-mcscopilot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

📋 Shared Instructions: shared-instructions.md - Cross-cutting concerns.

📋 通用说明：shared-instructions.md - 跨领域相关事项。

Add Microsoft Copilot Studio

添加Microsoft Copilot Studio连接器

Workflow

操作流程

Check Memory Bank → 2. Add Connector → 3. Configure → 4. Build → 5. Update Memory Bank

检查Memory Bank → 2. 添加连接器 → 3. 配置 → 4. 构建 → 5. 更新Memory Bank

Step 1: Check Memory Bank

步骤1：检查Memory Bank

Check for

memory-bank.md

per shared-instructions.md.

根据shared-instructions.md的要求检查

memory-bank.md

文件。

Step 2: Add Connector

步骤2：添加连接器

First, find the connection ID (see connector-reference.md):

Run the

/list-connections

skill. Find the Microsoft Copilot Studio connection in the output. If none exists, direct the user to create one using the environment-specific Connections URL — construct it from the active environment ID in context (from

power.config.json

or a prior step):

https://make.powerapps.com/environments/<environment-id>/connections

→ + New connection → search for the connector → Create.

bash

pwsh -NoProfile -Command "pac code add-data-source -a microsoftcopilotstudio -c <connection-id>"

首先，找到连接ID（参考connector-reference.md）：

运行

/list-connections

技能。在输出结果中找到Microsoft Copilot Studio连接。如果不存在，请引导用户使用环境专属的连接URL创建连接——可通过上下文里的活跃环境ID（来自

power.config.json

或上一步骤）构造该URL：

https://make.powerapps.com/environments/<environment-id>/connections

→ + 新建连接 → 搜索该连接器 → 创建。

bash

pwsh -NoProfile -Command "pac code add-data-source -a microsoftcopilotstudio -c <connection-id>"

Step 3: Configure

步骤3：配置

Ask the user which Copilot Studio agent they want to invoke and what operations they need.

Agent Setup Prerequisites (manual steps the user must complete in Copilot Studio):

Publish the agent: In Copilot Studio, click Channels → select Teams → add to Teams → click Publish.
Get the agent name: Under Channels, click "Web app". The connection string URL contains the agent name. Example:
```
https://...api.powerplatform.com/copilotstudio/dataverse-backed/authenticated/bots/cr3e1_myAgent/conversations?...
```
— the agent name is
```
cr3e1_myAgent
```
.

ExecuteCopilotAsyncV2 -- execute an agent and wait for the response:

Use the

ExecuteCopilotAsyncV2

operation (path:

/proactivecopilot/executeAsyncV2

). This is the only endpoint that reliably returns agent responses synchronously. It is the same endpoint used by Power Automate's "Execute Agent and wait" action.

typescript

const result = await MicrosoftCopilotStudioService.ExecuteCopilotAsyncV2({
  message: "Your prompt or data here", // Can be a JSON string
  notificationUrl: "https://notificationurlplaceholder" // Required by API but unused; any URL works
});

// Response structure:
// result.responses — Array of response strings from the agent
// result.conversationId — The conversation ID
// result.lastResponse — The last response from the agent
// result.completed — Boolean indicating if the agent finished

Important: Agents often return responses as JSON strings. Parse the

responses

array to extract meaningful data:

typescript

const agentResponse = result.responses?.[0];
if (agentResponse) {
  const parsed = JSON.parse(agentResponse);
  // Extract specific fields, e.g., parsed.trend_summary
}

Use

Grep

to find specific methods in the generated service file (generated files can be very large — see connector-reference.md).

询问用户要调用哪个Copilot Studio Agent以及需要执行哪些操作。

Agent设置前提条件（用户必须在Copilot Studio中完成的手动步骤）：

发布Agent：在Copilot Studio中，点击“渠道” → 选择Teams → 添加到Teams → 点击“发布”。
获取Agent名称：在“渠道”下，点击“Web应用”。连接字符串URL中包含Agent名称。示例：
```
https://...api.powerplatform.com/copilotstudio/dataverse-backed/authenticated/bots/cr3e1_myAgent/conversations?...
```
—— Agent名称为
```
cr3e1_myAgent
```
。

ExecuteCopilotAsyncV2 -- 执行Agent并等待响应：

使用

ExecuteCopilotAsyncV2

操作（路径：

/proactivecopilot/executeAsyncV2

）。这是唯一能可靠同步返回Agent响应的端点，与Power Automate中的“执行Agent并等待”动作使用的是同一个端点。

typescript

const result = await MicrosoftCopilotStudioService.ExecuteCopilotAsyncV2({
  message: "Your prompt or data here", // Can be a JSON string
  notificationUrl: "https://notificationurlplaceholder" // Required by API but unused; any URL works
});

// Response structure:
// result.responses — Array of response strings from the agent
// result.conversationId — The conversation ID
// result.lastResponse — The last response from the agent
// result.completed — Boolean indicating if the agent finished

重要提示：Agent的响应通常以JSON字符串形式返回。解析

responses

数组以提取有意义的数据：

typescript

const agentResponse = result.responses?.[0];
if (agentResponse) {
  const parsed = JSON.parse(agentResponse);
  // Extract specific fields, e.g., parsed.trend_summary
}

使用

Grep

工具在生成的服务文件中查找特定方法（生成的文件可能非常大——参考connector-reference.md）。

Known Issues

已知问题

ExecuteCopilot (
```
/execute
```
) -- fire-and-forget, only returns
```
ConversationId
```
, not the actual response. Do NOT use this.
ExecuteCopilotAsync (
```
/executeAsync
```
) -- returns 502 "Cannot read server response" errors. Do NOT use this.
Conversation turn model (
```
/conversations/{ConversationId}
```
) -- only works after
```
/execute
```
, which doesn't provide responses. Do NOT use this.
Response casing varies -- check all variations:
```
conversationId
```
,
```
ConversationId
```
,
```
conversationID
```
.

ExecuteCopilot（
```
/execute
```
）——即发即弃模式，仅返回
```
ConversationId
```
，不返回实际响应。请勿使用此接口。
ExecuteCopilotAsync（
```
/executeAsync
```
）——会返回502“无法读取服务器响应”错误。请勿使用此接口。
对话轮次模型（
```
/conversations/{ConversationId}
```
）——仅在
```
/execute
```
之后可用，但
```
/execute
```
不提供响应。请勿使用此接口。
响应字段大小写不固定——请检查所有可能的大小写形式：
```
conversationId
```
、
```
ConversationId
```
、
```
conversationID
```
。

Step 4: Build

步骤4：构建

powershell

npm run build

Fix TypeScript errors before proceeding. Do NOT deploy yet.

powershell

npm run build

在继续之前修复所有TypeScript错误。请勿立即部署。

Step 5: Update Memory Bank

步骤5：更新Memory Bank

Update

memory-bank.md

with: connector added, agent name configured, configured operations, build status.

在

memory-bank.md

中更新以下内容：已添加连接器、已配置Agent名称、已配置操作、构建状态。