通过

探索语义内核 CopilotStudioAgent

重要

此功能处于实验阶段。 此阶段的功能正在开发中，在升级到预览阶段或候选发布阶段之前可能会更改。

有关此讨论的详细 API 文档在以下位置提供：

适用于 .NET 的 CopilotStudioAgent 即将推出。

即将推出更新的 API 文档。

功能当前在 Java 中不可用。

什么是 CopilotStudioAgent？

它是 CopilotStudioAgent 语义内核框架中的集成点，它允许使用编程 API 与 Microsoft Copilot Studio 代理无缝交互。 此代理允许你：

  • 自动执行对话并从 Python 代码调用现有 Copilot Studio 代理。
  • 使用线程保存丰富的对话历史记录，以在消息之间保留上下文。
  • 利用 Microsoft Copilot Studio 中提供的高级知识检索、Web 搜索和数据集成功能。

注释

必须在 Microsoft Copilot Studio 中 配置知识源/工具，然后才能通过代理访问它们。

准备您的开发环境

若要使用 CopilotStudioAgent进行开发，必须正确设置环境和身份验证。

适用于 .NET 的 CopilotStudioAgent 即将推出。

先决条件

  1. Python 3.10 或更高版本

  2. 具有 Copilot Studio 依赖项的语义内核：

    • 在 PyPI 上广泛提供依赖项之前： 
      pip install semantic-kernel
pip install --extra-index-url https://test.pypi.org/simple microsoft-agents-core microsoft-agents-copilotstudio-client

  3. Microsoft Copilot Studio 代理：

    • 在 Microsoft Copilot Studio 中创建代理。
    • 发布代理后，在 Settings → Advanced → Metadata 下获取：
      • Schema Name （用作 agent_identifier）
      • Environment ID

  4. 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进行互动

核心工作流与其他语义内核代理类似：通过线程提供用户输入（s）、接收响应、维护上下文。

适用于 .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 的主要扩展性来自工作室本身，但你可以与其他代理一样编写插件。

适用于 .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 中不可用。

高级功能

A CopilotStudioAgent 可以利用 Copilot Studio 所增强的高级功能，其具体取决于目标代理在 Studio 环境中的配置方式。

  • 知识检索 - 基于工作室中预配置的知识源做出响应。
  • Web 搜索 - 如果在 Studio 代理中启用了 Web 搜索，查询将使用必应搜索。
  • 自定义身份验证或 API - 通过 Power Platform 和 Studio 插件;直接 OpenAPI 绑定目前不是 SK 集成中的一流。

适用于 .NET 的 CopilotStudioAgent 即将推出。

知识检索

不需要特定的 Python 代码;必须在 Copilot Studio 中配置知识源。 当用户消息需要来自这些源的事实时，代理将根据需要返回信息。

在 Studio 中配置 Copilot 以允许必应搜索。 然后按上述方法使用。 有关配置必应搜索的详细信息，请参阅以下 指南。

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 中不可用。

操作说明

有关使用 a CopilotStudioAgent的实际示例，请参阅 GitHub 上的代码示例：

适用于 .NET 的 CopilotStudioAgent 即将推出。

功能当前在 Java 中不可用。

注意：

  • 有关详细信息或故障排除，请参阅 Microsoft Copilot Studio 文档。
  • 只有单独启用和发布在 Studio 代理中的功能和工具才能通过语义内核接口使用。
  • 将来版本中计划实现流式处理、插件的准备与部署，以及编程工具的添加。

后续步骤

探索 OpenAI 助手代理