Explorando o Kernel Semântico `CopilotStudioAgent`

2025-05-23

Importante

Esta característica encontra-se em fase experimental. Os recursos nesta fase estão em desenvolvimento e sujeitos a alterações antes de avançar para a versão de pré-visualização ou versão candidata.

A documentação detalhada da API relacionada a esta discussão está disponível em:

O CopilotStudioAgent para .NET será lançado em breve.

Documentos de API atualizados estão chegando em breve.

Recurso atualmente indisponível em Java.

O que é um `CopilotStudioAgent`?

A CopilotStudioAgent é um ponto de integração dentro da estrutura do Kernel Semântico que permite a interação perfeita com agentes do Microsoft Copilot Studio usando APIs programáticas. Este agente permite-lhe:

Automatize conversas e invoque agentes existentes do Copilot Studio a partir do código Python.
Mantenha um histórico de conversação rico usando threads, preservando o contexto nas mensagens.
Aproveite os recursos avançados de recuperação de conhecimento, pesquisa na Web e integração de dados disponibilizados no Microsoft Copilot Studio.

Observação

As fontes/ferramentas de conhecimento devem ser configuradas no Microsoft Copilot Studio antes de poderem ser acessadas por meio do agente.

Preparando seu ambiente de desenvolvimento

Para desenvolver com o CopilotStudioAgent, você deve ter seu ambiente e autenticação configurados corretamente.

O CopilotStudioAgent para .NET será lançado em breve.

Pré-requisitos

Python 3.10 ou superior

Kernel semântico com dependências do Copilot Studio:

Até que as dependências estejam amplamente disponíveis no PyPI:

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

Agente do Microsoft Copilot Studio :
- Crie um agente no Microsoft Copilot Studio.
- Publique seu agente e, em Settings → Advanced → Metadata obtenha:
  - Schema Name (utilizado como agent_identifier)
  - Environment ID
Azure Entra ID Application Registration ("Aplicação nativa", para início de sessão interativo), com CopilotStudio.Copilots.Invoke permissão delegada.

Variáveis de ambiente

Defina as seguintes variáveis em seu ambiente ou .env arquivo:

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

Sugestão

Consulte Autenticação de API da Power Platform para obter ajuda com permissões.

Recurso atualmente indisponível em Java.

Criando e configurando um `CopilotStudioAgent` cliente

Você pode confiar em variáveis de ambiente para a maioria das configurações, mas pode criar e personalizar explicitamente o cliente do agente conforme necessário.

O CopilotStudioAgent para .NET será lançado em breve.

Uso Básico — Dirigido por Variável de Ambiente

from semantic_kernel.agents import CopilotStudioAgent

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

Nenhuma configuração explícita do cliente será necessária se as variáveis de ambiente estiverem definidas.

Construção explícita de clientes

Substitua a configuração ou use a identidade 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.",
)

Recurso atualmente indisponível em Java.

Interagindo com um `CopilotStudioAgent`

O fluxo de trabalho principal é semelhante a outros agentes do Kernel Semântico: fornecer entrada(s) do usuário, receber respostas, manter o contexto por meio de threads.

O CopilotStudioAgent para .NET será lançado em breve.

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

Mantendo o contexto com threads

Para manter a conversa com estado persistente:

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

Usar argumentos e modelos de solicitação

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

Iteração sobre streaming (não é suportado)

Observação

Atualmente, as respostas de streaming não são suportadas pelo CopilotStudioAgent.

Usando plug-ins com um `CopilotStudioAgent`

Semantic Kernel permite a composição de agentes e plugins. Embora a extensibilidade principal para o Copilot Studio venha através do próprio Studio, você pode compor plugins como com outros agentes.

O CopilotStudioAgent para .NET será lançado em breve.

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

Recurso atualmente indisponível em Java.

Funcionalidades avançadas

A CopilotStudioAgent pode aproveitar as habilidades avançadas aprimoradas do Copilot Studio, dependendo de como o agente de destino está configurado no ambiente Studio:

Recuperação de conhecimento — responde com base em fontes de conhecimento pré-configuradas no Studio.
Pesquisa na Web — se a pesquisa na Web estiver habilitada no agente do Studio, as consultas usarão a Pesquisa do Bing.
Autenticação personalizada ou APIs — através de plug-ins Power Platform e Studio; a vinculação direta de OpenAPI não é atualmente de primeira classe na integração SK.

O CopilotStudioAgent para .NET será lançado em breve.

Recuperação de Conhecimento

Nenhum código Python específico é necessário; as fontes de conhecimento devem ser configuradas no Copilot Studio. Quando as mensagens do usuário exigirem fatos dessas fontes, o agente retornará informações conforme apropriado.

Pesquisa na Web

Configure seu Copilot no Studio para permitir a Pesquisa do Bing. Em seguida, use como acima. Para obter mais informações sobre como configurar a Pesquisa do Bing, consulte o guia a seguir.

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

Recurso atualmente indisponível em Java.

Instruções

Para obter exemplos práticos do uso de um CopilotStudioAgent, consulte nossos exemplos de código no GitHub:

O CopilotStudioAgent para .NET será lançado em breve.

Introdução aos agentes do Copilot Studio

Recurso atualmente indisponível em Java.

Notas:

Para obter mais informações ou solução de problemas, consulte a documentação do Microsoft Copilot Studio.
Somente recursos e ferramentas habilitados separadamente e publicados em seu agente do Studio estarão disponíveis através da interface do Kernel Semântico.
Streaming, implantação de plug-ins e adição de ferramentas programáticas estão planejados para versões futuras.

Próximas Etapas

Explore o Agente Assistente da OpenAI

Partilhar via

Explorando o Kernel Semântico CopilotStudioAgent

O que é um CopilotStudioAgent?

Preparando seu ambiente de desenvolvimento

Pré-requisitos

Variáveis de ambiente

Criando e configurando um CopilotStudioAgent cliente

Uso Básico — Dirigido por Variável de Ambiente

Construção explícita de clientes

Interagindo com um CopilotStudioAgent

Exemplo básico

Mantendo o contexto com threads

Usar argumentos e modelos de solicitação

Iteração sobre streaming (não é suportado)

Usando plug-ins com um CopilotStudioAgent

Funcionalidades avançadas

Recuperação de Conhecimento

Pesquisa na Web

Instruções

Próximas Etapas

Recursos adicionais

Explorando o Kernel Semântico `CopilotStudioAgent`

O que é um `CopilotStudioAgent`?

Criando e configurando um `CopilotStudioAgent` cliente

Interagindo com um `CopilotStudioAgent`

Usando plug-ins com um `CopilotStudioAgent`