Freigeben über

Erforschung des semantischen Kerns CopilotStudioAgent

Von Bedeutung

Dieses Feature befindet sich in der experimentellen Phase. Features in dieser Phase befinden sich in der Entwicklung und können sich ändern, bevor Sie zur Vorschau- oder Veröffentlichungskandidatenstufe wechseln.

Detaillierte API-Dokumentation zu dieser Diskussion finden Sie unter:

Der CopilotStudioAgent für .NET wird in Kürze verfügbar sein.

Aktualisierte API-Dokumente werden in Kürze verfügbar sein.

Das Feature ist derzeit in Java nicht verfügbar.

Was ist ein CopilotStudioAgent?

A CopilotStudioAgent ist ein Integrationspunkt innerhalb des semantischen Kernel-Frameworks, der eine nahtlose Interaktion mit Microsoft Copilot Studio-Agents mithilfe von programmgesteuerten APIs ermöglicht. Dieser Agent ermöglicht Folgendes:

  • Automatisieren Sie Unterhaltungen, und rufen Sie vorhandene Copilot Studio-Agents aus Python-Code auf.
  • Den umfassenden Unterhaltungsverlauf mithilfe von Threads aufrechterhalten und den Kontext über Nachrichten hinweg bewahren.
  • Nutzen Sie erweiterte Wissensabruf-, Websuche- und Datenintegrationsfunktionen, die in Microsoft Copilot Studio zur Verfügung gestellt werden.

Hinweis

Wissensquellen/Tools müssen in Microsoft Copilot Studio konfiguriert werden, bevor über den Agent darauf zugegriffen werden kann.

So bereiten Sie Ihre Entwicklungsumgebung vor

Für die Entwicklung mit dem CopilotStudioAgent müssen Sie Ihre Umgebung und Authentifizierung richtig konfiguriert haben.

Der CopilotStudioAgent für .NET wird in Kürze verfügbar sein.

Voraussetzungen

  1. Python 3.10 oder höher

  2. Semantischer Kernel mit Copilot Studio-Abhängigkeiten:

    • Bis Abhängigkeiten allgemein auf PyPI verfügbar sind: 
      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-Agent :

    • Erstellen Sie einen Agent bei Microsoft Copilot Studio.
    • Veröffentlichen Sie Ihren Agenten, und erhalten Sie unter Settings → Advanced → Metadata Folgendes:
      • Schema Name (verwendet als agent_identifier)
      • Environment ID

  4. Azure Entra ID-Anwendungsregistrierung ("Native App", für interaktive Anmeldung) mit CopilotStudio.Copilots.Invoke delegierter Berechtigung.

Umgebungsvariablen

Legen Sie die folgenden Variablen in Ihrer Umgebung oder .env Datei fest:

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

Tipp

Hilfe zu Berechtigungen finden Sie unter Power Platform-API-Authentifizierung .

Das Feature ist derzeit in Java nicht verfügbar.

Erstellen und Konfigurieren eines CopilotStudioAgent Clients

Sie können sich für die meisten Konfigurationen auf Umgebungsvariablen verlassen, aber den Agentclient bei Bedarf explizit erstellen und anpassen.

Der CopilotStudioAgent für .NET wird in Kürze verfügbar sein.

Grundlegende Verwendung – Gesteuert durch Umgebungsvariablen

from semantic_kernel.agents import CopilotStudioAgent

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

Wenn Die Umgebungsvariablen festgelegt sind, ist kein explizites Clientsetup erforderlich.

Explizite Konstruktion von Clients

Außerkraftsetzen der Konfiguration oder Verwenden einer benutzerdefinierten Identität:

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.",
)

Das Feature ist derzeit in Java nicht verfügbar.

Interagieren mit einem CopilotStudioAgent

Der Kernworkflow ähnelt anderen semantischen Kernel-Agents: Bereitstellen von Benutzereingaben, Empfangen von Antworten, Verwalten des Kontexts über Threads.

Der CopilotStudioAgent für .NET wird in Kürze verfügbar sein.

Einfaches Beispiel

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())

Aufrechterhalten des Kontexts mit Threads

Um den Gesprächszustand beizubehalten:

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())

Verwenden von Argumenten und Eingabeaufforderungsvorlagen

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())

Iterieren über Streaming (nicht unterstützt)

Hinweis

Streamingantworten werden derzeit von CopilotStudioAgent nicht unterstützt.

Verwenden von Plug-Ins mit einem CopilotStudioAgent

Der semantische Kernel ermöglicht die Zusammensetzung von Agents und Plug-Ins. Obwohl die primäre Erweiterbarkeit für Copilot Studio über das Studio selbst kommt, können Sie Plug-Ins wie bei anderen Agents verfassen.

Der CopilotStudioAgent für .NET wird in Kürze verfügbar sein.

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()],
)

Das Feature ist derzeit in Java nicht verfügbar.

Erweiterte Funktionen

Ein CopilotStudioAgent kann erweiterte Fähigkeiten durch Copilot Studio nutzen, je nachdem, wie der Ziel-Agent in der Studio-Umgebung konfiguriert ist.

  • Wissensabruf – antwortet basierend auf vorkonfigurierten Wissensquellen im Studio.
  • Websuche – wenn die Websuche in Ihrem Studio-Agent aktiviert ist, verwenden Abfragen Bing Search.
  • Benutzerdefinierte Authentifizierung oder APIs – über Power Platform- und Studio-Plug-Ins; Direkte OpenAPI-Bindung ist derzeit nicht erstklassig in der SK-Integration.

Der CopilotStudioAgent für .NET wird in Kürze verfügbar sein.

Abrufen von Wissen

Es ist kein spezifischer Python-Code erforderlich; Wissensquellen müssen in Copilot Studio konfiguriert werden. Wenn Benutzernachrichten Fakten aus diesen Quellen erfordern, gibt der Agent nach Bedarf Informationen zurück.

Konfigurieren Sie Ihren Copilot in Studio, um Bing Search zuzulassen. Verwenden Sie dann wie oben beschrieben. Weitere Informationen zum Konfigurieren von Bing Search finden Sie in der folgenden Anleitung.

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()

Das Feature ist derzeit in Java nicht verfügbar.

Vorgehensweise

Praktische Beispiele für die Verwendung eines CopilotStudioAgentCodes finden Sie in unseren Codebeispielen auf GitHub:

Der CopilotStudioAgent für .NET wird in Kürze verfügbar sein.

Das Feature ist derzeit in Java nicht verfügbar.

Hinweise:

  • Weitere Informationen oder Problembehandlung finden Sie in der Dokumentation zu Microsoft Copilot Studio.
  • Nur Features und Tools, die separat aktiviert und in Ihrem Studio-Agent veröffentlicht wurden, sind über die Semantik-Kernel-Schnittstelle verfügbar.
  • Streaming, Plug-In-Bereitstellung und programmgesteuertes Hinzufügen von Tools sind für zukünftige Versionen geplant.

Nächste Schritte

Erkunden sie den OpenAI Assistant Agent