Microsoft Copilot Studio

https://learn.microsoft.com/en-us/microsoft-copilot-studio
Admin
Microsoft Copilot Studio is a platform for easily building AI-driven conversational agents...
Tokens:983,357
Snippets:7,422
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Manifest file example structure

Source: https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-certification

JSON manifest file defining the MCP server, including developer info, names, descriptions, agent connectors with remote MCP server configuration, icons, and accent color. Placeholders like <APP_ID> and <MCP_SERVER_URL> must be replaced. Note: Microsoft only supports ASCII header names and values.

```json
{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.30/MicrosoftTeams.schema.json",
  "version": "1.30",
  "id": "<APP_ID>",
  "developer": {
    "name": "<COMPANY_NAME>",
    "websiteUrl": "<COMPANY_WEBSITE_URL>",
    "privacyUrl": "<PRIVACY_POLICY_URL>",
    "termsOfUseUrl": "<TERMS_OF_USE_URL>"
    "contactInfo": {
      "defaultSupport": {
        "userEmailsForChatSupport": [
          "ISV_EmailAddress1",
          "ISV_EmailAddress2"
        ],
        "emailsForEmailSupport": [  
          "<SUPPORT_Email_Address>"
        ]
      }
    }  
  },
  "name": {
    "short": "<MCP_SHORT_NAME>",
    "full": "<MCP_FULL_NAME>"
  },
  "description": {
    "short": "<SHORT_DESCRIPTION>",
    "full": "<LONG_DESCRIPTION>"
  },
  "agentConnectors": [
    {
      "id": "<CONNECTOR_ID>",
      "displayName": "<CONNECTOR_DISPLAY_NAME>",
      "description": "<CONNECTOR_DESCRIPTION>",
      "toolSource": {
        "remoteMcpServer": {
          "mcpServerUrl": "<MCP_SERVER_URL>",
          "mcpToolDescription": {
            "file": "mcptools.json"
          },
          "authorization": {
            "type": "AzureKeyVault",
            "referenceId": "<KEYVAULT_URI>"
          }
        }
      }
    }
  ],
  "icons": {
    "outline": "Outline.png",
    "color": "Color.png"
  },
  "accentColor": "<HEX_COLOR>"
}

```

--------------------------------

### YAML comment example for complex logic

Source: https://learn.microsoft.com/en-us/microsoft-copilot-studio/visual-studio-code-extension-edit-agent-components

Use comments in YAML to explain complex logic, such as checking business hours and eligibility. Comments start with # and are placed above the relevant node.

```yaml
nodes:
  # Check if user is within business hours and eligible for live support
  # Business hours: 9 AM - 5 PM EST, Monday-Friday
  # Eligibility: Premium tier customers only
  - id: check-live-support-availability
    type: condition

```

--------------------------------

### mcp_CalendarTools_graph_getSchedule

Source: https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-calendar-tools

Gets the free/busy schedule for a user, distribution list, or resource. Requires schedules, start time, and end time, and optionally accepts a user ID and availability view interval.

```APIDOC
## mcp_CalendarTools_graph_getSchedule

### Description
Get the free/busy schedule for a user, distribution list, or resource.

### Parameters
#### Required Parameters
- **schedules** (array) - SMTP addresses of users or resources
- **startTime** (object) - Start time with `dateTime` and `timeZone`
- **endTime** (object) - End time with `dateTime` and `timeZone`

#### Optional Parameters
- **userId** (string) - User ID or `userPrincipalName`
- **availabilityViewInterval** (integer) - Time slot length in minutes

```

--------------------------------

### Knowledge source URL with variable

Source: https://learn.microsoft.com/en-us/microsoft-copilot-studio/knowledge-add-public-website

Example URL using a variable to scope knowledge to a specific product area.

```text
https://www.microsoft.com/en-us/{GlobalProductURL}
```

--------------------------------

### Sample instructions template (JSON)

Source: https://learn.microsoft.com/en-us/microsoft-copilot-studio/voice-realtime-customize

Structured JSON template for voice agent instructions. Replace placeholders in the 'variables' section (e.g., COMPANY_NAME, AGENT_ROLE) with your own values. Defines persona, objective, absolute rules, and instruction categories including tone, real-time responsiveness, compliance, and fallback/escalation.

```json
{
  "_comment": "TEMPLATE VARIABLES: Replace placeholders in the 'variables' section.",
  "variables": {
    "COMPANY_NAME": "Contoso",
    "AGENT_ROLE": "customer support agent",
    "OBJECTIVE": "the primary goal of the agent (e.g., to assist customers with inquiries and issues in a friendly and efficient manner)",
    "VERIFICATION_FIELD_1_NAME": "Customer ID",
    "VERIFICATION_FIELD_2_NAME": "ZIP Code",
    "VERIFICATION_ITEM": "account details"
  },
  "role": "system",
  "behavior": {
    "persona": "You are an agent representing {{COMPANY_NAME}}, acting as a {{AGENT_ROLE}}. You assist customers with their needs related to {{COMPANY_NAME}}'s services. You have access to tools to help customers, and you maintain a friendly, professional demeanor.",
    "objective": "{{OBJECTIVE}}",
    "absolute_rules": {
      "priority": "HIGH",
      "description": "These rules override all other instructions and must be followed strictly.",
      "do": [
        "Start the conversation with a warm greeting that includes the company name and state your role.",
        "Before ending the conversation, ensure the customer's query or issue is fully resolved and they have no further questions."
      ],
      "do_not": [
        "Do NOT provide information or make promises that are not explicitly supported by provided data or authorized tools.",
        "Do NOT request highly sensitive personal information (such as passwords, full credit card numbers, or social security numbers).",
        "Do NOT engage in topics unrelated to the customer's issues or {{COMPANY_NAME}}'s services.",
        "Do NOT misrepresent yourself. Do not claim to be human or to have feelings.",
        "Do NOT violate any company policies or legal requirements."
      ]
    },
    "instructions": {
      "general": [
        "Allow the customer to communicate first. Listen/read carefully, then respond appropriately.",
        "Handle one request or issue at a time.",
        "Clearly communicate any actions you are taking on behalf of the customer.",
        "After resolving an issue, verify with the customer if they need further assistance."
      ],
      "tone_and_personality": [
        "Maintain a polite, friendly, and patient tone.",
        "Use the customer's name (if provided) to personalize the interaction.",
        "Keep language simple and jargon-free.",
        "Show empathy and understanding."
      ],
      "real_time_responsiveness": [
        "Respond promptly once the customer has finished their message.",
        "If you need additional time to process, give a brief acknowledgment.",
        "If the customer's request isn't clear, politely ask follow-up questions."
      ],
      "compliance": [
        "Request personal information only when necessary. Explain why you need it.",
        "Adhere to all of {{COMPANY_NAME}}'s privacy policies and data protection laws.",
        "Maintain professionalism and impartiality."
      ],
      "fallback_and_escalation": [
        "If you cannot resolve the issue, apologize and offer to connect with a human representative.",
        "If the customer requests a human agent, immediately acknowledge and initiate transfer.",
        "When ending a conversation, confirm concerns have been addressed and express appreciation."
      ]
    }
  }
}
```

--------------------------------

### GET /copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets

Source: https://learn.microsoft.com/en-us/microsoft-copilot-studio/analytics-agent-evaluation-rest-api

Retrieves an array of test set IDs and details for a specific agent. Use the returned test set ID to start an evaluation.

```APIDOC
## GET /copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets

### Description
Retrieves an array of test set IDs and other details for a specific agent.

### Method
GET

### Endpoint
`https://api.powerplatform.com/copilotstudio/environments/{EnvironmentId}/bots/{BotId}/api/makerevaluation/testsets?api-version=2024-10-01`

### Parameters
#### Path Parameters
- **EnvironmentId** (string) - Required - The environment ID of the target agent.
- **BotId** (string) - Required - The bot ID of the target agent.

#### Query Parameters
- **api-version** (string) - Required - The API version to use. Must be `2024-10-01`.

### Response
#### Success Response (200)
Returns a list called `value` of test sets with the following information:
- **auditInfo** (object) - Timestamps and user IDs for creating and modifying each test set.
- **displayName** (string) - The name of the test set.
- **id** (string) - The ID of the test set. Use in Start an agent evaluation to choose which test set to use.
- **description** (string) - The description of the test set.
- **state** (string) - The status of the test set. A usable test set has the status `Active`.
- **totalTestCases** (integer) - The number of test cases within the test set.

#### Response Example
```json
{
  "value": [
    {
      "auditInfo": {},
      "displayName": "string",
      "id": "string",
      "description": "string",
      "state": "Active",
      "totalTestCases": 0
    }
  ]
}
```
```

--------------------------------

### Authenticate with Power Platform CLI

Source: https://learn.microsoft.com/en-us/microsoft-copilot-studio/administer-computer-use

Run this command to connect to your tenant before disabling computer use. Follow the prompts to complete authentication.

```cli
pac auth create
```
Tokens:
Raw