agent-framework-copilotstudio 1.0.0b251112__py3-none-any.whl

agent_framework_copilotstudio/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import importlib.metadata
+
+from ._acquire_token import acquire_token
+from ._agent import CopilotStudioAgent
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development mode
+
+__all__ = ["CopilotStudioAgent", "__version__", "acquire_token"]

agent_framework_copilotstudio/_acquire_token.py

@@ -0,0 +1,95 @@
+# Copyright (c) Microsoft. All rights reserved.
+# pyright: reportUnknownMemberType = false
+# pyright: reportUnknownVariableType = false
+# pyright: reportUnknownArgumentType = false
+
+import logging
+from typing import Any
+
+from agent_framework.exceptions import ServiceException
+from msal import PublicClientApplication
+
+logger = logging.getLogger(__name__)
+
+# Default scopes for Power Platform API
+DEFAULT_SCOPES = ["https://api.powerplatform.com/.default"]
+
+
+def acquire_token(
+    *,
+    client_id: str,
+    tenant_id: str,
+    username: str | None = None,
+    token_cache: Any | None = None,
+    scopes: list[str] | None = None,
+) -> str:
+    """Acquire an authentication token using MSAL Public Client Application.
+
+    This function attempts to acquire a token silently first (using cached tokens),
+    and falls back to interactive authentication if needed.
+
+    Keyword Args:
+        client_id: The client ID of the application.
+        tenant_id: The tenant ID for authentication.
+        username: Optional username to filter accounts.
+        token_cache: Optional token cache for storing tokens.
+        scopes: Optional list of scopes. Defaults to Power Platform API scopes.
+
+    Returns:
+        The access token string.
+
+    Raises:
+        ServiceException: If authentication token cannot be acquired.
+    """
+    if not client_id:
+        raise ServiceException("Client ID is required for token acquisition.")
+
+    if not tenant_id:
+        raise ServiceException("Tenant ID is required for token acquisition.")
+
+    authority = f"https://login.microsoftonline.com/{tenant_id}"
+    target_scopes = scopes or DEFAULT_SCOPES
+
+    pca = PublicClientApplication(client_id=client_id, authority=authority, token_cache=token_cache)
+
+    accounts = pca.get_accounts(username=username)
+
+    token: str | None = None
+
+    # Try silent token acquisition first if we have cached accounts
+    if accounts:
+        try:
+            logger.debug("Attempting silent token acquisition")
+            response = pca.acquire_token_silent(scopes=target_scopes, account=accounts[0])
+            if response and "access_token" in response:
+                token = str(response["access_token"])  # type: ignore[assignment]
+                logger.debug("Successfully acquired token silently")
+            elif response and "error" in response:
+                logger.warning(
+                    "Silent token acquisition failed: %s - %s", response.get("error"), response.get("error_description")
+                )
+        except Exception as ex:
+            logger.warning("Silent token acquisition failed with exception: %s", ex)
+
+    # Fall back to interactive authentication if silent acquisition failed
+    if not token:
+        try:
+            logger.debug("Attempting interactive token acquisition")
+            response = pca.acquire_token_interactive(scopes=target_scopes)
+            if response and "access_token" in response:
+                token = str(response["access_token"])  # type: ignore[assignment]
+                logger.debug("Successfully acquired token interactively")
+            elif response and "error" in response:
+                logger.error(
+                    "Interactive token acquisition failed: %s - %s",
+                    response.get("error"),
+                    response.get("error_description"),
+                )
+        except Exception as ex:
+            logger.error("Interactive token acquisition failed with exception: %s", ex)
+            raise ServiceException(f"Failed to acquire authentication token: {ex}") from ex
+
+    if not token:
+        raise ServiceException("Authentication token cannot be acquired.")
+
+    return token

agent_framework_copilotstudio/_agent.py

@@ -0,0 +1,339 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from collections.abc import AsyncIterable
+from typing import Any, ClassVar
+
+from agent_framework import (
+    AgentMiddlewares,
+    AgentRunResponse,
+    AgentRunResponseUpdate,
+    AgentThread,
+    AggregateContextProvider,
+    BaseAgent,
+    ChatMessage,
+    ContextProvider,
+    Role,
+    TextContent,
+)
+from agent_framework._pydantic import AFBaseSettings
+from agent_framework.exceptions import ServiceException, ServiceInitializationError
+from microsoft_agents.copilotstudio.client import AgentType, ConnectionSettings, CopilotClient, PowerPlatformCloud
+from pydantic import ValidationError
+
+from ._acquire_token import acquire_token
+
+
+class CopilotStudioSettings(AFBaseSettings):
+    """Copilot Studio model settings.
+
+    The settings are first loaded from environment variables with the prefix 'COPILOTSTUDIOAGENT__'.
+    If the environment variables are not found, the settings can be loaded from a .env file
+    with the encoding 'utf-8'. If the settings are not found in the .env file, the settings
+    are ignored; however, validation will fail alerting that the settings are missing.
+
+    Keyword Args:
+        environmentid: Environment ID of environment with the Copilot Studio App.
+            Can be set via environment variable COPILOTSTUDIOAGENT__ENVIRONMENTID.
+        schemaname: The agent identifier or schema name of the Copilot to use.
+            Can be set via environment variable COPILOTSTUDIOAGENT__SCHEMANAME.
+        agentappid: The app ID of the App Registration used to login.
+            Can be set via environment variable COPILOTSTUDIOAGENT__AGENTAPPID.
+        tenantid: The tenant ID of the App Registration used to login.
+            Can be set via environment variable COPILOTSTUDIOAGENT__TENANTID.
+        env_file_path: If provided, the .env settings are read from this file path location.
+        env_file_encoding: The encoding of the .env file, defaults to 'utf-8'.
+
+    Examples:
+        .. code-block:: python
+
+            from agent_framework_copilotstudio import CopilotStudioSettings
+
+            # Using environment variables
+            # Set COPILOTSTUDIOAGENT__ENVIRONMENTID=env-123
+            # Set COPILOTSTUDIOAGENT__SCHEMANAME=my-agent
+            settings = CopilotStudioSettings()
+
+            # Or passing parameters directly
+            settings = CopilotStudioSettings(environmentid="env-123", schemaname="my-agent")
+
+            # Or loading from a .env file
+            settings = CopilotStudioSettings(env_file_path="path/to/.env")
+    """
+
+    env_prefix: ClassVar[str] = "COPILOTSTUDIOAGENT__"
+
+    environmentid: str | None = None
+    schemaname: str | None = None
+    agentappid: str | None = None
+    tenantid: str | None = None
+
+
+class CopilotStudioAgent(BaseAgent):
+    """A Copilot Studio Agent."""
+
+    def __init__(
+        self,
+        client: CopilotClient | None = None,
+        settings: ConnectionSettings | None = None,
+        *,
+        id: str | None = None,
+        name: str | None = None,
+        description: str | None = None,
+        context_providers: ContextProvider | list[ContextProvider] | AggregateContextProvider | None = None,
+        middleware: AgentMiddlewares | list[AgentMiddlewares] | None = None,
+        environment_id: str | None = None,
+        agent_identifier: str | None = None,
+        client_id: str | None = None,
+        tenant_id: str | None = None,
+        token: str | None = None,
+        cloud: PowerPlatformCloud | None = None,
+        agent_type: AgentType | None = None,
+        custom_power_platform_cloud: str | None = None,
+        username: str | None = None,
+        token_cache: Any | None = None,
+        scopes: list[str] | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+    ) -> None:
+        """Initialize the Copilot Studio Agent.
+
+        Args:
+            client: Optional pre-configured CopilotClient instance. If not provided,
+                a new client will be created using the other parameters.
+            settings: Optional pre-configured ConnectionSettings. If not provided,
+                settings will be created from the other parameters.
+
+        Keyword Args:
+            id: id of the CopilotAgent
+            name: Name of the CopilotAgent
+            description: Description of the CopilotAgent
+            context_providers: Context Providers, to be used by the copilot agent.
+            middleware: Agent middlewares used by the agent.
+            environment_id: Environment ID of the Power Platform environment containing
+                the Copilot Studio app. Can also be set via COPILOTSTUDIOAGENT__ENVIRONMENTID
+                environment variable.
+            agent_identifier: The agent identifier or schema name of the Copilot to use.
+                Can also be set via COPILOTSTUDIOAGENT__SCHEMANAME environment variable.
+            client_id: The app ID of the App Registration used for authentication.
+                Can also be set via COPILOTSTUDIOAGENT__AGENTAPPID environment variable.
+            tenant_id: The tenant ID of the App Registration used for authentication.
+                Can also be set via COPILOTSTUDIOAGENT__TENANTID environment variable.
+            token: Optional pre-acquired authentication token. If not provided,
+                token acquisition will be attempted using MSAL.
+            cloud: The Power Platform cloud to use (Public, GCC, etc.).
+            agent_type: The type of Copilot Studio agent (Copilot, Agent, etc.).
+            custom_power_platform_cloud: Custom Power Platform cloud URL if using
+                a custom environment.
+            username: Optional username for token acquisition.
+            token_cache: Optional token cache for storing authentication tokens.
+            scopes: Optional list of authentication scopes. Defaults to Power Platform
+                API scopes if not provided.
+            env_file_path: Optional path to .env file for loading configuration.
+            env_file_encoding: Encoding of the .env file, defaults to 'utf-8'.
+
+        Raises:
+            ServiceInitializationError: If required configuration is missing or invalid.
+        """
+        super().__init__(
+            id=id,
+            name=name,
+            description=description,
+            context_providers=context_providers,
+            middleware=middleware,
+        )
+        if not client:
+            try:
+                copilot_studio_settings = CopilotStudioSettings(
+                    environmentid=environment_id,
+                    schemaname=agent_identifier,
+                    agentappid=client_id,
+                    tenantid=tenant_id,
+                    env_file_path=env_file_path,
+                    env_file_encoding=env_file_encoding,
+                )
+            except ValidationError as ex:
+                raise ServiceInitializationError("Failed to create Copilot Studio settings.", ex) from ex
+
+            if not settings:
+                if not copilot_studio_settings.environmentid:
+                    raise ServiceInitializationError(
+                        "Copilot Studio environment ID is required. Set via 'environment_id' parameter "
+                        "or 'COPILOTSTUDIOAGENT__ENVIRONMENTID' environment variable."
+                    )
+                if not copilot_studio_settings.schemaname:
+                    raise ServiceInitializationError(
+                        "Copilot Studio agent identifier/schema name is required. Set via 'agent_identifier' parameter "
+                        "or 'COPILOTSTUDIOAGENT__SCHEMANAME' environment variable."
+                    )
+
+                settings = ConnectionSettings(
+                    environment_id=copilot_studio_settings.environmentid,
+                    agent_identifier=copilot_studio_settings.schemaname,
+                    cloud=cloud,
+                    copilot_agent_type=agent_type,
+                    custom_power_platform_cloud=custom_power_platform_cloud,
+                )
+
+            if not token:
+                if not copilot_studio_settings.agentappid:
+                    raise ServiceInitializationError(
+                        "Copilot Studio client ID is required. Set via 'client_id' parameter "
+                        "or 'COPILOTSTUDIOAGENT__AGENTAPPID' environment variable."
+                    )
+
+                if not copilot_studio_settings.tenantid:
+                    raise ServiceInitializationError(
+                        "Copilot Studio tenant ID is required. Set via 'tenant_id' parameter "
+                        "or 'COPILOTSTUDIOAGENT__TENANTID' environment variable."
+                    )
+
+                token = acquire_token(
+                    client_id=copilot_studio_settings.agentappid,
+                    tenant_id=copilot_studio_settings.tenantid,
+                    username=username,
+                    token_cache=token_cache,
+                    scopes=scopes,
+                )
+
+            client = CopilotClient(settings=settings, token=token)
+
+        self.client = client
+        self.cloud = cloud
+        self.agent_type = agent_type
+        self.custom_power_platform_cloud = custom_power_platform_cloud
+        self.username = username
+        self.token_cache = token_cache
+        self.scopes = scopes
+
+    async def run(
+        self,
+        messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
+        *,
+        thread: AgentThread | None = None,
+        **kwargs: Any,
+    ) -> AgentRunResponse:
+        """Get a response from the agent.
+
+        This method returns the final result of the agent's execution
+        as a single AgentRunResponse object. The caller is blocked until
+        the final result is available.
+
+        Note: For streaming responses, use the run_stream method, which returns
+        intermediate steps and the final result as a stream of AgentRunResponseUpdate
+        objects. Streaming only the final result is not feasible because the timing of
+        the final result's availability is unknown, and blocking the caller until then
+        is undesirable in streaming scenarios.
+
+        Args:
+            messages: The message(s) to send to the agent.
+
+        Keyword Args:
+            thread: The conversation thread associated with the message(s).
+            kwargs: Additional keyword arguments.
+
+        Returns:
+            An agent response item.
+        """
+        if not thread:
+            thread = self.get_new_thread()
+        thread.service_thread_id = await self._start_new_conversation()
+
+        input_messages = self._normalize_messages(messages)
+
+        question = "\n".join([message.text for message in input_messages])
+
+        activities = self.client.ask_question(question, thread.service_thread_id)
+        response_messages: list[ChatMessage] = []
+        response_id: str | None = None
+
+        response_messages = [message async for message in self._process_activities(activities, streaming=False)]
+        response_id = response_messages[0].message_id if response_messages else None
+
+        return AgentRunResponse(messages=response_messages, response_id=response_id)
+
+    async def run_stream(
+        self,
+        messages: str | ChatMessage | list[str] | list[ChatMessage] | None = None,
+        *,
+        thread: AgentThread | None = None,
+        **kwargs: Any,
+    ) -> AsyncIterable[AgentRunResponseUpdate]:
+        """Run the agent as a stream.
+
+        This method will return the intermediate steps and final results of the
+        agent's execution as a stream of AgentRunResponseUpdate objects to the caller.
+
+        Note: An AgentRunResponseUpdate object contains a chunk of a message.
+
+        Args:
+            messages: The message(s) to send to the agent.
+
+        Keyword Args:
+            thread: The conversation thread associated with the message(s).
+            kwargs: Additional keyword arguments.
+
+        Yields:
+            An agent response item.
+        """
+        if not thread:
+            thread = self.get_new_thread()
+        thread.service_thread_id = await self._start_new_conversation()
+
+        input_messages = self._normalize_messages(messages)
+
+        question = "\n".join([message.text for message in input_messages])
+
+        activities = self.client.ask_question(question, thread.service_thread_id)
+
+        async for message in self._process_activities(activities, streaming=True):
+            yield AgentRunResponseUpdate(
+                role=message.role,
+                contents=message.contents,
+                author_name=message.author_name,
+                raw_representation=message.raw_representation,
+                response_id=message.message_id,
+                message_id=message.message_id,
+            )
+
+    async def _start_new_conversation(self) -> str:
+        """Start a new conversation with the Copilot Studio agent.
+
+        Returns:
+            The conversation ID for the new conversation.
+
+        Raises:
+            ServiceException: If the conversation could not be started.
+        """
+        conversation_id: str | None = None
+
+        async for activity in self.client.start_conversation(emit_start_conversation_event=True):
+            if activity and activity.conversation and activity.conversation.id:
+                conversation_id = activity.conversation.id
+
+        if not conversation_id:
+            raise ServiceException("Failed to start a new conversation.")
+
+        return conversation_id
+
+    async def _process_activities(self, activities: AsyncIterable[Any], streaming: bool) -> AsyncIterable[ChatMessage]:
+        """Process activities from the Copilot Studio agent.
+
+        Args:
+            activities: Stream of activities from the agent.
+            streaming: Whether to process activities for streaming (typing activities)
+                or non-streaming (message activities) responses.
+
+        Yields:
+            ChatMessage objects created from the activities.
+        """
+        async for activity in activities:
+            if activity.text and (
+                (activity.type == "message" and not streaming) or (activity.type == "typing" and streaming)
+            ):
+                yield ChatMessage(
+                    role=Role.ASSISTANT,
+                    contents=[TextContent(activity.text)],
+                    author_name=activity.from_property.name if activity.from_property else None,
+                    message_id=activity.id,
+                    raw_representation=activity,
+                )

agent_framework_copilotstudio-1.0.0b251112.dist-info/METADATA

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: agent-framework-copilotstudio
+Version: 1.0.0b251112
+Summary: Copilot Studio integration for Microsoft Agent Framework.
+Author-email: Microsoft <af-support@microsoft.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: agent-framework-core
+Requires-Dist: microsoft-agents-copilotstudio-client>=0.3.1
+Project-URL: homepage, https://aka.ms/agent-framework
+Project-URL: issues, https://github.com/microsoft/agent-framework/issues
+Project-URL: release_notes, https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true
+Project-URL: source, https://github.com/microsoft/agent-framework/tree/main/python
+
+# Get Started with Microsoft Agent Framework Copilot Studio
+
+Please install this package via pip:
+
+```bash
+pip install agent-framework-copilotstudio --pre
+```
+
+## Copilot Studio Agent
+
+The Copilot Studio agent enables integration with Microsoft Copilot Studio, allowing you to interact with published copilots through the Agent Framework.
+
+### Prerequisites
+
+Before using the Copilot Studio agent, you need:
+
+1. **Copilot Studio Environment**: Access to a Microsoft Copilot Studio environment with a published copilot
+2. **App Registration**: An Azure AD App Registration with appropriate permissions for Power Platform API
+3. **Environment Configuration**: Set the required environment variables or pass them as parameters
+
+### Environment Variables
+
+The following environment variables are used for configuration:
+
+- `COPILOTSTUDIOAGENT__ENVIRONMENTID` - Your Copilot Studio environment ID
+- `COPILOTSTUDIOAGENT__SCHEMANAME` - Your copilot's agent identifier/schema name
+- `COPILOTSTUDIOAGENT__AGENTAPPID` - Your App Registration client ID
+- `COPILOTSTUDIOAGENT__TENANTID` - Your Azure AD tenant ID
+
+### Basic Usage Example
+
+```python
+import asyncio
+from agent_framework.microsoft import CopilotStudioAgent
+
+async def main():
+    # Create agent using environment variables
+    agent = CopilotStudioAgent()
+
+    # Run a simple query
+    result = await agent.run("What is the capital of France?")
+    print(result)
+
+asyncio.run(main())
+```
+
+### Explicit Configuration Example
+
+```python
+import asyncio
+import os
+from agent_framework.microsoft import CopilotStudioAgent, acquire_token
+from microsoft_agents.copilotstudio.client import ConnectionSettings, CopilotClient, PowerPlatformCloud, AgentType
+
+async def main():
+    # Acquire authentication token
+    token = acquire_token(
+        client_id=os.environ["COPILOTSTUDIOAGENT__AGENTAPPID"],
+        tenant_id=os.environ["COPILOTSTUDIOAGENT__TENANTID"]
+    )
+
+    # Create connection settings
+    settings = ConnectionSettings(
+        environment_id=os.environ["COPILOTSTUDIOAGENT__ENVIRONMENTID"],
+        agent_identifier=os.environ["COPILOTSTUDIOAGENT__SCHEMANAME"],
+        cloud=PowerPlatformCloud.PROD,
+        copilot_agent_type=AgentType.PUBLISHED,
+        custom_power_platform_cloud=None
+    )
+
+    # Create client and agent
+    client = CopilotClient(settings=settings, token=token)
+    agent = CopilotStudioAgent(client=client)
+
+    # Run a query
+    result = await agent.run("What is the capital of Italy?")
+    print(result)
+
+asyncio.run(main())
+```
+
+### Authentication
+
+The package uses MSAL (Microsoft Authentication Library) for authentication with interactive flows when needed. Ensure your App Registration has:
+
+- **API Permissions**: Power Platform API permissions (https://api.powerplatform.com/.default)
+- **Redirect URIs**: Configured appropriately for your authentication method
+- **Public Client Flows**: Enabled if using interactive authentication
+
+### Examples
+
+For more comprehensive examples, see the [Copilot Studio examples](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/agents/copilotstudio/) which demonstrate:
+
+- Basic non-streaming and streaming execution
+- Explicit settings and manual token acquisition
+- Different authentication patterns
+- Error handling and troubleshooting
+

agent_framework_copilotstudio-1.0.0b251112.dist-info/RECORD

@@ -0,0 +1,7 @@
+agent_framework_copilotstudio/__init__.py,sha256=n5OgoxpgvDY7Ttcgjcd0UG55d2fDmtWt6NmgvxYQOaU,391
+agent_framework_copilotstudio/_acquire_token.py,sha256=LzG4_U7jJyghDIndGJfV6tMq7LgfCpN2WaGXS8r83NQ,3675
+agent_framework_copilotstudio/_agent.py,sha256=WB_nR2Yvt86FAlHeQj3Zd-XKMgSisfOHbH6bwSxUh5o,14558
+agent_framework_copilotstudio-1.0.0b251112.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
+agent_framework_copilotstudio-1.0.0b251112.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+agent_framework_copilotstudio-1.0.0b251112.dist-info/METADATA,sha256=VIuNoP0Ww736lbb5ELKBvDGvQBUY-ijs1KLskENoPCA,4481
+agent_framework_copilotstudio-1.0.0b251112.dist-info/RECORD,,

agent_framework_copilotstudio-1.0.0b251112.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_framework_copilotstudio-1.0.0b251112.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE