共用方式為

探索語意核心 CopilotStudioAgent

這很重要

這項功能處於實驗階段。 在這個階段的功能正在開發中，在前進到預覽或發行候選階段之前，可能會變更。

如需此討論的詳細 API 檔，請參閱：

適用於 .NET 的 CopilotStudioAgent 即將推出。

即將推出更新的 API 檔。

Java 中目前無法使用的功能。

什麼是 CopilotStudioAgent？

CopilotStudioAgent是 Semantic Kernel 架構內的整合點，可讓您使用程式設計 API 與 Microsoft Copilot Studio 代理程序順暢地互動。 這個代理程式可讓您：

  • 自動化對話，並從 Python 程式代碼叫用現有的 Copilot Studio 代理程式。
  • 使用串流維護豐富的對話歷程，並在訊息間保留上下文。
  • 利用 Microsoft Copilot Studio 內提供的進階知識擷取、Web 搜尋和數據整合功能。

備註

知識來源/工具必須在 Microsoft Copilot Studio 內 設定，才能透過代理程式存取。

準備您的開發環境

若要使用 CopilotStudioAgent進行開發，您必須正確設定環境和驗證。

適用於 .NET 的 CopilotStudioAgent 即將推出。

先決條件

  1. Python 3.10 或更高版本
  2. 具有 Copilot Studio 相依性的語意核心：
pip install semantic-kernel[copilotstudio]

  1. Microsoft Copilot Studio 代理程序：

    • 在 copilot Studio Microsoft建立代理程式。
    • 發佈您的代理程式，然後在 Settings → Advanced → Metadata 底下取得：
      • Schema Name （用作 agent_identifier）
      • Environment ID

  2. 具有委派許可權的 Azure Entra ID 應用程式註冊（「原生應用程式」，用於互動式登入CopilotStudio.Copilots.Invoke。

環境變數

在您的環境或 .env 檔案中設定下列變數：

COPILOT_STUDIO_AGENT_APP_CLIENT_ID=<your-app-client-id>
COPILOT_STUDIO_AGENT_TENANT_ID=<your-tenant-id>
COPILOT_STUDIO_AGENT_ENVIRONMENT_ID=<your-env-id>
COPILOT_STUDIO_AGENT_AGENT_IDENTIFIER=<your-agent-id>
COPILOT_STUDIO_AGENT_AUTH_MODE=interactive

小提示

如需許可權的說明，請參閱 Power Platform API 驗證 。

Java 中目前無法使用的功能。

建立和設定 CopilotStudioAgent 用戶端

您可以仰賴大部分組態的環境變數，但可以視需要明確建立和自定義代理程式用戶端。

適用於 .NET 的 CopilotStudioAgent 即將推出。

基本使用方式 - 環境變數驅動

from semantic_kernel.agents import CopilotStudioAgent

agent = CopilotStudioAgent(
    name="PhysicsAgent",
    instructions="You help answer questions about physics.",
)

如果您的環境變數已設定，則不需要明確的客戶端設定。

明確用戶端建構

覆寫設定或使用客製化身份：

from semantic_kernel.agents import CopilotStudioAgent

client = CopilotStudioAgent.create_client(
    auth_mode="interactive",  # or use CopilotStudioAgentAuthMode.INTERACTIVE
    agent_identifier="<schema-name>",
    app_client_id="<client-id>",
    tenant_id="<tenant-id>",
    environment_id="<env-id>",
)

agent = CopilotStudioAgent(
    client=client,
    name="CustomAgent",
    instructions="You help answer custom questions.",
)

Java 中目前無法使用的功能。

與CopilotStudioAgent互動

核心工作流程與其他語意核心代理程序類似：提供使用者輸入、接收回應、透過線程維護內容。

適用於 .NET 的 CopilotStudioAgent 即將推出。

基本範例

import asyncio
from semantic_kernel.agents import CopilotStudioAgent

async def main():
    agent = CopilotStudioAgent(
        name="PhysicsAgent",
        instructions="You help answer questions about physics.",
    )

    USER_INPUTS = [
        "Why is the sky blue?",
        "What is the speed of light?",
    ]

    for user_input in USER_INPUTS:
        print(f"# User: {user_input}")
        response = await agent.get_response(messages=user_input)
        print(f"# {response.name}: {response}")

asyncio.run(main())

使用執行緒保持上下文

若要保持對話的連貫性：

import asyncio
from semantic_kernel.agents import CopilotStudioAgent, CopilotStudioAgentThread

async def main():
    agent = CopilotStudioAgent(
        name="PhysicsAgent",
        instructions="You help answer questions about physics.",
    )

    USER_INPUTS = [
        "Hello! Who are you? My name is John Doe.",
        "What is the speed of light?",
        "What have we been talking about?",
        "What is my name?",
    ]

    thread: CopilotStudioAgentThread | None = None

    for user_input in USER_INPUTS:
        print(f"# User: {user_input}")
        response = await agent.get_response(messages=user_input, thread=thread)
        print(f"# {response.name}: {response}")
        thread = response.thread

    if thread:
        await thread.delete()

asyncio.run(main())

使用參數和提示模板

import asyncio
from semantic_kernel.agents import CopilotStudioAgent, CopilotStudioAgentThread
from semantic_kernel.contents import ChatMessageContent
from semantic_kernel.functions import KernelArguments
from semantic_kernel.prompt_template import PromptTemplateConfig

async def main():
    agent = CopilotStudioAgent(
        name="JokeAgent",
        instructions="You are a joker. Tell kid-friendly jokes.",
        prompt_template_config=PromptTemplateConfig(template="Craft jokes about {{$topic}}"),
    )

    USER_INPUTS = [
        ChatMessageContent(role="user", content="Tell me a joke to make me laugh.")
    ]

    thread: CopilotStudioAgentThread | None = None

    for user_input in USER_INPUTS:
        print(f"# User: {user_input}")
        response = await agent.get_response(
            messages=user_input,
            thread=thread,
            arguments=KernelArguments(topic="pirate"),
        )
        print(f"# {response.name}: {response}")
        thread = response.thread

    if thread:
        await thread.delete()

asyncio.run(main())

迭代串流（不支援）

備註

目前 CopilotStudioAgent不支援串流回應。

搭配使用外掛程式與 CopilotStudioAgent

語意核心允許代理程式和外掛程式的組合。 雖然 Copilot Studio 的主要擴充性是透過 Studio 本身，但您可以撰寫外掛程式與其他代理程式一樣。

適用於 .NET 的 CopilotStudioAgent 即將推出。

from semantic_kernel.functions import kernel_function
from semantic_kernel.agents import CopilotStudioAgent

class SamplePlugin:
    @kernel_function(description="Provides sample data.")
    def get_data(self) -> str:
        return "Sample data from custom plugin"

agent = CopilotStudioAgent(
    name="PluggedInAgent",
    instructions="Demonstrate plugins.",
    plugins=[SamplePlugin()],
)

Java 中目前無法使用的功能。

進階功能

CopilotStudioAgent可以根據目標代理程式在 Studio 環境中設定的方式，運用進階 Copilot Studio 增強功能：

  • 知識擷取 - 會根據 Studio 中預先設定的知識來源回應。
  • Web 搜尋 - 如果您的 Studio 代理程式已啟用 Web 搜尋，查詢將會使用 Bing 搜尋。
  • 自訂身份驗證或 API — 透過 Power Platform 和 Studio 外掛程式，直接 OpenAPI 系結目前不是 SK 整合中的一流功能。

適用於 .NET 的 CopilotStudioAgent 即將推出。

知識檢索

不需要特定的 Python 程式代碼;知識來源必須在 Copilot Studio 中設定。 當使用者訊息需要來自這些來源的事實時，代理將根據需要傳回資訊。

在 Studio 中設定 Copilot 以允許 Bing 搜尋。 然後按照上述方法使用。 如需設定 Bing 搜尋的詳細資訊，請參閱下列 指南。

from semantic_kernel.agents import CopilotStudioAgent, CopilotStudioAgentThread

agent = CopilotStudioAgent(
    name="WebSearchAgent",
    instructions="Help answer the user's questions by searching the web.",
)

USER_INPUTS = ["Which team won the 2025 NCAA Basketball championship?"]

thread: CopilotStudioAgentThread | None = None

for user_input in USER_INPUTS:
    print(f"# User: {user_input}")
    # Note: Only non-streamed responses are supported
    response = await agent.get_response(messages=user_input, thread=thread)
    print(f"# {response.name}: {response}")
    thread = response.thread

if thread:
    await thread.delete()

Java 中目前無法使用的功能。

操作指南

如需使用 CopilotStudioAgent的實際範例，請參閱 GitHub 上的程式碼範例：

適用於 .NET 的 CopilotStudioAgent 即將推出。

Java 中目前無法使用的功能。

注意：

  • 如需詳細資訊或疑難解答，請參閱 Microsoft Copilot Studio 檔。
  • 只有個別啟用和發行於 Studio 代理程式中的功能和工具，才能透過語意核心介面取得。
  • 串流、外掛程式部署和程式化工具的新增預計在未來版本中推出。

後續步驟

探索 OpenAI 助理代理程式

  • Last updated on