mirror of
https://github.com/microsoft/agent-framework.git
synced 2026-06-16 21:04:09 +08:00
Python: restructure: Python samples into progressive 01-05 layout (#3862)
* restructure: Python samples into progressive 01-05 layout - 01-get-started/: 6 numbered steps (hello agent → hosting) - 02-agents/: all agent concept samples (tools, middleware, providers, etc.) - 03-workflows/: ALL existing workflow samples preserved as-is - 04-hosting/: azure-functions, durabletask, a2a - 05-end-to-end/: demos, evaluation, hosted agents - Old files moved to _to_delete/ for review - Added AGENTS.md with structure documentation - autogen-migration/ and semantic-kernel-migration/ preserved at root * fix: switch to AzureOpenAI Foundry, fix CI failures - Switch all 01-get-started samples to AzureOpenAIResponsesClient with Azure AI Foundry project endpoint (AZURE_AI_PROJECT_ENDPOINT + AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME + AzureCliCredential) - Add _to_delete/ and 05-end-to-end/ to pyrightconfig.samples.json excludes - Fix test paths in packages/ that referenced old getting_started/ dirs: durabletask conftest + streaming test, azurefunctions conftest, devui conftest + capture_messages + openai_sdk_integration - Fix workflow_as_agent_human_in_the_loop.py import (sibling import) - Update hosting READMEs and tool comment paths - Replace root README.md with new structure overview - Update AGENTS.md to document Azure OpenAI Foundry as default provider * cleanup: remove _to_delete folder, copy resource files to active dirs All files in _to_delete/ were either: - Exact duplicates of files in the new structure (240 files) - Same file with only comment path updates (100 files) - One import-fix diff (workflow_as_agent_human_in_the_loop.py) - One superseded minimal_sample.py Resource files (sample.pdf, countries.json, employees.pdf, weather.json) copied to 02-agents/sample_assets/ and 02-agents/resources/ since active samples reference them. * fix: address PR review comments, centralize resources, remove root duplicates - Fix type annotation in 04_memory.py (string union -> proper types) - Fix old sample paths in observability files - Fix grammar/spelling in observability samples - Move sample_assets/ and resources/ to shared/ folder - Remove 8 duplicate observability files from 02-agents root - Update resource path references in multimodal_input and provider samples * fix: update broken links from old getting_started paths to new structure - Update relative paths in READMEs: getting_started/ → 01-get-started/, 02-agents/, 03-workflows/, 04-hosting/, 05-end-to-end/ - Fix absolute GitHub URLs in package READMEs - Fix broken link in ollama package README * fix: convert absolute GitHub URLs to relative paths for link checker Absolute URLs to python/samples/ on main branch 404 until PR merges. Converted to relative paths that linkspector can verify locally. * fix: update link for handoff sample moved to orchestrations/ * fix: update chatkit-integration README path from demos/ to 05-end-to-end/ * fix: update broken links in orchestrations README to match flat directory structure
This commit is contained in:
Eduard van Valkenburg
@@ -0,0 +1,105 @@
|
||||
# Copilot Studio Agent Examples
|
||||
|
||||
This folder contains examples demonstrating how to create and use agents with Microsoft Copilot Studio using the Agent Framework.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before running these examples, 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
|
||||
3. **Environment Variables**: Set the following environment variables:
|
||||
- `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
|
||||
|
||||
## Examples
|
||||
|
||||
| Example | Description |
|
||||
|---------|-------------|
|
||||
| **[`copilotstudio_basic.py`](copilotstudio_basic.py)** | Basic non-streaming and streaming execution with simple questions |
|
||||
| **[`copilotstudio_with_explicit_settings.py`](copilotstudio_with_explicit_settings.py)** | Example with explicit settings and manual token acquisition |
|
||||
|
||||
## Authentication
|
||||
|
||||
The examples use MSAL (Microsoft Authentication Library) for authentication. The first time you run an example, you may need to complete an interactive authentication flow in your browser.
|
||||
|
||||
### App Registration Setup
|
||||
|
||||
Your Azure AD App Registration should have:
|
||||
|
||||
1. **API Permissions**:
|
||||
- Power Platform API permissions (https://api.powerplatform.com/.default)
|
||||
- Appropriate delegated permissions for your organization
|
||||
|
||||
2. **Redirect URIs**:
|
||||
- For public client flows: `http://localhost`
|
||||
- Configure as appropriate for your authentication method
|
||||
|
||||
3. **Authentication**:
|
||||
- Enable "Allow public client flows" if using interactive authentication
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### Basic Usage with Environment Variables
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
from agent_framework.microsoft import CopilotStudioAgent
|
||||
|
||||
# Uses environment variables for configuration
|
||||
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
|
||||
|
||||
```python
|
||||
from agent_framework.microsoft import CopilotStudioAgent, acquire_token
|
||||
from microsoft_agents.copilotstudio.client import ConnectionSettings, CopilotClient, PowerPlatformCloud, AgentType
|
||||
|
||||
# Acquire token manually
|
||||
token = acquire_token(
|
||||
client_id="your-client-id",
|
||||
tenant_id="your-tenant-id"
|
||||
)
|
||||
|
||||
# Create settings and client
|
||||
settings = ConnectionSettings(
|
||||
environment_id="your-environment-id",
|
||||
agent_identifier="your-agent-schema-name",
|
||||
cloud=PowerPlatformCloud.PROD,
|
||||
copilot_agent_type=AgentType.PUBLISHED,
|
||||
custom_power_platform_cloud=None
|
||||
)
|
||||
|
||||
client = CopilotClient(settings=settings, token=token)
|
||||
agent = CopilotStudioAgent(client=client)
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Authentication Errors**:
|
||||
- Verify your App Registration has correct permissions
|
||||
- Ensure environment variables are set correctly
|
||||
- Check that your tenant ID and client ID are valid
|
||||
|
||||
2. **Environment/Agent Not Found**:
|
||||
- Verify your environment ID is correct
|
||||
- Ensure your copilot is published and the schema name is correct
|
||||
- Check that you have access to the specified environment
|
||||
|
||||
3. **Token Acquisition Failures**:
|
||||
- Interactive authentication may require browser access
|
||||
- Corporate firewalls may block authentication flows
|
||||
- Try running with appropriate proxy settings if needed
|
||||
@@ -0,0 +1,54 @@
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
|
||||
from agent_framework.microsoft import CopilotStudioAgent
|
||||
|
||||
"""
|
||||
Copilot Studio Agent Basic Example
|
||||
|
||||
This sample demonstrates basic usage of CopilotStudioAgent with automatic configuration
|
||||
from environment variables, showing both streaming and non-streaming responses.
|
||||
"""
|
||||
|
||||
# Environment variables needed:
|
||||
# COPILOTSTUDIOAGENT__ENVIRONMENTID - Environment ID where your copilot is deployed
|
||||
# COPILOTSTUDIOAGENT__SCHEMANAME - Agent identifier/schema name of your copilot
|
||||
# COPILOTSTUDIOAGENT__AGENTAPPID - Client ID for authentication
|
||||
# COPILOTSTUDIOAGENT__TENANTID - Tenant ID for authentication
|
||||
|
||||
|
||||
async def non_streaming_example() -> None:
|
||||
"""Example of non-streaming response (get the complete result at once)."""
|
||||
print("=== Non-streaming Response Example ===")
|
||||
|
||||
agent = CopilotStudioAgent()
|
||||
|
||||
query = "What is the capital of France?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result}\n")
|
||||
|
||||
|
||||
async def streaming_example() -> None:
|
||||
"""Example of streaming response (get results as they are generated)."""
|
||||
print("=== Streaming Response Example ===")
|
||||
|
||||
agent = CopilotStudioAgent()
|
||||
|
||||
query = "What is the capital of Spain?"
|
||||
print(f"User: {query}")
|
||||
print("Agent: ", end="", flush=True)
|
||||
async for chunk in agent.run(query, stream=True):
|
||||
if chunk.text:
|
||||
print(chunk.text, end="", flush=True)
|
||||
print("\n")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
await non_streaming_example()
|
||||
await streaming_example()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
+103
@@ -0,0 +1,103 @@
|
||||
# /// script
|
||||
# requires-python = ">=3.10"
|
||||
# dependencies = [
|
||||
# "microsoft-agents",
|
||||
# ]
|
||||
# ///
|
||||
# Run with any PEP 723 compatible runner, e.g.:
|
||||
# uv run samples/getting_started/agents/copilotstudio/copilotstudio_with_explicit_settings.py
|
||||
|
||||
# Copyright (c) Microsoft. All rights reserved.
|
||||
|
||||
import asyncio
|
||||
import os
|
||||
|
||||
from agent_framework.microsoft import CopilotStudioAgent, acquire_token
|
||||
from microsoft_agents.copilotstudio.client import AgentType, ConnectionSettings, CopilotClient, PowerPlatformCloud
|
||||
|
||||
"""
|
||||
Copilot Studio Agent with Explicit Settings Example
|
||||
|
||||
This sample demonstrates explicit configuration of CopilotStudioAgent with manual
|
||||
token management and custom ConnectionSettings for production environments.
|
||||
"""
|
||||
|
||||
# Environment variables needed:
|
||||
# COPILOTSTUDIOAGENT__ENVIRONMENTID - Environment ID where your copilot is deployed
|
||||
# COPILOTSTUDIOAGENT__SCHEMANAME - Agent identifier/schema name of your copilot
|
||||
# COPILOTSTUDIOAGENT__AGENTAPPID - Client ID for authentication
|
||||
# COPILOTSTUDIOAGENT__TENANTID - Tenant ID for authentication
|
||||
|
||||
|
||||
async def example_with_connection_settings() -> None:
|
||||
"""Example using explicit ConnectionSettings and CopilotClient."""
|
||||
print("=== Copilot Studio Agent with Connection Settings ===")
|
||||
|
||||
# Configuration from environment variables
|
||||
environment_id = os.environ["COPILOTSTUDIOAGENT__ENVIRONMENTID"]
|
||||
agent_identifier = os.environ["COPILOTSTUDIOAGENT__SCHEMANAME"]
|
||||
client_id = os.environ["COPILOTSTUDIOAGENT__AGENTAPPID"]
|
||||
tenant_id = os.environ["COPILOTSTUDIOAGENT__TENANTID"]
|
||||
|
||||
# Acquire token using the acquire_token function
|
||||
token = acquire_token(
|
||||
client_id=client_id,
|
||||
tenant_id=tenant_id,
|
||||
)
|
||||
|
||||
# Create connection settings
|
||||
settings = ConnectionSettings(
|
||||
environment_id=environment_id,
|
||||
agent_identifier=agent_identifier,
|
||||
cloud=PowerPlatformCloud.PROD, # Or PowerPlatformCloud.GOV, PowerPlatformCloud.HIGH, etc.
|
||||
copilot_agent_type=AgentType.PUBLISHED, # Or AgentType.PREBUILT
|
||||
custom_power_platform_cloud=None, # Optional: for custom cloud endpoints
|
||||
)
|
||||
|
||||
# Create CopilotClient with explicit settings
|
||||
client = CopilotClient(settings=settings, token=token)
|
||||
|
||||
# Create agent with explicit client
|
||||
agent = CopilotStudioAgent(client=client)
|
||||
|
||||
# Run a simple query
|
||||
query = "What is the capital of Italy?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result}")
|
||||
|
||||
|
||||
async def example_with_explicit_parameters() -> None:
|
||||
"""Example using CopilotStudioAgent with all parameters explicitly provided."""
|
||||
print("\n=== Copilot Studio Agent with All Explicit Parameters ===")
|
||||
|
||||
# Configuration from environment variables
|
||||
environment_id = os.environ["COPILOTSTUDIOAGENT__ENVIRONMENTID"]
|
||||
agent_identifier = os.environ["COPILOTSTUDIOAGENT__SCHEMANAME"]
|
||||
client_id = os.environ["COPILOTSTUDIOAGENT__AGENTAPPID"]
|
||||
tenant_id = os.environ["COPILOTSTUDIOAGENT__TENANTID"]
|
||||
|
||||
# Create agent with all parameters explicitly
|
||||
agent = CopilotStudioAgent(
|
||||
environment_id=environment_id,
|
||||
agent_identifier=agent_identifier,
|
||||
client_id=client_id,
|
||||
tenant_id=tenant_id,
|
||||
cloud=PowerPlatformCloud.PROD,
|
||||
agent_type=AgentType.PUBLISHED,
|
||||
)
|
||||
|
||||
# Run a simple query
|
||||
query = "What is the capital of Japan?"
|
||||
print(f"User: {query}")
|
||||
result = await agent.run(query)
|
||||
print(f"Agent: {result}")
|
||||
|
||||
|
||||
async def main() -> None:
|
||||
await example_with_connection_settings()
|
||||
await example_with_explicit_parameters()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
Reference in New Issue
Block a user