Grounding Declarative Agents with Copilot Connectors

Your organization runs on more than Microsoft 365: HRIS platforms, internal wikis, CRMs, ticketing systems. Structured data scattered across systems that no SharePoint document can cover. Copilot connectors (formerly known as Microsoft Graph connectors) bring all of that into your declarative agent’s reach. For the Zava Insurance HR Onboarding Buddy, this means grounding the agent in real, structured data from external systems.

What Are Copilot Connectors?

Copilot connectors bring structured data from external systems into Microsoft 365 by indexing it into Microsoft Search, making it searchable, governable, and available to declarative agents.

• SharePoint gives your agent access to documents and policies
• Teams gives your agent access to conversations and tribal knowledge
• Copilot connectors give your agent access to everything else: databases, HRIS platforms, wikis, CRMs, ticketing systems, and any structured data source you can think of

The data doesn’t need to migrate into Microsoft 365. The connector indexes it in place and makes it available through the Microsoft Graph: your agent queries it the same way it queries SharePoint content.

Adding the GraphConnectors Capability

In declarativeAgent.json, the capabilities array defines what knowledge sources the agent uses. Adding a Copilot connector means referencing the connection ID of an already-configured connector. Note that the capability name in the manifest is still GraphConnectors (the original API name):

{
  "name": "GraphConnectors",
  "connections": [
    {
      "connection_id": "zavaInsuranceHrKnowledgeBase"
    }
  ]
}

One capability block, one connection ID. Here’s how it fits into the full declarativeAgent.json:

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.6/schema.json",
  "version": "v1.6",
  "name": "HR Onboarding Buddy",
  "description": "A friendly assistant to help new employees at Zava Insurance.",
  "instructions": "$[file('instructions.txt')]",
  "capabilities": [
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        {
          "url": "https://zavainsurance.sharepoint.com/sites/HR/Shared Documents/Onboarding"
        }
      ]
    },
    {
      "name": "GraphConnectors",
      "connections": [
        {
          "connection_id": "zavaInsuranceHrKnowledgeBase"
        }
      ]
    }
  ]
}

The agent now has access to both the HR document library and the indexed HRIS data. Copilot routes queries to the right source automatically: no routing logic required.

Connection IDs and Permissions

Every Copilot connector instance gets a unique connection ID when it’s set up by your Microsoft 365 admin. In our case, zavaInsuranceHrKnowledgeBase is the ID assigned when Zava Insurance’s IT team configured the HRIS connector. You reference that ID in your manifest, and the platform handles the rest.

Copilot connectors also respect access control. When indexing data from an external system, the connector maps the source system’s permissions to Microsoft 365 identities. If an employee shouldn’t see salary data in the HRIS, the agent won’t surface it. The same security boundaries you enforce in the source system carry over into the agent’s responses.

The Zava Insurance HR Knowledge Base Schema

To understand how KQL filtering works, it helps to see the schema behind the connector. Here’s what the zavaInsuranceHrKnowledgeBase connection indexes from the Zava Insurance HRIS:

Property	Type	Searchable	Queryable	Refinable	Labels
title	String	✔️			title
content	String	✔️
category	String		✔️	✔️
department	String		✔️	✔️
location	String		✔️	✔️
lastUpdated	DateTime		✔️		lastModifiedDateTime
author	String	✔️			createdBy
url	String				url

The category property holds values like benefits, onboarding, it-setup, policies, and payroll. The department property holds values like engineering, hr, sales, and finance. Both are marked as queryable and refinable, which means we can target them with KQL filters in our agent manifest.

Filtering with KQL: Scoping What the Agent Can See

The basic connection_id reference gives the agent access to everything in the connection. For a focused agent like the HR Buddy, you might want to narrow that scope. The additional_search_terms property accepts a KQL (Keyword Query Language) query that filters items based on the connection’s schema properties.

Here’s the HR Buddy scoped to only onboarding and benefits content:

{
  "name": "GraphConnectors",
  "connections": [
    {
      "connection_id": "zavaInsuranceHrKnowledgeBase",
      "additional_search_terms": "category:onboarding OR category:benefits"
    }
  ]
}

Now the agent only sees items where category is onboarding or benefits. Payroll data, engineering-specific policies, and everything else in the knowledge base stays out of scope, even if the user has permission to see it.

You can combine multiple property filters for even tighter scoping:

{
  "connection_id": "zavaInsuranceHrKnowledgeBase",
  "additional_search_terms": "category:onboarding AND department:engineering"
}

This gives the agent access only to onboarding content relevant to the engineering department. Perfect for a team-specific onboarding buddy.

Beyond KQL, the connection object also supports filtering by items_by_path, items_by_container_name, and items_by_external_id for scenarios where you need to target specific items or folder-like structures. See the declarative agent manifest reference for the full list of filtering options.

Use Cases: Where Copilot Connectors Shine

HRIS and People Data

This is our Zava Insurance scenario. The HRIS holds employee profiles, department structures, office locations, and org charts: structured data in a database, not SharePoint documents.

Without the connector, asking “Who’s the head of the Engineering department?” means searching SharePoint for an org chart PDF. With it, the agent queries indexed HRIS data directly:

Internal Knowledge Bases and Wikis

Copilot connectors can index internal wikis (Confluence, Notion, custom-built platforms) turning scattered pages into a searchable, citable knowledge source for your agent.

Ticketing and Case Management

An agent grounded in ServiceNow or Jira data lets new employees ask “Has anyone reported issues with the VPN on macOS?” and get results from actual support tickets: not a generic FAQ page.

Compliance and Regulatory Data

For industries like insurance (hello, Zava!), grounding an agent in compliance databases means employees can get accurate, up-to-date regulatory information sourced from the compliance system of record.

The Value You Just Unlocked

A single connection_id in your manifest gave us:

• Structured data access: The agent can answer questions from databases, HRIS platforms, wikis, and CRMs, not just documents
• Pre-built connector catalog: Hundreds of connectors for popular platforms (ServiceNow, Salesforce, Jira) ready to use without custom code
• Enterprise permission enforcement: Source system access controls carry over automatically; users only see data they’re authorized to access
• Zero data migration: External data stays in its source system; the connector indexes it in place
• Unified query routing: Copilot automatically routes questions to the right data source, blending document wisdom with database precision
• KQL-powered scoping: Filter indexed content by category, department, or any queryable property so each agent sees exactly the data it needs

The agent went from a document search assistant to an organizational knowledge interface backed by structured data from any system in your enterprise, with no RAG pipeline, no embeddings, and no vector database.

Resources

• Copilot Connectors Overview
• Copilot Connectors in Declarative Agents
• Build a Custom Copilot Connector
• Manage Connection Schema
• KQL Syntax Reference
• Declarative Agent Manifest Schema Reference