Exploration du noyau sémantique `CopilotStudioAgent`

2025-05-23

Important

Cette fonctionnalité est à l’étape expérimentale. Les fonctionnalités à ce stade sont en cours de développement et soumises à des modifications avant de passer à la phase de préversion ou de version candidate.

La documentation détaillée de l’API relative à cette discussion est disponible à l’adresse suivante :

CopilotStudioAgent pour .NET sera bientôt disponible.

Les documents d’API mis à jour seront bientôt disponibles.

Fonctionnalité actuellement indisponible en Java.

Qu’est-ce qu’un `CopilotStudioAgent` ?

CopilotStudioAgent est un point d'intégration dans le cadre Semantic Kernel qui permet une interaction transparente avec les agents Microsoft Copilot Studio à l'aide d'API programmatiques. Cet agent vous permet de :

Automatisez les conversations et appelez des agents Copilot Studio existants à partir du code Python.
Conservez un historique conversationnel riche à l’aide de threads, en préservant le contexte entre les messages.
Tirez parti des fonctionnalités avancées de récupération des connaissances, de recherche web et d’intégration des données disponibles dans Microsoft Copilot Studio.

Remarque

Les sources/outils de connaissances doivent être configurés dans Microsoft Copilot Studio avant d’être accessibles via l’agent.

Préparation de votre environnement de développement

Pour développer avec , CopilotStudioAgentvous devez configurer correctement votre environnement et votre authentification.

CopilotStudioAgent pour .NET sera bientôt disponible.

Conditions préalables

Python 3.10 ou version ultérieure

Noyau sémantique avec dépendances Copilot Studio :

Jusqu’à ce que les dépendances soient largement disponibles sur PyPI :

pip install semantic-kernel
pip install --extra-index-url https://test.pypi.org/simple microsoft-agents-core microsoft-agents-copilotstudio-client

Agent Microsoft Copilot Studio :
- Créez un agent sur Microsoft Copilot Studio.
- Publiez votre agent, et sous Settings → Advanced → Metadata, obtenez :
  - Schema Name (utilisé comme agent_identifier)
  - Environment ID
Inscription d’application d’ID Azure Entra (« application native », pour une connexion interactive) avec CopilotStudio.Copilots.Invoke autorisation déléguée.

Variables d’environnement

Définissez les variables suivantes dans votre environnement ou .env fichier :

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

Conseil / Astuce

Consultez l’authentification de l’API Power Platform pour obtenir de l’aide sur les autorisations.

Fonctionnalité actuellement indisponible en Java.

Création et configuration d’un `CopilotStudioAgent` client

Vous pouvez vous appuyer sur des variables d’environnement pour la plupart des configurations, mais peut créer et personnaliser explicitement le client de l’agent en fonction des besoins.

CopilotStudioAgent pour .NET sera bientôt disponible.

Utilisation de base — Basée sur les variables d'environnement

from semantic_kernel.agents import CopilotStudioAgent

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

Aucune configuration explicite du client n’est requise si vos variables d’environnement sont définies.

Construction de logiciel client explicite

Remplacez la configuration ou utilisez l’identité personnalisée :

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

Fonctionnalité actuellement indisponible en Java.

Interaction avec un `CopilotStudioAgent`

Le flux de travail principal est similaire à d’autres agents de noyau sémantique : fournissez des entrées utilisateur, recevez des réponses, conservez le contexte via des threads.

CopilotStudioAgent pour .NET sera bientôt disponible.

Exemple de base

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

Gestion du contexte avec des threads

Pour conserver l’état de la conversation :

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

Utilisation d’arguments et de modèles de sollicitation

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

Itération sur la diffusion en continu (non prise en charge)

Remarque

Les réponses de diffusion en continu ne sont actuellement pas prises en charge par CopilotStudioAgent.

Utilisation de plug-ins avec un `CopilotStudioAgent`

Le noyau sémantique permet la composition des agents et des plug-ins. Bien que l’extensibilité principale pour Copilot Studio soit fournie via le Studio lui-même, vous pouvez composer des plug-ins comme avec d’autres agents.

CopilotStudioAgent pour .NET sera bientôt disponible.

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

Fonctionnalité actuellement indisponible en Java.

Fonctionnalités avancées

Un CopilotStudioAgent peut tirer parti des capacités avancées améliorées de Copilot Studio, en fonction de la façon dont l’agent cible est configuré dans l’environnement Studio :

Récupération des connaissances : répond en fonction des sources de connaissances préconfigurées dans Studio.
Recherche web : si la recherche web est activée dans votre agent Studio, les requêtes utilisent Recherche Bing.
Authentification personnalisée ou API : via les plug-ins Power Platform et Studio ; La liaison directe avec OpenAPI n’est actuellement pas de première qualité dans l’intégration SK.

CopilotStudioAgent pour .NET sera bientôt disponible.

Récupération des connaissances

Aucun code Python spécifique n’est nécessaire ; les sources de connaissances doivent être configurées dans Copilot Studio. Lorsque les messages utilisateur nécessitent des faits provenant de ces sources, l’agent retourne les informations appropriées.

Recherche Web

Configurez votre Copilot dans Studio pour autoriser Recherche Bing. Utilisez ensuite comme indiqué ci-dessus. Pour plus d’informations sur la configuration de Recherche Bing, consultez le guide suivant.

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

Fonctionnalité actuellement indisponible en Java.

Comment faire

Pour obtenir des exemples pratiques d’utilisation d’un CopilotStudioAgent, consultez nos exemples de code sur GitHub :

CopilotStudioAgent pour .NET sera bientôt disponible.

Premiers pas avec les agents Copilot Studio

Fonctionnalité actuellement indisponible en Java.

Remarques :

Pour plus d’informations ou de résolution des problèmes, consultez la documentation de Microsoft Copilot Studio.
Seules les fonctionnalités et les outils activés séparément et publiés dans votre agent Studio seront disponibles via l’interface de noyau sémantique.
La diffusion en continu, le déploiement de plug-in et l’ajout d’outils programmatiques sont prévus pour les futures versions.

Étapes suivantes

Explorer l’agent Assistant OpenAI

Partager via

Exploration du noyau sémantique CopilotStudioAgent

Qu’est-ce qu’un CopilotStudioAgent ?

Préparation de votre environnement de développement

Conditions préalables

Variables d’environnement

Création et configuration d’un CopilotStudioAgent client

Utilisation de base — Basée sur les variables d'environnement

Construction de logiciel client explicite

Interaction avec un CopilotStudioAgent

Exemple de base

Gestion du contexte avec des threads

Utilisation d’arguments et de modèles de sollicitation

Itération sur la diffusion en continu (non prise en charge)

Utilisation de plug-ins avec un CopilotStudioAgent

Fonctionnalités avancées

Récupération des connaissances

Recherche Web

Comment faire

Étapes suivantes

Ressources supplémentaires

Exploration du noyau sémantique `CopilotStudioAgent`

Qu’est-ce qu’un `CopilotStudioAgent` ?

Création et configuration d’un `CopilotStudioAgent` client

Interaction avec un `CopilotStudioAgent`

Utilisation de plug-ins avec un `CopilotStudioAgent`