Explorando o kernel semântico `CopilotStudioAgent`

2025-05-23

Importante

Esse recurso está em estágio experimental. Os recursos nesta fase estão em desenvolvimento e sujeitos a alterações antes de avançar para a versão preliminar ou para o estágio de candidato a lançamento.

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

O CopilotStudioAgent para .NET estará disponível em breve.

A documentação atualizada da API estará disponível em breve.

Recurso atualmente indisponível em Java.

O que é `CopilotStudioAgent`?

Um CopilotStudioAgent é um ponto de integração dentro da estrutura de Kernel Semântico que permite interação perfeita com agentes do Microsoft Copilot Studio usando APIs programáticas. Esse agente permite que você:

Automatize conversas e invoque agentes existentes do Copilot Studio do código Python.
Mantenha um histórico rico de conversas usando threads, preservando o contexto entre 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 para que possam 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 estará disponível em breve.

Pré-requisitos

Python 3.10 ou superior

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

Até que as dependências estejam disponíveis de forma abrangente 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 Settings → Advanced → Metadata obtenha:
  - Schema Name (usado como agent_identifier)
  - Environment ID
Registro de Aplicativo do Azure Entra ID ("Aplicativo nativo", para logon 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

Dica

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

Recurso atualmente indisponível em Java.

Criando e configurando um `CopilotStudioAgent` cliente

Você pode contar com 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 estará disponível em breve.

Uso básico – Orientado por variáveis 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 do cliente

Sobreponha a configuração ou use uma 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 kernel semânticos: fornecer entradas do usuário, receber respostas, manter o contexto por meio de threads.

O CopilotStudioAgent para .NET estará disponível 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 o estado da conversa:

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

Usando argumentos e modelos de sugestã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 por streaming (sem suporte)

Observação

No momento, CopilotStudioAgent não suporta respostas de streaming.

Usando plug-ins com um `CopilotStudioAgent`

O Kernel Semântico permite a composição de agentes e plug-ins. Embora a extensibilidade primária do Copilot Studio venha por meio do próprio Studio, você pode compor plug-ins como com outros agentes.

O CopilotStudioAgent para .NET estará disponível 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.

Recursos avançados

Um CopilotStudioAgent pode aproveitar as habilidades avançadas aprimoradas do Copilot Studio, dependendo de como o agente de destino é configurado no ambiente do 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 em seu agente do Studio, as consultas usarão a Pesquisa do Bing.
Autenticação personalizada ou APIs — via plug-ins do Power Platform e do Studio; A associação direta do OpenAPI atualmente não é prioritária na integração de SK.

O CopilotStudioAgent para .NET estará disponível 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 de 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.

Como Fazer

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

O CopilotStudioAgent para .NET estará disponível em breve.

Introdução aos Agentes do Copilot Studio

Recurso atualmente indisponível em Java.

Observações:

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 por meio da interface Kernel Semântica.
Streaming, implantação de plug-in e adição de ferramenta programática são planejados para versões futuras.

Próximas etapas

Explorar o Agente Assistente do OpenAI

Compartilhar via

Explorando o kernel semântico CopilotStudioAgent

O que é CopilotStudioAgent?

Preparando seu ambiente de desenvolvimento

Pré-requisitos

Variáveis de ambiente

Criando e configurando um CopilotStudioAgent cliente

Uso básico – Orientado por variáveis de ambiente

Construção explícita do cliente

Interagindo com um CopilotStudioAgent

Exemplo básico

Mantendo o contexto com threads

Usando argumentos e modelos de sugestão

Iteração por streaming (sem suporte)

Usando plug-ins com um CopilotStudioAgent

Recursos avançados

Recuperação de conhecimento

Pesquisa na Web

Como Fazer

Próximas etapas

Recursos adicionais

Explorando o kernel semântico `CopilotStudioAgent`

O que é `CopilotStudioAgent`?

Criando e configurando um `CopilotStudioAgent` cliente

Interagindo com um `CopilotStudioAgent`

Usando plug-ins com um `CopilotStudioAgent`