Custom knowledge

  • 3 minutes

Declarative agents use custom knowledge to provide extra data and context to Microsoft 365 Copilot that is scoped to a specific scenario or task.

Custom knowledge consists of two parts:

  • Custom instructions: determines how the agent should behave and how it should shape its responses.
  • Custom grounding: determines the data sources to be used as grounding data.

Custom instructions

Instructions are specific directives or guidelines that are passed to the foundation model to shape its responses.

For our fictional customer support team, we want to create a helpful support assistant to help the team respond to customer queries.

Instructions are crucial to ensure that your declarative agent performs reliably and accurately. You should implement effective prompt engineering practices to write good instructions. Consider the answer to the following questions when writing your instructions:

  • Capabilities: What can it do and what can’t it do?
  • Tone and persona: How should the agent respond to queries?
  • Information sources: What sources of information should the agent use?
  • Fallback: What should the agent do if it can’t find the necessary information?

Effective instructions provide clarity and specificity to guide the agent to ensure that it responds with relevant and accurate answers.

The instructions that you give to your agent must be under 8,000 characters in length.

Custom grounding

Grounding is the process of connecting large language models (LLM) to real-world information, enabling more accurate and relevant responses. Grounding data is used to provide context and support to the LLM when generating responses. It reduces the need for the LLM to rely solely on its training data and improves the quality of the responses.

By default, a declarative agent isn't connected to any data sources. Data sources are defined in the declarative agent manifest using the capabilities property.

Use the following capabilities to add extra data and context:

  • WebSearch: Use Bing.com web search results.
  • GraphConnectors: Use data ingested into Microsoft 365 by using a Copilot connector.
  • OneDriveAndSharePoint: Use documents stored in OneDrive, or SharePoint Online sites.
  • Dataverse: Use data stored in Dataverse.
  • TeamsMessages: Use messages from Microsoft Teams channels, chats, and meetings.
  • People: Use data about people in Microsoft 365.

With the exception of WebSearch which uses a public datasource, access to grounding data is controlled by Microsoft 365 permissions. The agent can only access data that the user has permission to access.

The following code snippet shows how to configure Bing.com web search results as grounding data. Up to four public websites can be configured to scope the returned results. Omit the sites property to allow an unscoped search through all public websites.

"capabilities": [
    {
        "name": "WebSearch",
        "sites": [
            {
                "url": "microsoft.com"
            }
        ]
    }
]

Copilot connectors

The following code snippet shows how to configure data ingested into Microsoft 365 by using a Copilot connector as grounding data. You configure a connection by including the connection ID of the data source that contains the ingested items. You can configure one or more connections. Omit the connections property to allow an unscoped search through all data sources that are ingested into Microsoft 365 by using a Copilot connector.

"capabilities": [
    {
        "name": "GraphConnectors",
        "connections": [
            {
                "connection_id": "mydatasource"
            }
        ]
    }
]

OneDrive and SharePoint

The following code snippet shows how to configure documents held in OneDrive or SharePoint site as grounding data. You can configure a specific document, document library, web, or site collection as sources of grounding data using an absolute URL, or an identifier. You can configure one or more locations. Omit the items_by_url or items_by_sharepoint_ids property to allow an unscoped search through documents in OneDrive or SharePoint.

Tip

Obtain the unique identifiers for SharePoint objects by using the Microsoft Graph API.

"capabilities": [
    {
        "name": "OneDriveAndSharePoint",
        "items_by_url": [
            {
                "url": "https://tenant.sharepoint.com/sites/site/shared%20documents/mydocument.docx"
            },
            {
                "url": "https://tenant.sharepoint.com/sites/site/shared%20documents"
            },    
            {
                "url": "https://tenant.sharepoint.com/sites/site/web"
            },
            {
                "url": "https://tenant.sharepoint.com/sites/site"
            }
        ],
        "items_by_sharepoint_ids": [
            {
                "unique_id": "00000000-0000-0000-0000-000000000000"
            },
            {
                "list_id": "00000000-0000-0000-0000-000000000000"
            },
            {
                "web_id": "00000000-0000-0000-0000-000000000000"
            },
            {
                "site_id": "00000000-0000-0000-0000-000000000000"
            }
        ]
    }
]

Dataverse

The following code snippet shows how to configure data stored in Dataverse as grounding data. You can configure one or more tables.

"capabilities": [
    {
        "name": "Dataverse",
        "knowledge_sources": [ 
            { 
                "host_name": "organization.crm.dynamics.com", 
                "skill": "DVCopilotSkillName",
                "tables": [ 
                    { 
                        "table_name": "account" 
                    }, 
                    { 
                        "table_name": "opportunity" 
                    } 
                ]     
            } 
        ]
    }
]

Teams messages

The following code snippet shows how to configure messages from Microsoft Teams channel as grounding data. You can configure one or more urls. Omit the urls property allows an unscoped search through all of channels, teams, meetings, 1:1 chats, and group chats.

"capabilities": [
    {
        "name": "TeamsMessages",
        "urls": [
            {
              "url": "https://teams.microsoft.com/l/channel/{channelId}/{parentMessageId}?groupId={groupId}&tenantId={tenantId}"
            }
        ]
    }
]

People

The following code snippet shows how to configure information about people in Microsoft 365 as grounding data.

"capabilities": [
    {
        "name": "People"
    }
]

Additional capabilities

There are additional capabilities that you can configure in the declarative agent manifest which aren't used for grounding data, but can be used to enhance the agent's responses.

  • CodeInterpreter - Indicates that the declarative agent can generate and execute Python code to solve complex math problems, analyze data, generate visualizations, and more.
  • GraphicArt - Indicates that the declarative agent can create images and art based on the text input from the user.

Code interpreter

The following code snippet shows how to configure the code interpreter capability. The code interpreter is used to run Python code.

"capabilities": [
    {
        "name": "CodeInterpreter"
    }
]

Graphic art

The following code snippet shows how to configure the graphic art capability. The graphic art capability is used to generate images.

"capabilities": [
    {
        "name": "GraphicArt"
    }
]