의미 체계 커널 `CopilotStudioAgent` 탐색

2025-05-23

중요합니다

이 기능은 실험 단계에 있습니다. 이 단계의 기능은 개발 중이며 미리 보기 또는 릴리스 후보 단계로 넘어가기 전에 변경될 수 있습니다.

이 설명과 관련된 자세한 API 설명서는 다음에서 확인할 수 있습니다.

.NET용 CopilotStudioAgent는 곧 출시될 예정입니다.

업데이트된 API 문서는 곧 제공될 예정입니다.

현재 Java에서 기능을 사용할 수 없습니다.

`CopilotStudioAgent`이란 무엇입니까?

A CopilotStudioAgent 는 프로그래밍 방식 API를 사용하여 Microsoft Copilot Studio 에이전트와 원활하게 상호 작용할 수 있도록 하는 의미 체계 커널 프레임워크 내의 통합 지점입니다. 이 에이전트를 사용하면 다음을 수행할 수 있습니다.

대화를 자동화하고 Python 코드에서 기존 Copilot Studio 에이전트를 호출합니다.
스레드를 사용하여 다양한 대화 기록을 유지 관리하고 메시지 간에 컨텍스트를 유지합니다.
Microsoft Copilot Studio 내에서 제공되는 고급 지식 검색, 웹 검색 및 데이터 통합 기능을 활용합니다.

비고

에이전트를 통해 액세스하려면 먼저 Microsoft Copilot Studio 내에서 기술 자료/도구를 구성해야 합니다.

개발 환경 준비

CopilotStudioAgent로 개발을 하려면, 환경 및 인증이 올바르게 설정되어 있어야 합니다.

.NET용 CopilotStudioAgent는 곧 출시될 예정입니다.

필수 조건

Python 3.10 이상

Copilot Studio 종속성을 사용하는 의미 체계 커널:

종속성이 PyPI에서 광범위하게 사용 가능할 때까지:

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

Microsoft Copilot Studio 에이전트:
- Microsoft Copilot Studio에서 에이전트를 만듭니다.
- 에이전트를 게시하고 Settings → Advanced → Metadata을(를) 획득하세요.
  - Schema Name (agent_identifier으로 사용)
  - Environment ID
권한이 위임된 Azure Entra ID 애플리케이션 등록 (“네이티브 앱”, 대화형 로그인을 위한)입니다.

환경 변수

환경 또는 .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

팁 (조언)

권한에 대한 도움말은 Power Platform API 인증 을 참조하세요.

현재 Java에서 기능을 사용할 수 없습니다.

클라이언트 만들기 및 구성 `CopilotStudioAgent`

대부분의 구성에 환경 변수를 사용할 수 있지만 필요에 따라 에이전트 클라이언트를 명시적으로 만들고 사용자 지정할 수 있습니다.

.NET용 CopilotStudioAgent는 곧 출시될 예정입니다.

기본 사용 — 환경 변수 기반

from semantic_kernel.agents import CopilotStudioAgent

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

환경 변수가 설정된 경우 명시적 클라이언트 설정이 필요하지 않습니다.

명시적 클라이언트 생성

구성을 재정의하거나 사용자 지정 ID를 사용합니다.

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

현재 Java에서 기능을 사용할 수 없습니다.

A와 상호 작용 `CopilotStudioAgent`

핵심 워크플로는 사용자 입력 제공, 응답 수신, 스레드를 통한 컨텍스트 유지 관리 등 다른 의미 체계 커널 에이전트와 유사합니다.

.NET용 CopilotStudioAgent는 곧 출시될 예정입니다.

기본 예제

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

스레드를 사용하여 컨텍스트 유지 관리

대화를 상태 저장 상태로 유지하려면 다음을 수행합니다.

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

인수 및 프롬프트 템플릿 사용

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

스트리밍 반복(지원되지 않음)

비고

스트리밍 응답은 현재 CopilotStudioAgent에서 지원되지 않습니다.

와 함께 플러그 인 사용 `CopilotStudioAgent`

의미 체계 커널은 에이전트 및 플러그 인의 구성을 허용합니다. Copilot Studio의 기본 확장성은 Studio 자체를 통해 제공되지만 다른 에이전트와 마찬가지로 플러그 인을 작성할 수 있습니다.

.NET용 CopilotStudioAgent는 곧 출시될 예정입니다.

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

현재 Java에서 기능을 사용할 수 없습니다.

고급 기능

A는 CopilotStudioAgent Studio 환경에서 대상 에이전트가 구성된 방법에 따라 Copilot Studio의 고급 향상된 기능을 활용할 수 있습니다.

지식 검색 - Studio에서 미리 구성된 기술 자료를 기반으로 응답합니다.
웹 검색 - Studio 에이전트에서 웹 검색을 사용하도록 설정하면 쿼리에서 Bing Search를 사용합니다.
Power Platform 및 Studio 플러그 인을 통한 사용자 지정 인증 또는 API 직접 OpenAPI 바인딩은 현재 SK 통합에서 일류가 아닙니다.

.NET용 CopilotStudioAgent는 곧 출시될 예정입니다.

지식 검색

특정 Python 코드가 필요하지 않습니다. 기술 자료는 Copilot Studio에서 구성해야 합니다. 사용자 메시지에 이러한 원본의 팩트를 요구하는 경우 에이전트는 적절하게 정보를 반환합니다.

웹 검색

Bing Search를 허용하도록 Studio 내에서 Copilot를 구성합니다. 그런 다음 위와 같이 사용합니다. Bing Search 구성에 대한 자세한 내용은 다음 가이드를 참조 하세요.

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

현재 Java에서 기능을 사용할 수 없습니다.

사용 방법

실제 사용 예제는 CopilotStudioAgentGitHub의 코드 샘플을 참조하세요.

.NET용 CopilotStudioAgent는 곧 출시될 예정입니다.

Copilot Studio 에이전트 시작하기

현재 Java에서 기능을 사용할 수 없습니다.

참고:

자세한 내용 또는 문제 해결은 Microsoft Copilot Studio 설명서를 참조하세요.
Studio 에이전트에 별도로 사용하도록 설정되고 게시된 기능 및 도구만 의미 체계 커널 인터페이스를 통해 사용할 수 있습니다.
스트리밍, 플러그 인 배포 및 프로그래밍 방식 도구 추가는 향후 릴리스에 대해 계획되어 있습니다.

다음 단계

OpenAI 길잡이 에이전트 살펴보기

다음을 통해 공유

의미 체계 커널 CopilotStudioAgent 탐색

CopilotStudioAgent이란 무엇입니까?

개발 환경 준비

필수 조건

환경 변수

클라이언트 만들기 및 구성 CopilotStudioAgent

기본 사용 — 환경 변수 기반

명시적 클라이언트 생성

A와 상호 작용 CopilotStudioAgent

기본 예제

스레드를 사용하여 컨텍스트 유지 관리

인수 및 프롬프트 템플릿 사용

스트리밍 반복(지원되지 않음)

와 함께 플러그 인 사용 CopilotStudioAgent

고급 기능

지식 검색

웹 검색

사용 방법

다음 단계

추가 리소스

의미 체계 커널 `CopilotStudioAgent` 탐색

`CopilotStudioAgent`이란 무엇입니까?

클라이언트 만들기 및 구성 `CopilotStudioAgent`

A와 상호 작용 `CopilotStudioAgent`

와 함께 플러그 인 사용 `CopilotStudioAgent`