Compartir a través de

Exploración del kernel semántico CopilotStudioAgent

Importante

Esta característica está en la fase experimental. Las características de esta fase están en desarrollo y están sujetas a cambios antes de avanzar a la fase de versión preliminar o candidata para lanzamiento.

La documentación detallada de la API relacionada con esta discusión está disponible en:

CopilotStudioAgent para .NET estará disponible próximamente.

Pronto se actualizarán los documentos de API.

Característica actualmente no disponible en Java.

¿Qué es CopilotStudioAgent?

A CopilotStudioAgent es un punto de integración dentro del marco de kernel semántico que permite la interacción perfecta con los agentes de Microsoft Copilot Studio mediante API de programación. Este agente le permite:

  • Automatice las conversaciones e invoque los agentes existentes de Copilot Studio desde el código de Python.
  • Mantener un historial de conversación enriquecido mediante hilos, conservando el contexto entre los mensajes.
  • Aproveche las funcionalidades avanzadas de recuperación de conocimientos, búsqueda web e integración de datos disponibles en Microsoft Copilot Studio.

Nota:

Los orígenes de conocimiento o las herramientas deben configurarse en Microsoft Copilot Studio para poder acceder a ellos a través del agente.

Preparación del entorno de desarrollo

Para desarrollar con CopilotStudioAgent, debe tener el entorno y la autenticación configurados correctamente.

CopilotStudioAgent para .NET estará disponible próximamente.

Prerrequisitos

  1. Python 3.10 o superior
  2. Kernel semántico con dependencias de Copilot Studio:
pip install semantic-kernel[copilotstudio]

  1. Agente de Microsoft Copilot Studio :

    • Cree un agente en Microsoft Copilot Studio.
    • Publique su agente y, bajo Settings → Advanced → Metadata, obtenga:
      • Schema Name (se usa como agent_identifier)
      • Environment ID

  2. Registro de aplicaciones de Azure Entra ID ("Aplicación nativa", para inicio de sesión interactivo), con CopilotStudio.Copilots.Invoke permiso delegado.

Variables de entorno

Establezca las siguientes variables en su entorno o archivo .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

Sugerencia

Consulte Autenticación de Power Platform API para obtener ayuda con los permisos.

Característica actualmente no disponible en Java.

Creación y configuración de un CopilotStudioAgent cliente

Puede confiar en variables de entorno para la mayoría de la configuración, pero puede crear y personalizar explícitamente el cliente del agente según sea necesario.

CopilotStudioAgent para .NET estará disponible próximamente.

Uso básico — Impulsado por variables de entorno

from semantic_kernel.agents import CopilotStudioAgent

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

No se requiere ninguna configuración de cliente explícita si se establecen las variables de entorno.

Construcción de cliente explícita

Invalide la configuración o use una identidad personalizada:

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

Característica actualmente no disponible en Java.

Interacción con un CopilotStudioAgent

El flujo de trabajo principal es similar a otros agentes de kernel semántico: proporcionar entradas de usuario, recibir respuestas, mantener el contexto a través de subprocesos.

CopilotStudioAgent para .NET estará disponible próximamente.

Ejemplo básico

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

Mantener el contexto con hilos

Para mantener la continuidad de la conversación:

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

El uso de argumentos y plantillas de instrucción

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

Iteración a través de streaming (no compatible)

Nota:

Actualmente, las respuestas de streaming no son compatibles con CopilotStudioAgent.

Uso de complementos con CopilotStudioAgent

El kernel semántico permite la composición de agentes y complementos. Aunque la extensibilidad principal de Copilot Studio viene a través del propio Studio, puede compilar complementos de la misma manera que con otros agentes.

CopilotStudioAgent para .NET estará disponible próximamente.

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

Característica actualmente no disponible en Java.

Características avanzadas

Un CopilotStudioAgent puede aprovechar las capacidades avanzadas de Copilot Studio, en función de cómo se configure el agente de destino en el entorno de Copilot Studio.

  • Recuperación de conocimiento : responde en función de los orígenes de conocimiento preconfigurados en Studio.
  • Búsqueda web: si la búsqueda web está habilitada en el agente de Studio, las consultas usarán Bing Search.
  • Autenticación personalizada o APIs — a través de complementos de Power Platform y Studio; La vinculación directa de OpenAPI no es actualmente prioritaria en la integración de SK.

CopilotStudioAgent para .NET estará disponible próximamente.

Recuperación de conocimientos

No se necesita código de Python específico; Los orígenes de conocimiento deben configurarse en Copilot Studio. Cuando los mensajes de usuario requieren hechos de estos orígenes, el agente devolverá información según corresponda.

Configure el Copilot en Studio para permitir Bing Search. A continuación, use como se ha indicado anteriormente. Para obtener más información sobre cómo configurar Bing Search, consulte la siguiente guía.

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

Característica actualmente no disponible en Java.

Procedimiento

Para obtener ejemplos prácticos de uso de , CopilotStudioAgentconsulte nuestros ejemplos de código en GitHub:

CopilotStudioAgent para .NET estará disponible próximamente.

Característica actualmente no disponible en Java.

Notas:

  • Para obtener más información o solucionar problemas, consulte la documentación de Microsoft Copilot Studio.
  • Solo las características y herramientas habilitadas por separado y publicadas en el agente de Studio estarán disponibles a través de la interfaz semántica del kernel.
  • La transmisión por secuencias, la implementación de complementos y la adición de herramientas mediante programación están planeadas para futuras versiones.

Pasos siguientes

Explora el agente asistente de OpenAI

  • Last updated on