diff --git a/CLAUDE.md b/CLAUDE.md index 21237bb6..c26ef47d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -134,9 +134,9 @@ Central NuGet package management in `src/Directory.Packages.props`. Key dependen ## Key Documentation -- `Readme-Usage.md` - CLI usage guide with examples +- [Agent 365 CLI reference](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/) - CLI usage guide with examples - `.github/copilot-instructions.md` - Code standards and review rules -- `docs/commands/` - Individual command documentation +- `docs/commands/` - Index/pointers to CLI command documentation on Microsoft Learn ## Code Review Checklist diff --git a/Readme-Usage.md b/Readme-Usage.md deleted file mode 100644 index 2268a3a5..00000000 --- a/Readme-Usage.md +++ /dev/null @@ -1,494 +0,0 @@ -# Microsoft Agent 365 CLI - -A command-line tool for deploying and managing Microsoft Agent 365 applications on Azure. - -## Supported Platforms -- ✅ .NET Applications -- ✅ Node.js Applications -- ✅ **Python Applications** (Auto-detects via `pyproject.toml`, handles Microsoft Agent 365 dependencies, converts .env to Azure App Settings) - -## Quick Start - -### 1. Install the CLI - -**From NuGet (Production):** -```bash -dotnet tool install -g Microsoft.Agents.A365.DevTools.Cli -``` - -### 2. Configure - -Configure the CLI using the interactive wizard: - -```bash -a365 config init -``` - -The wizard provides: -- **Azure CLI integration** - Automatically detects your Azure subscription, tenant, and resources -- **Smart defaults** - Uses values from existing configuration or generates sensible defaults -- **Minimal input** - Only requires 2-3 core values (agent name, deployment path, manager email) -- **Auto-generation** - Creates related resource names from your agent name -- **Platform detection** - Validates your project type (.NET, Node.js, or Python) - -**What you'll be prompted for:** -- **Agent name** - A unique identifier for your agent (alphanumeric only) -- **Deployment project path** - Path to your agent project directory -- **Manager email** - Email of the manager overseeing this agent -- **Azure resources** - Select from existing resource groups and app service plans - -The wizard will automatically generate: -- Web app names -- Agent identity names -- User principal names -- Display names - -**Import from file:** -```bash -a365 config init -c path/to/config.json -``` - -**Global configuration:** -```bash -a365 config init --global -``` - -**Configure custom blueprint permissions:** -```bash -# Add custom API permissions for your agent -a365 config permissions --resource-app-id 00000003-0000-0000-c000-000000000000 \ - --scopes Presence.ReadWrite,Files.Read.All - -# View configured permissions -a365 config permissions - -# Clear all custom permissions -a365 config permissions --reset -``` - -**Minimum required configuration:** -```json -{ - "tenantId": "your-tenant-id", - "subscriptionId": "your-subscription-id", - "resourceGroup": "rg-agent365-dev", - "location": "westus", - "webAppName": "webapp-agent365-dev", - "agentIdentityDisplayName": "Agent 365 Development Agent", - "agentUserPrincipalName": "agent.username@yourdomain.onmicrosoft.com", - "agentUserDisplayName": "Username's Agent User", - "deploymentProjectPath": "./src" -} -``` - -See `a365.config.example.json` for all available options. - -### 3. Setup (Blueprint + Messaging Endpoint) - -```bash -# Create agent blueprint and register messaging endpoint -a365 setup all -``` - -- This command creates the agent blueprint and registers the messaging endpoint for your application. -- No subcommands are required. Deployment and messaging endpoint registration are handled together. - -### 4. Publish and Deploy - -```bash -# Publish manifest to MOS (Microsoft Online Services) -a365 publish - -# Deploy application binaries (for Azure-hosted agents) -# Can be run before or after publish -a365 deploy -``` - -- After publishing, hire your agent through Microsoft Teams to complete onboarding. -- See [Microsoft Learn documentation](https://learn.microsoft.com/en-us/microsoft-agent-365/onboard) for the complete workflow. - -### 5. Query Microsoft Entra ID information -```bash -a365 query-entra blueprint-scopes -a365 query-entra instance-scopes -``` - ---- - -## Common Commands - -See below for frequently used commands. For full details, run `a365 --help` or see the CLI reference in the documentation. - -### Setup & Registration -```bash -a365 setup all -``` - -If infrastructure has already been deployed then skip the deployment using: -```bash -a365 setup all --skip-infrastructure -``` - -The above command will run the following commands in sequence. You may also run the commands individually. -```bash -a365 setup infrastructure -a365 setup blueprint -a365 setup permissions mcp -a365 setup permissions bot -a365 setup permissions custom # Configure custom blueprint permissions (if configured) -a365 setup permissions copilotstudio # Configure Copilot Studio permissions -``` - -**Custom Blueprint Permissions:** -If your agent needs additional API permissions beyond the standard set (e.g., Presence, Files, Chat, or custom APIs), configure them before running setup: - -```bash -# Add custom permissions to config -a365 config permissions --resource-app-id 00000003-0000-0000-c000-000000000000 \ - --scopes Presence.ReadWrite,Files.Read.All - -# Then run setup (custom permissions applied automatically) -a365 setup all - -# Or apply custom permissions separately -a365 setup permissions custom -``` - -See [Custom Permissions Guide](docs/commands/setup-permissions-custom.md) for detailed examples. - -### Publish & Deploy -```bash -a365 publish # Publish manifest to MOS -a365 deploy # Deploy application to Azure (optional) -``` - -> **Note:** After publishing, hire your agent through Microsoft Teams to complete onboarding. -> See the [onboarding guide](https://learn.microsoft.com/en-us/microsoft-agent-365/onboard). - -### Deploy & Cleanup -```bash -a365 deploy # Full build and deploy -a365 deploy app # Deploy application binaries to the configured Azure App Service -a365 deploy mcp # Update Microsoft Agent 365 Tool permissions -a365 deploy --restart # Skip build, deploy existing publish folder (quick iteration) -a365 deploy --inspect # Pause before deployment to verify package contents -a365 deploy --restart --inspect # Combine flags for quick redeploy with inspection -a365 cleanup -``` - -**Deploy Options Explained:** -- **Default** (`a365 deploy`): Full build pipeline - platform detection, environment validation, build, manifest creation, packaging, and deployment -- **app**: Deploy application binaries to the configured Azure App Service -- **mcp**: Update Microsoft Agent 365 Tool permissions -- **`--restart`**: Skip all build steps and start from compressing the existing `publish/` folder. Perfect for quick iteration when you've manually modified files in the publish directory (e.g., tweaking `requirements.txt`, `.deployment`, or other config files) -- **`--inspect`**: Pause before deployment to review the publish folder and ZIP contents. Useful for verifying package structure before uploading to Azure -- **`--verbose`**: Enable detailed logging for all build and deployment steps -- **`--dry-run`**: Show what would be deployed without actually executing - -### Query & Develop -```bash -a365 query-entra blueprint-scopes -a365 query-entra instance-scopes -a365 develop --list -``` - -### MCP Server Management - -Manage Model Context Protocol (MCP) servers in Dataverse environments. The CLI automatically uses the production environment unless a configuration file is specified with `--config`. - -```bash -# List Dataverse environments -a365 develop-mcp list-environments - -# List MCP servers in a specific environment -a365 develop-mcp list-servers -e "Default-12345678-1234-1234-1234-123456789abc" - -# Publish an MCP server -a365 develop-mcp publish -e "Default-12345678-1234-1234-1234-123456789abc" -s "msdyn_MyMcpServer" - -# Unpublish an MCP server -a365 develop-mcp unpublish -e "Default-12345678-1234-1234-1234-123456789abc" -s "msdyn_MyMcpServer" - -# Approve/block MCP servers (global operations, no environment needed) -a365 develop-mcp approve -s "msdyn_MyMcpServer" -a365 develop-mcp block -s "msdyn_MyMcpServer" - -# All commands support dry-run for safe testing -a365 develop-mcp publish -e "myenv" -s "myserver" --dry-run - -# Use verbose output for detailed logging -a365 develop-mcp list-environments --verbose -``` - ---- - -## Multiplatform Deployment Support - -The Agent 365 CLI automatically detects and deploys applications built with: - -### .NET Applications -- **Detection:** Looks for `*.csproj`, `*.fsproj`, or `*.vbproj` files -- **Build Process:** `dotnet restore` → `dotnet publish` -- **Deployment:** Creates Oryx manifest with `dotnet YourApp.dll` command -- **Requirements:** .NET SDK installed - -### Node.js Applications -- **Detection:** Looks for `package.json` file -- **Build Process:** `npm ci` → `npm run build` (if build script exists) -- **Deployment:** Creates Oryx manifest with start script from `package.json` -- **Requirements:** Node.js and npm installed - -### Python Applications -- **Detection:** Looks for `requirements.txt`, `setup.py`, `pyproject.toml`, or `*.py` files -- **Build Process:** Copies project files, handles local wheel packages in `dist/`, creates deployment configuration -- **Deployment:** Creates Oryx manifest with appropriate start command (gunicorn, uvicorn, or python) -- **Requirements:** Python 3.11+ and pip installed -- **Special Features:** - - Automatically converts `.env` to Azure App Settings - - Handles local Agent 365 packages via `--find-links dist` - - Creates `requirements.txt` with `--pre` flag for pre-release packages - - Detects Agent 365 entry points (`start_with_generic_host.py`) - - Sets correct Python startup command automatically - -### Deployment Example -```bash -# Works for any supported platform - CLI auto-detects! -a365 deploy - -# With verbose output to see build details -a365 deploy --verbose - -# Test what would be deployed without executing -a365 deploy --dry-run -``` - -The CLI automatically: -1. Detects your project platform -2. Validates required tools are installed -3. Cleans previous build artifacts -4. Builds your application using platform-specific tools -5. Creates an appropriate Oryx manifest for Azure App Service -6. Packages and deploys to Azure - ---- - -## Configuration - - -The CLI always updates both `a365.config.json` (static config) and `a365.generated.config.json` (dynamic state) in: - -- **%LocalAppData%\Microsoft.Agents.A365.DevTools.Cli** (Windows) or `$HOME/.config/Microsoft.Agents.A365.DevTools.Cli` (Linux/macOS) — this is the global user config/state location and is always kept up to date. -- The **current working directory** — but only if the file already exists there. The CLI will NOT create new config/state files in the current directory unless you explicitly do so. - -This prevents leaving config "crumbs" in random folders and ensures your configuration and state are always available and consistent. - -**Working across multiple directories:** - -- If you run CLI commands in different folders, each folder may have its own `a365.generated.config.json`. -- The CLI will warn you if the local generated config is older than the global config in your user profile. This helps prevent using stale configuration by accident. -- If you see this warning, you should consider running `a365 setup all` again in your current directory, or manually sync the latest config from your global config folder. -- Best practice: Work from a single project directory, or always ensure your local config is up to date before running commands. - -You can create or update these files using `a365 config init` (interactive) or `a365 config init -c ` (import). If you want a config in your current directory, create it there first. - -See `a365.config.example.json` for all available options and schema. - ---- - -## Troubleshooting - -### Configuration Issues -- **Config file not found:** - - Create it: `cp a365.config.example.json a365.config.json` - - Or specify with `--config path/to/config.json` -- **Missing mandatory fields:** - - Run: `a365 config init` to interactively set required values - - Ensure `agentUserPrincipalName` follows UPN format (username@domain) - - Verify `deploymentProjectPath` points to an existing directory -- **Invalid UPN format:** - - Use email-like format: `agent.name@yourdomain.onmicrosoft.com` - - Avoid spaces or special characters except `.`, `@`, and `-` -- **Project path not found:** - - Use absolute paths or paths relative to where you run the CLI - - Ensure the directory exists and contains your agent project files -- **Not logged into Azure:** - - Run: `az login --tenant YOUR_TENANT_ID` - - Set subscription: `az account set --subscription YOUR_SUBSCRIPTION_ID` - -### Deployment Issues -- **Platform not detected:** - - Ensure your project has the required files (.csproj, package.json, requirements.txt, or .py files) - - Check that `deploymentProjectPath` points to the correct directory -- **.NET deployment fails:** - - Verify .NET SDK is installed: `dotnet --version` - - Ensure project file is valid and builds locally: `dotnet build` -- **Node.js deployment fails:** - - Verify Node.js and npm are installed: `node --version` and `npm --version` - - Test local build: `npm install` and `npm run build` (if applicable) -- **Python deployment fails:** - - Verify Python and pip are installed: `python --version` and `pip --version` - - Test local install: `pip install -r requirements.txt` -- **`--restart` fails with "Publish folder not found":** - - Run full build first: `a365 deploy` (without `--restart`) - - Verify `publish/` folder exists in your project directory - - Check that `deploymentProjectPath` in config points to correct location - -### Authentication & Permissions -- **Admin consent required:** - - Open consent URLs printed by the CLI and approve as Global Admin -- **Agent identity/user IDs not saved:** - - Re-run: `a365 create-instance identity` - - Check `a365.generated.config.json` for IDs -- **Messaging endpoint registration failed:** - - Ensure your tenant has required M365 licenses - -### General Issues -- **Windows: Azure CLI issues:** - - Verify Azure CLI: `az --version` - - Reinstall CLI: `dotnet tool uninstall -g Microsoft.Agents.A365.DevTools.Cli` then `pwsh ./install-cli.ps1` - -### Debugging with Log Files - -The CLI automatically logs all commands to help with debugging. When reporting issues, share the relevant log file. - -**Log Locations:** -- **Windows:** `%LocalAppData%\Microsoft.Agents.A365.DevTools.Cli\logs\` -- **Linux/Mac:** `~/.config/a365/logs/` - -**View Latest Logs:** -```powershell -# Windows (PowerShell) -Get-Content $env:LOCALAPPDATA\Microsoft.Agents.A365.DevTools.Cli\logs\a365.setup.log -Tail 50 -``` - -```bash -# Linux/Mac -tail -50 ~/.config/a365/logs/a365.setup.log -``` - -Each command has its own log file (`a365.setup.log`, `a365.deploy.log`, etc.). The CLI keeps only the latest run of each command. - ---- - -## Getting Help - -```bash -# General help -a365 --help - -# Command-specific help -a365 setup --help -a365 create-instance --help -a365 deploy --help -a365 develop --help -a365 develop-mcp --help -a365 query-entra --help -a365 config --help - -``` - - ---- - -## Developer & Contributor Info - -For build, test, architecture, and contributing instructions, see [DEVELOPER.md](./DEVELOPER.md). - ---- - -## License - -Copyright (c) Microsoft Corporation. All rights reserved. - -Licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details. - ---- - -## Getting Help - -```bash -# General help -a365 --help - -# Command-specific help -a365 setup --help -a365 createinstance --help -a365 deploy --help -a365 develop --help -``` - ---- - -## Technical Notes - -### Messaging Endpoint Registration Architecture - -The `a365 setup blueprint` command configures the agent blueprint and registers the messaging endpoint using the blueprint identity. This ensures proper identity isolation and secure communication for your agent application. - -**Key Technical Details:** -- Messaging endpoint registration uses the agent blueprint identity (from `a365.generated.config.json`) -- The endpoint is registered for Teams/channel communication -- App Service managed identity handles Azure resource access (Key Vault, etc.) -- This architecture follows Azure security best practices for identity isolation - -**Command ordering:** Messaging endpoint registration happens after blueprint creation to use the actual deployed web app URL for the endpoint. - -**Generated during:** -```bash -a365 setup blueprint # Creates agent blueprint and registers messaging endpoint -``` - ---- - -## Prerequisites - -### Required for All Projects -- **Azure CLI** (`az`) - logged into your tenant -- **PowerShell 7+** (for development scripts) -- **Azure Global Administrator role** (for admin consent) -- **M365 licenses** in your tenant (for agent users) - -### Platform-Specific Requirements -Choose based on your application type: - -- **.NET Projects:** .NET 8.0 SDK or later -- **Node.js Projects:** Node.js (20+ recommended) and npm -- **Python Projects:** Python 3.11+ and pip - -The CLI will validate that required tools are installed before deployment. - ---- - -## License - -MIT License - -Copyright (c) 2025 Microsoft - -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. - - - -## 📋 **Telemetry** - -Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. - -## Trademarks - -*Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.* diff --git a/docs/commands/README.md b/docs/commands/README.md new file mode 100644 index 00000000..d02a0e5f --- /dev/null +++ b/docs/commands/README.md @@ -0,0 +1,55 @@ +# Documentation for Agent 365 CLI commands + +Reference documentation about using commands is published at [Agent 365 CLI reference](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/). + +There is reference documentation for each command. + +| Command | Description | +| --- | --- | +| [cleanup](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/cleanup) | Cleans up ALL resources (blueprint, instance, and Azure). Use subcommands for granular cleanup. | +| [cleanup blueprint](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/cleanup#cleanup-blueprint) | Remove Entra ID blueprint application and service principal. | +| [cleanup azure](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/cleanup#cleanup-azure) | Remove Azure resources (App Service, App Service Plan). | +| [cleanup instance](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/cleanup#cleanup-instance) | Remove agent instance identity and user from Entra ID. | +| [config](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/config) | Manage Agent 365 CLI configuration settings. | +| [config init](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/config#config-init) | Interactively configure Agent 365 CLI or import from a file. | +| [config display](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/config#config-display) | Show current Agent 365 CLI configuration. | +| [create-instance](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/create-instance) | This command is temporarily removed. Use `a365 publish` to create an agent instance via Teams instead. | +| [deploy](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/deploy) | Deploy Agent 365 application binaries to the configured Azure App Service and update Agent 365 Tool permissions | +| [deploy app](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/deploy#deploy-app) | Deploys your agent code to the Azure Web App created during setup. | +| [deploy mcp](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/deploy#deploy-mcp) | Updates MCP server permissions on your agent blueprint. | +| [develop](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop) | Manage MCP tool servers for agent development. | +| [develop list-available](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop#develop-list-available) | List all MCP servers available in the catalog (what you can install). | +| [develop list-configured](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop#develop-list-configured) | List currently configured MCP servers from your local ToolingManifest.json. | +| [develop add-mcp-servers](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop#develop-add-mcp-servers) | Add MCP Servers to the current agent configuration. | +| [develop remove-mcp-servers](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop#develop-remove-mcp-servers) | Remove MCP Servers from the current agent configuration. | +| [develop add-permissions](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop#develop-add-permissions) | Add MCP server API permissions to Microsoft Entra applications for development scenarios where you need to configure custom applications to access MCP servers. | +| [develop get-token](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop#develop-get-token) | Retrieve bearer tokens for testing MCP servers during development using interactive browser authentication. | +| [develop start-mock-tooling-server](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop#develop-start-mock-tooling-server) | Start a mock tooling server for testing and development purposes. | +| [develop-mcp](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop-mcp) | Manage MCP servers in Dataverse environments. | +| [develop-mcp list-environments](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop-mcp#develop-mcp-list-environments) | List all Dataverse environments available for MCP server management. | +| [develop-mcp list-servers](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop-mcp#develop-mcp-list-servers) | List MCP servers in a specific Dataverse environment. | +| [develop-mcp publish](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop-mcp#develop-mcp-publish) | Publish an MCP server to a Dataverse environment. | +| [develop-mcp unpublish](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop-mcp#develop-mcp-unpublish) | Unpublish an MCP server from a Dataverse environment. | +| [develop-mcp approve](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop-mcp#develop-mcp-approve) | Approve an MCP server. | +| [develop-mcp block](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop-mcp#develop-mcp-block) | Block an MCP server. | +| [develop-mcp package-mcp-server](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/develop-mcp#develop-mcp-package-mcp-server) | Generate MCP server package for submission on Microsoft admin center. | +| [publish](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/publish) | Update manifest.json ID values and publish the package. Configure federated identity and app role assignments. | +| [query-entra](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/query-entra) | Query Microsoft Entra ID for agent information including scopes, permissions, and consent status. | +| [query-entra blueprint-scopes](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/query-entra#query-entra-blueprint-scopes) | List configured scopes and consent status for the agent blueprint. | +| [query-entra instance-scopes](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/query-entra#query-entra-instance-scopes) | List configured scopes and consent status for the agent instance. | +| [setup](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/setup) | Set up your Agent 365 environment with granular control over each step. | +| [setup requirements](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/setup#setup-requirements) | Validate prerequisites for Agent 365 setup. | +| [setup infrastructure](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/setup#setup-infrastructure) | Create Azure infrastructure. | +| [setup blueprint](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/setup#setup-blueprint) | Create agent blueprint (Entra ID application registration). | +| [setup permissions](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/setup#setup-permissions) | Configure OAuth2 permission grants and inheritable permissions. | +| [setup permissions mcp](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/setup#setup-permissions-mcp) | Configure MCP server OAuth2 grants and inheritable permissions. | +| [setup permissions bot](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/setup#setup-permissions-bot) | Configure Messaging Bot API OAuth2 grants and inheritable permissions. | +| [setup permissions copilotstudio](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/setup#setup-permissions-copilotstudio) | Configures OAuth2 permission grants and inheritable permissions for the agent blueprint to invoke Copilot Studio copilots via the Power Platform API. | +| [setup permissions custom](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/setup#setup-permissions-custom) | Applies custom API permissions to your agent blueprint that go beyond the standard permissions required for agent operation. | +| [setup all](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/setup#setup-all) | Perform all setup steps to set up your Agent 365 environment | + +## Documentation policy + +As new Agent CLI commands are developed you may find documentation about these commands in this folder. These temporary artifacts support the workflow for developers creating features. After the feature ships, docs must be created or updated on learn.microsoft.com and the documentation in this folder should be deleted. + +The only documentation that will persist in this folder is to support developers creating and maintaining the code for commands in this repo, for example [Agent365-devTools Architecture](../design.md) \ No newline at end of file diff --git a/docs/commands/config-init.md b/docs/commands/config-init.md deleted file mode 100644 index 35e7e847..00000000 --- a/docs/commands/config-init.md +++ /dev/null @@ -1,680 +0,0 @@ -# Agent 365 CLI - Configuration Initialization Guide - -> **Command**: `a365 config init` -> **Purpose**: Interactive wizard to configure Agent 365 with Azure CLI integration and smart defaults - -## Overview - -The `a365 config init` command provides an intelligent, interactive configuration wizard that minimizes manual input by leveraging Azure CLI integration and smart defaults. The wizard automatically detects your Azure subscription, suggests resource names, and validates your inputs to ensure a smooth setup experience. - -## Quick Start - -```bash -# Initialize configuration with interactive wizard -a365 config init - -# Import existing config file -a365 config init --configfile path/to/existing/a365.config.json - -# Create config in global directory (AppData) -a365 config init --global -``` - -## Key Features - -- **Azure CLI Integration**: Automatically detects your Azure subscription, tenant, and available resources -- **Smart Defaults**: Generates sensible defaults for resource names, agent identities, and UPNs -- **Resource Discovery**: Lists existing resource groups, app service plans, and locations -- **Platform Detection**: Automatically detects project type (.NET, Node.js, Python) -- **Input Validation**: Validates paths, UPNs, emails, and Azure resources -- **Interactive Prompts**: Press Enter to accept defaults or type to customize - -## Configuration Flow - -### Step 1: Azure CLI Verification - -The wizard first verifies your Azure CLI authentication: - -``` -Checking Azure CLI authentication... -Subscription ID: e09e22f2-9193-4f54-a335-01f59575eefd (My Subscription) -Tenant ID: adfa4542-3e1e-46f5-9c70-3df0b15b3f6c - -NOTE: Defaulted from current Azure account. To use a different Azure subscription, -run 'az login' and then 'az account set --subscription ' before -running this command. -``` - -**If not logged in:** -``` -ERROR: You are not logged in to Azure CLI. -Please run 'az login' and then try again. -``` - -### Step 2: Agent Name - -Provide a unique name for your agent. This is used to generate derived names for resources: - -``` -Agent name [agent1114]: myagent -``` - -**Smart Defaults**: If no existing config, defaults to `agent` + current date (e.g., `agent1114`) - -### Step 3: Client App ID - -Provide the Application (client) ID of your custom Entra ID app registration: - -``` -================================================================= -IMPORTANT: Custom Client App Required -================================================================= -The Agent365 CLI requires a custom client app registration in your -Entra ID tenant with specific Microsoft Graph API permissions. - -Required Delegated Permissions: - See AuthenticationConstants.RequiredClientAppPermissions in the codebase - for the complete list of required permissions. - -If you haven't created this app yet, see: - https://learn.microsoft.com/en-us/microsoft-agent-365/developer/agent-365-cli - -================================================================= - -Client App ID (Application ID from Entra ID): a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6 - -Validating client app... -✓ Client app found in tenant -✓ Required permissions configured -✓ Admin consent granted -``` - -**Validation**: The CLI performs comprehensive validation: -- ✅ GUID format check -- ✅ App exists in your tenant -- ✅ All required permissions are configured (see AuthenticationConstants.RequiredClientAppPermissions) -- ✅ Admin consent has been granted - -**If Validation Fails**: You'll see specific error messages and have up to 3 attempts: -``` -✗ Validation failed: - - Missing permission: Application.ReadWrite.All - - Admin consent not granted for: DelegatedPermissionGrant.ReadWrite.All - -Common issues: - • Not all required permissions have been added to the app - • Admin consent has not been granted (click "Grant admin consent" in Azure Portal) - • Using the wrong GUID (use Application ID, not Object ID) - -See troubleshooting guide: - https://learn.microsoft.com/en-us/microsoft-agent-365/developer/agent-365-cli - -Retry (2 attempts remaining)? (Y/n): -``` - -**Prerequisites**: Before running config init, create your custom client app: -1. Follow the guide: [Custom Client App Registration](https://learn.microsoft.com/microsoft-agent-365/developer/custom-client-app-registration) -2. Copy the **Application (client) ID** from Azure Portal -3. Ensure admin consent is granted for all permissions -4. Enter the ID when prompted during config init - -**Security Note**: This app stays within your tenant's security boundaries and you control which permissions are granted. - -### Step 4: Deployment Project Path - -Specify the path to your agent project: - -``` -Deployment project path [C:\A365-Ignite-Demo\sample_agent]: -Detected DotNet project -``` - -**Features**: -- Defaults to current directory or existing config path -- Validates directory exists -- Detects project platform (.NET, Node.js, Python) -- Warns if no supported project type detected - -### Step 5: Resource Group Selection - -Choose from existing resource groups or create a new one: - -``` -Available resource groups: - 1. a365demorg - 2. another-rg - 3. - -Select resource group (1-3) [1]: 1 -``` - -**Smart Behavior**: -- Lists existing resource groups from your subscription -- Option to create new resource group -- Defaults to existing config value if available - -### Step 6: App Service Plan Selection - -Choose from existing app service plans in the selected resource group: - -``` -Available app service plans in resource group 'a365demorg': - 1. a365agent-app-plan - 2. - -Select app service plan (1-2) [1]: 1 -``` - -**Smart Behavior**: -- Only shows plans in the selected resource group -- Option to create new plan -- Defaults to existing config value - -### Step 7: Manager Email - -Provide the email address of the agent's manager: - -``` -Manager email [agent365demo.manager1@a365preview001.onmicrosoft.com]: -``` - -**Validation**: Ensures valid email format - -### Step 8: Azure Location - -Choose the Azure region for deployment: - -``` -Azure location [westus]: -``` - -**Smart Defaults**: Uses location from existing config or Azure account - -### Step 9: Custom Blueprint Permissions (Optional) - -Optionally configure custom resource permissions for your agent: - -``` -=== Optional: Custom Blueprint Permissions === -If your agent needs access to additional external resources -(e.g. Teams presence, OneDrive files, custom APIs) beyond -standard permissions, you can configure them here. -Most agents do not require this. - -Configure custom blueprint permissions? (y/N): y - -Resource App ID (GUID) - press Enter when done: 00000003-0000-0000-c000-000000000000 -Scopes (comma-separated, e.g. Presence.ReadWrite,Files.Read.All): Presence.ReadWrite,Files.Read.All -Permission added. - -Resource App ID (GUID) - press Enter when done: -``` - -Press **Enter** with no input to finish and proceed. - -> **Tip**: You can also add or update permissions after initial setup using `a365 config permissions`. - -### Step 10: Configuration Summary - -Review all settings before saving: - -``` -================================================================= - Configuration Summary -================================================================= -Agent Name : myagent -Client App ID : a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6 -Web App Name : myagent-webapp-11140916 -Agent Identity Name : myagent Identity -Agent Blueprint Name : myagent Blueprint -Agent UPN : agent.myagent.11140916@yourdomain.onmicrosoft.com -Agent Display Name : myagent Agent User -Manager Email : agent365demo.manager1@a365preview001.onmicrosoft.com -Deployment Path : C:\A365-Ignite-Demo\sample_agent -Resource Group : a365demorg -App Service Plan : a365agent-app-plan -Location : westus -Subscription : My Subscription (e09e22f2-9193-4f54-a335-01f59575eefd) -Tenant : adfa4542-3e1e-46f5-9c70-3df0b15b3f6c -Custom Permissions : 1 configured - -Do you want to customize any derived names? (y/N): -``` - -### Step 11: Name Customization (Optional) - -Optionally customize generated names: - -``` -Do you want to customize any derived names? (y/N): y - -Web App Name [myagent-webapp-11140916]: myagent-prod -Agent Identity Display Name [myagent Identity]: -Agent Blueprint Display Name [myagent Blueprint]: -Agent User Principal Name [agent.myagent.11140916@yourdomain.onmicrosoft.com]: -Agent User Display Name [myagent Agent User]: -``` - -### Step 12: Confirmation - -Final confirmation to save: - -``` -Save this configuration? (Y/n): Y - -Configuration saved to: C:\Users\user\a365.config.json - -You can now run: - a365 setup all - Create Azure resources - a365 deploy - Deploy your agent -``` - -## Configuration Fields - -The wizard automatically populates these fields: - -### Authentication (Required for Microsoft Graph API) - -| Field | Description | Source | Example | -|-------|-------------|--------|---------| -| **clientAppId** | Custom Entra ID app registration Application (client) ID | User provides after creating app | `a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6` | - -**Important**: This must be configured before setup. See [Custom Client App Registration Guide](https://learn.microsoft.com/microsoft-agent-365/developer/custom-client-app-registration) for detailed setup instructions. - -### Azure Infrastructure (Auto-detected from Azure CLI) - -| Field | Description | Source | Example | -|-------|-------------|--------|---------| -| **tenantId** | Azure AD Tenant ID | Azure CLI (`az account show`) | `adfa4542-3e1e-46f5-9c70-3df0b15b3f6c` | -| **subscriptionId** | Azure Subscription ID | Azure CLI (`az account show`) | `e09e22f2-9193-4f54-a335-01f59575eefd` | -| **resourceGroup** | Azure Resource Group name | User selection from list | `a365demorg` | -| **location** | Azure region | Azure account or user input | `westus` | -| **appServicePlanName** | App Service Plan name | User selection from list | `a365agent-app-plan` | -| **appServicePlanSku** | Service Plan SKU | Default value | `B1` | - -### Agent Identity (Auto-generated with customization option) - -| Field | Description | Generation Logic | Example | -|-------|-------------|------------------|---------| -| **webAppName** | Web App name (globally unique) | `{agentName}-webapp-{timestamp}` | `myagent-webapp-11140916` | -| **agentIdentityDisplayName** | Agent identity in Azure AD | `{agentName} Identity` | `myagent Identity` | -| **agentBlueprintDisplayName** | Agent blueprint name | `{agentName} Blueprint` | `myagent Blueprint` | -| **agentUserPrincipalName** | UPN for the agentic user | `agent.{agentName}.{timestamp}@domain` | `agent.myagent.11140916@yourdomain.onmicrosoft.com` | -| **agentUserDisplayName** | Display name for agentic user | `{agentName} Agent User` | `myagent Agent User` | -| **agentDescription** | Description of your agent | `{agentName} - Agent 365 Demo Agent` | `myagent - Agent 365 Demo Agent` | - -### User-Provided Fields - -| Field | Description | Validation | Example | -|-------|-------------|------------|---------| -| **managerEmail** | Email of the agent's manager | Email format | `manager@contoso.com` | -| **deploymentProjectPath** | Path to agent project directory | Directory exists, platform detection | `C:\projects\my-agent` | -| **agentUserUsageLocation** | Country code for license | Auto-detected from Azure account | `US` | - -## Command Options - -```bash -# Display help -a365 config init --help - -# Import existing configuration file -a365 config init --configfile path/to/config.json -a365 config init -c path/to/config.json - -# Create config in global directory (AppData) -a365 config init --global -a365 config init -g -``` - -## Generated Configuration File - -After completing the wizard, `a365.config.json` is created: - -```json -{ - "tenantId": "adfa4542-3e1e-46f5-9c70-3df0b15b3f6c", - "clientAppId": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6", - "subscriptionId": "e09e22f2-9193-4f54-a335-01f59575eefd", - "resourceGroup": "a365demorg", - "location": "westus", - "environment": "prod", - "appServicePlanName": "a365agent-app-plan", - "appServicePlanSku": "B1", - "webAppName": "myagent-webapp-11140916", - "agentIdentityDisplayName": "myagent Identity", - "agentBlueprintDisplayName": "myagent Blueprint", - "agentUserPrincipalName": "agent.myagent.11140916@yourdomain.onmicrosoft.com", - "agentUserDisplayName": "myagent Agent User", - "managerEmail": "manager@contoso.com", - "agentUserUsageLocation": "US", - "deploymentProjectPath": "C:\\projects\\my-agent", - "agentDescription": "myagent - Agent 365 Demo Agent" -} -``` - -## Smart Default Generation - -The wizard uses intelligent algorithms to generate defaults: - -### Agent Name Derivation - -**Input**: `myagent` - -**Generated Names**: -``` -webAppName = myagent-webapp-11140916 -agentIdentityDisplayName = myagent Identity -agentBlueprintDisplayName = myagent Blueprint -agentUserPrincipalName = agent.myagent.11140916@yourdomain.onmicrosoft.com -agentUserDisplayName = myagent Agent User -agentDescription = myagent - Agent 365 Demo Agent -``` - -**Timestamp**: `MMddHHmm` format (e.g., `11140916` = Nov 14, 09:16 AM) - -### Usage Location Detection - -Automatically determined from Azure account home tenant location: -- US-based tenants → `US` -- UK-based tenants → `GB` -- Canada-based tenants → `CA` -- Falls back to `US` if unable to detect - -## Validation Rules - -### Deployment Project Path - -- **Existence**: Directory must exist on the file system -- **Platform Detection**: Warns if no supported project type (.NET, Node.js, Python) is detected -- **Confirmation**: User can choose to continue even without detected platform - -``` -WARNING: Could not detect a supported project type (.NET, Node.js, or Python) -in the specified directory. -Continue anyway? (y/N): -``` - -### Resource Group - -- **Existence**: Must select from existing resource groups or create new -- **Format**: Azure naming conventions (lowercase, alphanumeric, hyphens) - -### App Service Plan - -- **Scope**: Must exist in the selected resource group -- **Fallback**: Option to create new plan if none exist - -### Manager Email - -- **Format**: Valid email address (contains `@` and domain) - -- **Format**: Valid email address (contains `@` and domain) - -## Azure CLI Integration - -The wizard leverages Azure CLI for automatic resource discovery: - -### Prerequisites - -```bash -# Install Azure CLI (if not already installed) -# Windows: https://learn.microsoft.com/cli/azure/install-azure-cli-windows -# macOS: brew install azure-cli -# Linux: curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash - -# Login to Azure -az login - -# Set active subscription (if you have multiple) -az account set --subscription "My Subscription" - -# Verify current account -az account show -``` - -### What the Wizard Fetches - -1. **Current Azure Account**: - - Subscription ID and Name - - Tenant ID - - User information - - Home tenant location (for usage location) - -2. **Resource Groups**: - - Lists all resource groups in your subscription - - Allows selection or creation of new group - -3. **App Service Plans**: - - Lists plans in the selected resource group - - Filters by location compatibility - - Shows SKU and pricing tier - -4. **Azure Locations**: - - Lists available Azure regions - - Suggests location based on account or existing config - -### Error Handling - -**Not logged in**: -``` -ERROR: You are not logged in to Azure CLI. -Please run 'az login' and then try again. -``` - -**Solution**: Run `az login` and complete browser authentication - -**Multiple subscriptions**: -``` -Subscription ID: e09e22f2-9193-4f54-a335-01f59575eefd (Subscription 1) - -NOTE: To use a different Azure subscription, run 'az login' and then -'az account set --subscription ' before running this command. -``` - -**Solution**: Set desired subscription with `az account set` - -## Updating Existing Configuration - -Re-run the wizard to update your configuration: - -```bash -# Wizard will load existing values as defaults -a365 config init - -# Or import from a different file -a365 config init --configfile production.config.json -``` - -**Workflow**: -1. Wizard detects existing `a365.config.json` -2. Displays message: "Found existing configuration. Default values will be used where available." -3. Each prompt shows current value in brackets: `[current-value]` -4. Press **Enter** to keep current value -5. Type new value to update - -**Example**: -``` -Agent name [myagent]: myagent-v2 -Deployment project path [C:\projects\my-agent]: ← Press Enter to keep -Resource group [a365demorg]: new-rg ← Type to update -``` - -### Setup Command - -```bash -# Initialize config first -a365 config init - -# Then run setup to create Azure resources and agent blueprint -a365 setup all -``` - -The `setup` command uses: -- **Azure Infrastructure fields**: To create App Service, Plan, and Resource Group -- **Agent Identity fields**: To create agent blueprint and agentic user -- **deploymentProjectPath**: To detect project platform (DotNet, Node.js, Python) - -### Create Instance Command - -```bash -# Create agent instance after setup -a365 create-instance identity -``` - -Uses: -- **agentUserPrincipalName**: To create the agentic user in Azure AD -- **agentUserDisplayName**: Display name shown in Microsoft 365 -- **managerEmail**: To assign a manager to the agent user -- **agentUserUsageLocation**: For license assignment - -### Deploy Command - -```bash -# Deploy your agent to Azure -a365 deploy app -``` - -Uses: -- **deploymentProjectPath**: Source code location -- **webAppName**: Deployment target -- **resourceGroup**: Azure resource location - -## Updating Existing Configuration - -You can edit `a365.config.json` manually or re-run `a365 config init`: - -```bash -# Load existing config and update specific fields -a365 config init --config a365.config.json -``` - -The CLI will: -1. Load current values from the file -2. Show them as defaults in prompts -3. Press **Enter** to keep existing values -4. Or type new values to update - -## Best Practices - -### 1. Use Descriptive Names - -```json -{ - "agentIdentityDisplayName": "Support Agent - Production", - "agentUserPrincipalName": "support.agent.prod@contoso.onmicrosoft.com", - "agentUserDisplayName": "Support Agent (Prod)" -} -``` - -### 2. Follow Naming Conventions - -- **Resource names**: Use lowercase with hyphens (`my-agent-rg`) -- **Display names**: Use Title Case (`My Agent Identity`) -- **UPNs**: Use descriptive prefixes (`support.agent`, `demo.agent`) - -### 3. Organize by Environment - -``` -configs/ - ??? a365.config.dev.json - ??? a365.config.staging.json - ??? a365.config.prod.json -``` - -```bash -# Use environment-specific configs -a365 setup all --config configs/a365.config.prod.json -``` - -### 4. Secure Sensitive Data - -**? Safe to commit** (public information): -- `a365.config.json` (static configuration) - -**? Never commit** (sensitive secrets): -- `a365.generated.config.json` (contains secrets like client secrets) -- Add to `.gitignore`: - -```gitignore -# Agent 365 generated configs with secrets -a365.generated.config.json -``` - -## Troubleshooting - -### Issue: "Directory does not exist" - -**Symptom**: Path validation fails during config init - -**Solution**: -```bash -# Create the directory first -mkdir my-agent -cd my-agent - -# Then run config init -a365 config init -``` - -### Issue: "Invalid UPN format" - -**Symptom**: Agent User Principal Name validation fails - -**Solution**: Ensure format is `username@domain`: -``` -? Correct: demo.agent@contoso.onmicrosoft.com -? Incorrect: demo.agent (missing domain) -``` - -### Issue: "Web App name already exists" - -**Symptom**: Setup fails because web app name is taken - -**Solution**: Web app names must be globally unique in Azure: -```json -{ - "webAppName": "my-agent-webapp-prod-12345" -} -``` - -## Command Options - -```bash -# Display help -a365 config init --help - -# Specify custom config file path -a365 config init --config path/to/config.json - -# Specify custom output path (generated config) -a365 config init --output path/to/generated.json -``` - -## Next Steps - -After running `a365 config init`: - -1. **Review the generated config**: - ```bash - # View static configuration - a365 config display - ``` - -2. **Run setup** to create Azure resources: - ```bash - a365 setup all - ``` - -3. **Deploy your agent**: - ```bash - a365 deploy - ``` - -## Additional Resources - -- **Command Reference**: [a365 config display](config-display.md) -- **Setup Guide**: [a365 setup](setup.md) -- **Deployment Guide**: [a365 deploy](deploy.md) -- **GitHub Issues**: [Agent 365 Repository](https://github.com/microsoft/Agent365-devTools/issues) -- **Documentation**: [Microsoft Learn](https://learn.microsoft.com/agent365) - diff --git a/docs/commands/deploy.md b/docs/commands/deploy.md deleted file mode 100644 index 062464a0..00000000 --- a/docs/commands/deploy.md +++ /dev/null @@ -1,193 +0,0 @@ -# Microsoft Agent 365 CLI – Deploy Command Guide - -> **Command**: `a365 deploy` -> **Purpose**: Deploy your application to Azure App Service **and** update Microsoft Agent 365 Tool (MCP) permissions in one run. Subcommands let you run either phase independently. ---- - -## TL;DR - -```bash -# Full two-phase deploy (App binaries, then MCP permissions) -a365 deploy - -# App-only deploy -a365 deploy app - -# MCP-only permissions update -a365 deploy mcp - -# Common flags -a365 deploy app --restart # reuse existing publish/ (skip build) -a365 deploy app --inspect # pause to review publish/ and zip -a365 deploy --dry-run # print actions, no changes -a365 deploy --verbose # detailed logs -``` - ---- - -## What the command actually does - -### Default (`a365 deploy`) -Runs **two phases sequentially**: - -**Step 1 — App Binaries** -1. Load `a365.config.json` (+ dynamic state from generated config). -2. **Azure preflight** - - Validates Azure CLI auth + subscription context (`ValidateAllAsync`). - - Ensures target Web App exists via `az webapp show`. -3. Build/package via `DeploymentService.DeployAsync(...)` (supports `--inspect` and `--restart`). -4. Log success/failure. - -**Step 2 — MCP Permissions** -1. Re-load config (same path). -2. Read required scopes from `deploymentProjectPath/toolingManifest.json`. -3. Apply **in order**: - - **OAuth2 grant**: `ReplaceOauth2PermissionGrantAsync` - - **Inheritable permissions**: `SetInheritablePermissionsAsync` - - **Admin consent (agent identity)**: `ReplaceOauth2PermissionGrantAsync` -4. Log success/failure. - ---- - -## Subcommands & Flags - -### `a365 deploy` (default, two-phase) -- **Options**: `--config|-c`, `--verbose|-v`, `--dry-run`, `--inspect`, `--restart` -- **Behavior**: Runs **App** then **MCP**, prints “Part 1…” and “Part 2…” sections (even on `--dry-run`). - -### `a365 deploy app` (app-only) -- **Options**: `--config|-c`, `--verbose|-v`, `--dry-run`, `--inspect`, `--restart` -- **Behavior**: Only runs the App phase (includes the same Azure validations and Web App existence check). - -### `a365 deploy mcp` (MCP-only) -- **Options**: `--config|-c`, `--verbose|-v`, `--dry-run` -- **Behavior**: Only runs the MCP permissions sequence (no `--inspect` or `--restart` here). - ---- - -## Preflight Checks - -- **Azure auth & subscription**: Validated via `ValidateAllAsync(subscriptionId)`. - If invalid, deployment is stopped with a clear error. -- **Web App existence**: `az webapp show --resource-group --name --subscription ` must succeed before app deploy proceeds. - ---- - -## Configuration Inputs - -- **`a365.config.json`** (user-maintained) and **`a365.generated.config.json`** (dynamic state) -- **Tooling scopes**: Read from `/toolingManifest.json` during the MCP phase -- `--config` defaults to `a365.config.json` in the current directory - -> The CLI also keeps **global** copies of config/state in: -> - Windows: `%LocalAppData%\Microsoft.Agents.A365.DevTools.Cli` -> - Linux/macOS: `$HOME/.config/Microsoft.Agents.A365.DevTools.Cli` ---- - -## Flags (behavior details) - -- `--restart` - Skip a fresh build and start from compressing the **existing** `publish/` folder. If `publish/` is missing, the deploy fails with guidance to run a full deploy. - -- `--inspect` - Pause before upload so you can inspect `publish/` and the generated ZIP. (App phase only.) - -- `--dry-run` - Print everything that would happen. The default command shows **two sections**: - - *Part 1 — Deploy application binaries* (target RG/app, config path) - - *Part 2 — Deploy/update Agent 365 Tool permissions* (the three MCP steps) - No changes are made. - -- `--verbose` - Enables detailed logging in both phases. - ---- - -## MCP Permission Update Flow (exact order) - -When running `a365 deploy` or `a365 deploy mcp`: - -1. **OAuth2 permission grant** - `ReplaceOauth2PermissionGrantAsync(tenant, blueprintSp, mcpPlatformSp, scopes)` - -2. **Inheritable permissions** - `SetInheritablePermissionsAsync(tenant, agentBlueprintAppId, mcpResourceAppId, scopes)` - -3. **Admin consent** (agent identity → MCP platform) - `ReplaceOauth2PermissionGrantAsync(tenant, agenticAppSpObjectId, mcpPlatformResourceSpObjectId, scopes)` - -> All scopes are sourced from `toolingManifest.json` in your project root. ---- - -## Typical Flows - -### Full two-phase deploy with visibility -```bash -a365 deploy --verbose -``` - -### Quick iteration (reuse last build) -```bash -a365 deploy app --restart -``` - -### MCP only (permissions/scopes refresh) -```bash -a365 deploy mcp --verbose -``` - -### Validate everything without changing anything -```bash -a365 deploy app --dry-run --inspect -``` - ---- - -## Troubleshooting - -- **“Not logged into Azure” or wrong subscription** - Fix with `az login --tenant ` and `az account set --subscription `. - -- **Web App not found** - Ensure `a365 setup` has been run or correct `webAppName`/`resourceGroup` are in `a365.config.json`. - -- **Permissions update fails** - - Confirm `AgentBlueprintId`, `AgenticAppId`, and environment are set in config. - - Ensure your account has rights to manage service principals and grants. - - Verify `toolingManifest.json` exists and contains valid scopes. - -- **`--restart` fails** - Run a full build once (no `--restart`) to produce `publish/`. - ---- - -## Logs - -**CLI logs** -- Windows: `%LocalAppData%\Microsoft.Agents.A365.DevTools.Cli\logs\` -- Linux/macOS: `~/.config/a365/logs/` - -Tail latest deploy logs: -```powershell -# Windows -Get-Content $env:LOCALAPPDATA\Microsoft.Agents.A365.DevTools.Cli\logs\a365.deploy.log -Tail 80 -``` - -```bash -# Linux/Mac -tail -80 ~/.config/a365/logs/a365.deploy.log -``` - -**App Service logs** -Use Log Stream in the Azure Portal for runtime stdout/stderr. - ---- - -## Related - -- [`a365 setup`](./setup.md) — provision resources and register the messaging endpoint -- [`a365 create-instance`](./create-instance.md) — create agent identity/user and licenses -- [`a365 config init`](./config-init.md) — initialize configuration - ---- - diff --git a/docs/commands/develop/develop-addpermissions.md b/docs/commands/develop/develop-addpermissions.md deleted file mode 100644 index dc88df32..00000000 --- a/docs/commands/develop/develop-addpermissions.md +++ /dev/null @@ -1,109 +0,0 @@ -# a365 develop add-permissions Command - -## Overview - -The `a365 develop add-permissions` command adds MCP (Model Context Protocol) server API permissions to Azure AD applications. This command is designed for **development scenarios** where you need to configure custom applications (not agent blueprints) to access MCP servers. - -## Usage - -```bash -a365 develop add-permissions [options] -``` - -## Options - -| Option | Alias | Description | Default | -|--------|-------|-------------|---------| -| `--config` | `-c` | Configuration file path | `a365.config.json` | -| `--manifest` | `-m` | Path to ToolingManifest.json | `/ToolingManifest.json` | -| `--app-id` | | Application (client) ID to add permissions to | `clientAppId` from config | -| `--scopes` | | Specific scopes to add (space-separated) | All scopes from ToolingManifest.json | -| `--verbose` | `-v` | Show detailed output | `false` | -| `--dry-run` | | Show what would be done without making changes | `false` | - -## When to Use This Command - -### Development Scenarios -- Custom backend services needing MCP access -- Testing applications with specific MCP permissions -- Third-party integrations calling MCP servers - -### NOT for Agent Blueprints -- Use `a365 setup permissions mcp` for agent blueprint setup - -## Understanding the Application ID - -This command adds permissions to a **single application**, which you can specify in two ways: - -1. **Using config file** (default): `clientAppId` from `a365.config.json` -2. **Using command line**: `--app-id` parameter (overrides config) - -The application you're adding permissions to can be the **same application** you use for authentication (your custom client app). This is the typical scenario: -- Your custom client app authenticates to Microsoft Graph API -- The same app needs MCP permissions added to it -- You can reuse the same `clientAppId` for both purposes - -**Example**: If your `a365.config.json` has `clientAppId: "12345678-..."`, running `a365 develop add-permissions` will add MCP permissions to that same application. - -> **Note**: The `clientAppId` must be a **client application you create in your Entra ID tenant** with `Application.ReadWrite.All` permission. See the [custom client app registration guide](https://learn.microsoft.com/microsoft-agent-365/developer/custom-client-app-registration) for setup instructions. - -## Prerequisites - -1. **Azure CLI Authentication**: `az login` with appropriate permissions -2. **Client Application**: - - Must exist in Azure AD - - Must have `Application.ReadWrite.All` permission (to modify app registrations) - - Can be configured in `a365.config.json` as `clientAppId` OR provided via `--app-id` - -## ToolingManifest.json Structure - -```json -{ - "mcpServers": [ - { - "mcpServerName": "mcp_MailTools", - "url": "https://agent365.svc.cloud.microsoft/agents/servers/mcp_MailTools", - "scope": "McpServers.Mail.All", - "audience": "api://mcp-mailtools" - }, - { - "mcpServerName": "mcp_CalendarTools", - "url": "https://agent365.svc.cloud.microsoft/agents/servers/mcp_CalendarTools", - "scope": "McpServers.Calendar.All", - "audience": "api://mcp-calendartools" - } - ] -} -``` - -## Examples - -### Add all scopes from manifest to the app in config -```bash -# Uses clientAppId from a365.config.json as the target application -a365 develop add-permissions -``` - -### Add permissions to a different application -```bash -# Override the config and add permissions to a different app -a365 develop add-permissions --app-id 87654321-4321-4321-4321-210987654321 -``` - -### Add specific scopes only -```bash -# Add only specific scopes to the app from config -a365 develop add-permissions --scopes McpServers.Mail.All McpServers.Calendar.All -``` - -### Combine options with dry-run -```bash -# Preview changes to a specific app with specific scopes -a365 develop add-permissions --app-id 12345678-1234-1234-1234-123456789abc --scopes McpServers.Mail.All --dry-run -``` - -### Without config file -```bash -# When no config exists, you must provide --app-id -a365 develop add-permissions --app-id 12345678-1234-1234-1234-123456789abc --scopes McpServers.Mail.All -``` \ No newline at end of file diff --git a/docs/commands/develop/develop-gettoken.md b/docs/commands/develop/develop-gettoken.md deleted file mode 100644 index a0378f5e..00000000 --- a/docs/commands/develop/develop-gettoken.md +++ /dev/null @@ -1,157 +0,0 @@ -# a365 develop get-token Command - -## Overview - -The `a365 develop get-token` command retrieves bearer tokens for testing MCP servers during development. This command acquires tokens with explicit scopes using interactive browser authentication. - -> **Note**: For production agent deployments, authentication is handled automatically through inheritable permissions configured during `a365 setup permissions mcp`. This command is for development testing and debugging. - -## Usage - -```bash -a365 develop get-token [options] -``` - -## Options - -| Option | Alias | Description | Default | -|--------|-------|-------------|---------| -| `--config` | `-c` | Configuration file path | `a365.config.json` | -| `--app-id` | | Application (client) ID for authentication | `clientAppId` from config | -| `--manifest` | `-m` | Path to ToolingManifest.json | `/ToolingManifest.json` | -| `--scopes` | | Specific scopes to request (space-separated) | Read from ToolingManifest.json | -| `--output` | `-o` | Output format: table, json, or raw | `table` | -| `--verbose` | `-v` | Show detailed output including full token | `false` | -| `--force-refresh` | | Force token refresh bypassing cache | `false` | -| `--resource` | | Resource keyword to get token for (mcp, powerplatform) | `mcp` | -| `--resource-id` | | Resource application ID (GUID) for custom resources | None | - -### Resource Options - -The `--resource` and `--resource-id` options allow you to acquire tokens for different Azure resources: - -- **`--resource`**: Use a keyword to select a predefined resource - - `mcp` (default): Agent 365 Tools for MCP servers - - `powerplatform`: Power Platform API - -- **`--resource-id`**: Specify a custom resource application ID (GUID) for resources not covered by keywords - -> **Note**: `--resource` and `--resource-id` are mutually exclusive. Use one or the other, not both. - -> **Important**: When using `--resource` or `--resource-id`, the `--scopes` option is **required**. Manifest-based scope resolution is only supported for the default MCP flow. - -## When to Use This Command - -### Development & Testing -- Local development and debugging -- Manual API testing with Postman/curl -- Integration testing before deployment - -### NOT for Production -- Production agents use inheritable permissions (`a365 setup permissions mcp`) - -## Understanding the Application ID - -This command retrieves tokens for a **single application**, which you can specify in two ways: - -1. **Using config file** (default): `clientAppId` from `a365.config.json` -2. **Using command line**: `--app-id` parameter (overrides config) - -The application you're getting a token for should be your **custom client app** that has the required MCP permissions. This is typically the same application you use across development commands. - -**Example**: If your `a365.config.json` has `clientAppId: "12345678-..."`, running `a365 develop get-token` will retrieve a token for that application. - -> **Note**: For more details about the client application setup and how it's used across development commands, see the [develop add-permissions documentation](./develop-addpermissions.md#understanding-the-application-id). - -## Prerequisites - -1. **Azure CLI**: Run `az login` before using this command -2. **Client Application**: - - Must exist in Azure AD - - Must have the required MCP scopes configured - - Can be configured in `a365.config.json` as `clientAppId` OR provided via `--app-id` -3. **ToolingManifest.json** (optional): Can be bypassed with `--scopes` parameter - -## ToolingManifest.json Structure - -```json -{ - "mcpServers": [ - { - "mcpServerName": "mcp_MailTools", - "scope": "McpServers.Mail.All" - }, - { - "mcpServerName": "mcp_CalendarTools", - "scope": "McpServers.Calendar.All" - } - ] -} -``` - -## Examples - -### Get token with all scopes from manifest -```bash -a365 develop get-token -``` - -### Get token with specific scopes -```bash -a365 develop get-token --scopes McpServers.Mail.All McpServers.Calendar.All -``` - -### Get token with custom client app -```bash -a365 develop get-token --app-id 98765432-4321-4321-4321-210987654321 -``` - -### Export token to file -```bash -a365 develop get-token --output raw > token.txt -``` - -### Use token in curl request -```bash -TOKEN=$(a365 develop get-token --output raw) -curl -H "Authorization: Bearer $TOKEN" https://agent365.svc.cloud.microsoft/agents/discoverToolServers -``` - -### Get token for Power Platform API -```bash -a365 develop get-token --resource powerplatform --scopes .default -``` - -### Get token for a custom resource -```bash -a365 develop get-token --resource-id 12345678-1234-1234-1234-123456789abc --scopes .default -``` - -## Authentication Flow - -1. **Resource Selection**: Uses `--resource-id`, `--resource` keyword, or defaults to Agent 365 Tools (MCP) -2. **Application Selection**: Uses `--app-id` or `clientAppId` from config -3. **Scope Resolution**: Uses `--scopes` or reads from `ToolingManifest.json` (manifest only for default MCP flow) -4. **Token Acquisition**: Opens browser for interactive OAuth2 authentication -5. **Token Caching**: Cached in local storage for reuse (until expiration or `--force-refresh`) - -## Token Storage for Development - -When `a365.config.json` exists in your project, the command automatically attempts to save the bearer token to your project's configuration files for convenient local testing: - -### .NET Projects -- **Target File**: `Properties/launchSettings.json` -- **Behavior**: Updates `BEARER_TOKEN` only in profiles that already have it defined. Shows which profiles were updated. -- **Setup**: Add `"BEARER_TOKEN": ""` to your profile's `environmentVariables` before running the command. - -### Python/Node.js Projects -- **Target File**: `.env` in project root -- **Behavior**: Updates `BEARER_TOKEN=` if the file exists. Shows guidance if file is missing. -- **Setup**: Create a `.env` file with `BEARER_TOKEN=` before running the command. - -### Without Config File -When running `a365 develop get-token` with `--app-id` (no config file), the token is **not** automatically saved to any project files. You must manually copy and paste it into: -- **.NET projects**: `Properties/launchSettings.json` > `profiles` > `environmentVariables` > `BEARER_TOKEN` -- **Python/Node.js projects**: `.env` file as `BEARER_TOKEN=` - -> **Note**: This token storage is for **development convenience only**. Production agents use inheritable permissions configured through `a365 setup permissions mcp`. \ No newline at end of file diff --git a/docs/commands/setup-permissions-custom.md b/docs/commands/setup-permissions-custom.md deleted file mode 100644 index 45b3b327..00000000 --- a/docs/commands/setup-permissions-custom.md +++ /dev/null @@ -1,531 +0,0 @@ -# Agent 365 CLI - Custom Blueprint Permissions Guide - -> **Command**: `a365 setup permissions custom` -> **Purpose**: Configure custom resource OAuth2 grants and inheritable permissions for your agent blueprint - -## Overview - -The `a365 setup permissions custom` command applies custom API permissions to your agent blueprint that go beyond the standard permissions required for agent operation. This allows your agent to access additional Microsoft Graph scopes (like Presence, Files, Chat) or custom APIs that your organization has developed. - -## Quick Start - -```bash -# Step 1: Configure custom permissions in config -a365 config permissions \ - --resource-app-id 00000003-0000-0000-c000-000000000000 \ - --scopes Presence.ReadWrite,Files.Read.All - -# Step 2: Apply permissions to blueprint -a365 setup permissions custom - -# Or run as part of full setup -a365 setup all -``` - -## Key Features - -- **Generic Resource Support**: Works with Microsoft Graph, custom APIs, and first-party Microsoft services -- **OAuth2 Grants**: Automatically configures delegated permission grants with admin consent -- **Inheritable Permissions**: Enables agent users to inherit permissions from the blueprint -- **Portal Visibility**: Permissions appear in Azure Portal under API permissions -- **Reconciling**: Removes permissions from Azure AD when they are removed from config -- **Idempotent**: Safe to run multiple times - skips already-configured permissions -- **Dry Run Support**: Preview changes before applying with `--dry-run` - -## Prerequisites - -1. **Blueprint Created**: Run `a365 setup blueprint` first to create the agent blueprint -2. **Custom Permissions Configured**: Add custom permissions to `a365.config.json` using `a365 config permissions` -3. **Global Administrator**: You must have Global Administrator role to grant admin consent - -## Configuration - -### Step 1: Add Custom Permissions to Config - -Use the `a365 config permissions` command to add custom permissions: - -```bash -# Add Microsoft Graph extended permissions -a365 config permissions \ - --resource-app-id 00000003-0000-0000-c000-000000000000 \ - --scopes Presence.ReadWrite,Files.Read.All,Chat.Read - -# Add custom API permissions -a365 config permissions \ - --resource-app-id abcd1234-5678-90ab-cdef-1234567890ab \ - --scopes CustomScope.Read,CustomScope.Write -``` - -**Expected Output**: -``` -Permission added successfully. -Configuration saved to: C:\Users\user\a365.config.json - -Next step: Run 'a365 setup permissions custom' to apply these permissions to your blueprint. -``` - -> **Note**: The resource name is not prompted for during configuration. It will be automatically resolved from Azure during the `a365 setup permissions custom` step. - -### Step 2: Verify Configuration - -Check your `a365.config.json` file: - -```json -{ - "tenantId": "...", - "clientAppId": "...", - "customBlueprintPermissions": [ - { - "resourceAppId": "00000003-0000-0000-c000-000000000000", - "resourceName": null, - "scopes": [ - "Presence.ReadWrite", - "Files.Read.All", - "Chat.Read" - ] - }, - { - "resourceAppId": "abcd1234-5678-90ab-cdef-1234567890ab", - "resourceName": null, - "scopes": [ - "CustomScope.Read", - "CustomScope.Write" - ] - } - ] -} -``` - -> **Note**: The `resourceName` field is optional and can be left as `null`. The display name is auto-resolved from Azure during `a365 setup permissions custom` for logging purposes only — the resolved name is not written back to any config file. - -## Usage - -### Apply Custom Permissions - -```bash -# Apply all configured custom permissions -a365 setup permissions custom - -# Preview what would be configured (dry run) -a365 setup permissions custom --dry-run - -# Specify custom config file -a365 setup permissions custom --config path/to/a365.config.json -``` - -### Example Output - -``` -Configuring custom blueprint permissions... - -Configuring Microsoft Graph Extended (00000003-0000-0000-c000-000000000000)... - - Configuring OAuth2 permission grants... - - Setting inheritable permissions... - - Microsoft Graph Extended configured successfully - -Configuring Contoso Custom API (abcd1234-5678-90ab-cdef-1234567890ab)... - - Configuring OAuth2 permission grants... - - Setting inheritable permissions... - - Contoso Custom API configured successfully - -Custom blueprint permissions configured successfully -``` - -### Dry Run Output - -```bash -$ a365 setup permissions custom --dry-run - -DRY RUN: Configure Custom Blueprint Permissions -Would configure the following custom permissions: - - Microsoft Graph Extended (00000003-0000-0000-c000-000000000000) - Scopes: Presence.ReadWrite, Files.Read.All, Chat.Read - - Contoso Custom API (abcd1234-5678-90ab-cdef-1234567890ab) - Scopes: CustomScope.Read, CustomScope.Write -``` - -## Integration with Setup All - -Custom permissions are automatically configured when you run `a365 setup all`: - -```bash -# Full setup including custom permissions -a365 setup all -``` - -**Setup Flow**: -1. Infrastructure (Resource Group, App Service Plan, Web App) -2. Agent Blueprint -3. MCP Tools Permissions -4. Bot API Permissions -5. **Custom Blueprint Permissions** (if configured) -6. Messaging Endpoint - -## Common Use Cases - -### Use Case 1: Extended Microsoft Graph Permissions - -**Scenario**: Your agent needs access to user presence and files in OneDrive. - -**Solution**: -```bash -# Configure Microsoft Graph extended permissions -a365 config permissions \ - --resource-app-id 00000003-0000-0000-c000-000000000000 \ - --scopes Presence.ReadWrite,Files.Read.All -``` - -**Scopes**: -- `Presence.ReadWrite`: Read and update user presence information -- `Files.Read.All`: Read files in all site collections - -### Use Case 2: Teams Chat Integration - -**Scenario**: Your agent needs to read and send Teams chat messages. - -**Solution**: -```bash -# Configure Teams Chat permissions -a365 config permissions \ - --resource-app-id 00000003-0000-0000-c000-000000000000 \ - --scopes Chat.Read,Chat.ReadWrite,ChatMessage.Send -``` - -**Scopes**: -- `Chat.Read`: Read user's chat messages -- `Chat.ReadWrite`: Read and write user's chat messages -- `ChatMessage.Send`: Send chat messages as the user - -### Use Case 3: Custom API Access - -**Scenario**: Your organization has a custom API that agents need to access. - -**Solution**: -```bash -# Configure custom API permissions -a365 config permissions \ - --resource-app-id YOUR-CUSTOM-API-APP-ID \ - --scopes api://your-api/Read,api://your-api/Write -``` - -**Prerequisites**: -- Your custom API must be registered in Entra ID -- The API must expose delegated permissions -- You need the Application (client) ID of the API - -### Use Case 4: Multiple Custom Resources - -**Scenario**: Your agent needs permissions to multiple resources. - -**Solution**: -```bash -# Add first resource -a365 config permissions \ - --resource-app-id 00000003-0000-0000-c000-000000000000 \ - --scopes Presence.ReadWrite,Files.Read.All - -# Add second resource (run command again) -a365 config permissions \ - --resource-app-id YOUR-CUSTOM-API-APP-ID \ - --scopes CustomScope.Read - -# Apply all permissions -a365 setup permissions custom -``` - -## Managing Custom Permissions - -### View Current Permissions - -```bash -# View all configured custom permissions -a365 config permissions -``` - -**Output**: -``` -Current custom blueprint permissions: - 1. Microsoft Graph Extended (00000003-0000-0000-c000-000000000000) - Scopes: Presence.ReadWrite, Files.Read.All - 2. Contoso Custom API (abcd1234-5678-90ab-cdef-1234567890ab) - Scopes: CustomScope.Read, CustomScope.Write -``` - -### Update Existing Permission - -```bash -# Update scopes for an existing resource -a365 config permissions \ - --resource-app-id 00000003-0000-0000-c000-000000000000 \ - --scopes Presence.ReadWrite,Files.Read.All,Chat.Read -``` - -**Confirmation Prompt**: -``` -Resource 00000003-0000-0000-c000-000000000000 already exists with scopes: - Presence.ReadWrite, Files.Read.All - -Do you want to overwrite with new scopes? (y/N): y - -Permission updated successfully. -Configuration saved to: C:\Users\user\a365.config.json -``` - -### Remove Custom Permissions - -To fully remove a custom permission — from both config and Azure AD — run the two-step process: - -```bash -# Step 1: Remove from config (one specific resource, or all) -a365 config permissions --reset - -# Step 2: Reconcile Azure AD with the updated config -a365 setup permissions custom -# OR equivalently: -a365 setup blueprint -``` - -`config permissions --reset` only updates `a365.config.json`. The second command detects the removed entries and cleans them up from Azure AD (both inheritable permissions and the OAuth2 grant). - -**Step 1 output** (`config permissions --reset`): -``` -Clearing all custom blueprint permissions... - -Configuration saved to: C:\Users\user\a365.config.json -``` - -**Step 2 output** (`setup permissions custom`): -``` -Configuring custom blueprint permissions... - -Removing 1 stale custom permission(s) no longer in config... - Removing stale permission for 00000003-0000-0ff1-ce00-000000000000... - - Inheritable permissions removed for 00000003-0000-0ff1-ce00-000000000000 - - OAuth2 grant revoked for 00000003-0000-0ff1-ce00-000000000000 -No custom blueprint permissions configured. -``` - -## Validation - -The CLI validates custom permissions at multiple stages: - -### Config Validation - -When adding permissions via `a365 config permissions` (or the `a365 config init` wizard): -- ✅ **GUID Format**: Resource App ID must be a valid GUID -- ✅ **Required Fields**: Resource App ID (GUID) and scopes are required; resource name is optional and will be auto-resolved during setup if not provided -- ✅ **Scopes**: At least one scope must be specified -- ✅ **Duplicates**: No duplicate scopes within a permission -- ✅ **Unique Resources**: No duplicate resource App IDs - -### Setup Validation - -When applying permissions via `a365 setup permissions custom`: -- ✅ **Blueprint Exists**: Verifies agent blueprint ID exists -- ✅ **Permission Format**: Re-validates each permission -- ✅ **API Existence**: Checks if resource API exists in tenant (best effort) -- ✅ **Scope Availability**: Validates scopes are exposed by the API - -## Error Handling - -### Error: Blueprint Not Found - -``` -ERROR: Blueprint ID not found. Run 'a365 setup blueprint' first. -``` - -**Solution**: Create the agent blueprint before configuring permissions: -```bash -a365 setup blueprint -``` - -### Error: Invalid Resource App ID - -``` -ERROR: Invalid resourceAppId 'not-a-guid'. Must be a valid GUID format. -``` - -**Solution**: Use a valid GUID format (e.g., `00000003-0000-0000-c000-000000000000`) - -### Error: Invalid Permission Configuration - -``` -ERROR: Invalid custom permission configuration: resourceAppId must be a valid GUID, At least one scope is required -``` - -**Solution**: Ensure all required fields are properly configured in `a365.config.json` - -## Idempotency and Reconciliation - -The `a365 setup permissions custom` command is **reconciling**: it syncs Azure AD to match the current config — adding what is configured and removing what is not. - -- ✅ Safe to run multiple times -- ✅ Skips already-configured permissions (no-op if nothing changed) -- ✅ Applies new or updated permissions -- ✅ Removes permissions that were deleted from config -- ✅ Standard permissions (MCP, Bot API, Graph) are never removed - -**Rerun with no changes**: -``` -Configuring custom blueprint permissions... - -Configuring Microsoft Graph Extended (00000003-0000-0000-c000-000000000000)... - - Inheritable permissions already configured for Microsoft Graph Extended - - Microsoft Graph Extended configured successfully -Custom blueprint permissions configured successfully -``` - -**After removing a permission from config**: -``` -Configuring custom blueprint permissions... - -Removing 1 stale custom permission(s) no longer in config... - Removing stale permission for 00000003-0000-0ff1-ce00-000000000000... - - Inheritable permissions removed for 00000003-0000-0ff1-ce00-000000000000 - - OAuth2 grant revoked for 00000003-0000-0ff1-ce00-000000000000 -No custom blueprint permissions configured. -``` - -## Troubleshooting - -### Issue: Permission not appearing in Azure Portal - -**Symptom**: Custom permission is not visible in the blueprint's API permissions - -**Solution**: -1. Wait a few minutes for Azure AD replication -2. Refresh the Azure Portal page -3. Navigate to: Azure Portal → Entra ID → Applications → [Your Blueprint] → API permissions - -### Issue: "Insufficient privileges" error - -**Symptom**: Permission setup fails with insufficient privileges - -**Solution**: You need Global Administrator role to grant admin consent: -```bash -# Check your current role -az ad signed-in-user show --query '[displayName, userPrincipalName, id]' - -# Contact your Global Administrator to run the command -``` - -### Issue: Custom API not found - -**Symptom**: Setup fails because custom API doesn't exist - -**Solution**: -1. Verify the API is registered in your Entra ID tenant -2. Check the Application (client) ID is correct -3. Ensure the API exposes the requested scopes - -### Issue: Scope not available - -**Symptom**: Requested scope doesn't exist on the resource API - -**Solution**: -1. Verify the scope name is correct (case-sensitive) -2. Check the API's exposed permissions in Azure Portal -3. Update the scope name to match exactly - -## Command Options - -```bash -# Display help -a365 setup permissions custom --help - -# Specify custom config file -a365 setup permissions custom --config path/to/a365.config.json -a365 setup permissions custom -c path/to/a365.config.json - -# Preview changes without applying -a365 setup permissions custom --dry-run - -# Show detailed output -a365 setup permissions custom --verbose -a365 setup permissions custom -v -``` - -## Azure Portal Verification - -After running `a365 setup permissions custom`, verify in Azure Portal: - -1. Navigate to **Azure Portal** → **Entra ID** → **Applications** -2. Find your agent blueprint application -3. Click **API permissions** -4. You should see your custom permissions listed under **Configured permissions** -5. Verify **Status** column shows "Granted for [Your Tenant]" - -## Best Practices - -### 1. Use Least Privilege Principle - -Only request the minimum scopes your agent needs: -```json -{ - "scopes": ["Files.Read.All"] // ✅ Good: Only read access -} -``` - -Avoid overly broad permissions: -```json -{ - "scopes": ["Files.ReadWrite.All", "Sites.FullControl.All"] // ❌ Too broad -} -``` - -### 2. Document Your Custom Permissions - -Add comments to your config explaining why each permission is needed: -```json -{ - "customBlueprintPermissions": [ - { - "resourceName": "Microsoft Graph Extended", - "resourceAppId": "00000003-0000-0000-c000-000000000000", - "scopes": [ - "Presence.ReadWrite", // Required for status updates - "Files.Read.All" // Required for document retrieval - ] - } - ] -} -``` - -### 3. Test with Dry Run First - -Always preview changes before applying: -```bash -# Preview first -a365 setup permissions custom --dry-run - -# Then apply -a365 setup permissions custom -``` - -### 4. Version Control Your Config - -Keep `a365.config.json` in version control: -```gitignore -# Safe to commit (no secrets) -a365.config.json - -# Never commit (contains secrets) -a365.generated.config.json -``` - -## Next Steps - -After configuring custom permissions: - -1. **Test the agent**: Verify it can access the custom resources -2. **Monitor usage**: Check Azure Portal for API call patterns -3. **Update as needed**: Add or remove scopes using `a365 config permissions` -4. **Deploy updates**: Run `a365 setup permissions custom` to apply changes - -## Additional Resources - -- **Configuration Guide**: [a365 config init](config-init.md) -- **Setup Guide**: [a365 setup](setup.md) -- **Microsoft Graph Permissions**: [Graph Permissions Reference](https://learn.microsoft.com/graph/permissions-reference) -- **GitHub Issues**: [Agent 365 Repository](https://github.com/microsoft/Agent365-devTools/issues) -- **Issue #194**: [Original feature request](https://github.com/microsoft/Agent365-devTools/issues/194) diff --git a/docs/commands/setup/setup-permissions-copilotstudio.md b/docs/commands/setup/setup-permissions-copilotstudio.md deleted file mode 100644 index e9e99ade..00000000 --- a/docs/commands/setup/setup-permissions-copilotstudio.md +++ /dev/null @@ -1,109 +0,0 @@ -# a365 setup permissions copilotstudio Command - -## Overview - -The `a365 setup permissions copilotstudio` command configures OAuth2 permission grants and inheritable permissions for the agent blueprint to invoke Copilot Studio copilots via the Power Platform API. - -## Usage - -```bash -a365 setup permissions copilotstudio [options] -``` - -## Options - -| Option | Alias | Description | Default | -|--------|-------|-------------|---------| -| `--config` | `-c` | Configuration file path | `a365.config.json` | -| `--verbose` | `-v` | Show detailed output | `false` | -| `--dry-run` | | Show what would be done without making changes | `false` | - -## Prerequisites - -1. **Blueprint Created**: Run `a365 setup blueprint` first -2. **Global Administrator**: Required for admin consent operations -3. **Azure CLI Authentication**: `az login` with appropriate permissions - -## What This Command Does - -1. **Ensures Power Platform API Service Principal** exists in your tenant -2. **Creates OAuth2 Permission Grant** from blueprint to Power Platform API -3. **Sets Inheritable Permissions** so agent instances can invoke Copilot Studio - -## Permission Configured - -| Resource | Scope | Type | -|----------|-------|------| -| Power Platform API (`8578e004-a5c6-46e7-913e-12f58912df43`) | `CopilotStudio.Copilots.Invoke` | Delegated | - -## Examples - -### Configure CopilotStudio permissions -```bash -a365 setup permissions copilotstudio -``` - -### Preview changes without executing -```bash -a365 setup permissions copilotstudio --dry-run -``` - -### Use custom configuration file -```bash -a365 setup permissions copilotstudio --config my-agent.config.json -``` - -### Show detailed output -```bash -a365 setup permissions copilotstudio --verbose -``` - -## When to Use This Command - -Use this command when your agent needs to: -- Invoke Copilot Studio copilots at runtime -- Call Power Platform APIs that require CopilotStudio permissions - -## Related Commands - -- `a365 setup blueprint` - Create the agent blueprint (prerequisite) -- `a365 setup permissions mcp` - Configure MCP server permissions -- `a365 setup permissions bot` - Configure Messaging Bot API permissions - -## Common Issues - -### "Blueprint ID not found" Error -``` -ERROR: Blueprint ID not found. Run 'a365 setup blueprint' first. -``` -**Solution**: Run `a365 setup blueprint` to create the agent blueprint first. - -### Permission Grant Failures -If the command fails during permission grant creation, verify: -- You have Global Administrator permissions -- You're authenticated with `az login` -- The Power Platform API service principal exists in your tenant - -## Output Examples - -### Successful Execution -``` -Configuring CopilotStudio permissions... - -✓ Power Platform API service principal found -✓ OAuth2 permission grant created: CopilotStudio.Copilots.Invoke -✓ Inheritable permissions configured - -CopilotStudio permissions configured successfully - -Your agent blueprint can now invoke Copilot Studio copilots. -``` - -### Dry Run Output -``` -DRY RUN: Configure CopilotStudio Permissions -Would configure Power Platform API permissions: - - Blueprint: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - - Resource: Power Platform API (8578e004-a5c6-46e7-913e-12f58912df43) - - Scopes: CopilotStudio.Copilots.Invoke -``` \ No newline at end of file diff --git a/docs/design.md b/docs/design.md index 153b78c1..f5f81c86 100644 --- a/docs/design.md +++ b/docs/design.md @@ -231,7 +231,7 @@ a365 setup all **Documentation**: - Design: [design-custom-resource-permissions.md](./design-custom-resource-permissions.md) -- Command Reference: [setup-permissions-custom.md](./commands/setup-permissions-custom.md) +- Command Reference: [a365 setup permissions custom](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/setup#setup-permissions-custom) - GitHub Issue: [#194](https://github.com/microsoft/Agent365-devTools/issues/194) --- @@ -247,6 +247,6 @@ a365 setup all ## Related Documentation -- [CLI Usage Guide](../Readme-Usage.md) - End-user documentation -- [Command Documentation](./commands/) - Individual command reference +- [CLI Usage Guide](https://learn.microsoft.com/microsoft-agent-365/developer/reference/cli/) - End-user documentation +- [Command Documentation](./commands/) - Index of CLI commands and links to Microsoft Learn reference - [Code Standards](../.github/copilot-instructions.md) - Coding conventions and review rules