Microsoft 365 Copilot agent#

The Reportworq Microsoft 365 Copilot agent lets Copilot users ask about their distribution jobs and the outputs those jobs deliver, in natural language, in chat, Teams, and the Microsoft 365 app, without leaving Copilot. The agent reaches your on-prem instance over the outbound-only CloudHub relay, and every request runs as the signed-in user, scoped to the jobs, folders, and workspaces that user is allowed to see.

This is a two-role task. A Reportworq administrator generates the agent package. A Microsoft Entra Global Administrator grants one-time consent and deploys it to users.

When to use it. Reach for the Copilot agent when your organization has standardized on Microsoft 365 Copilot and wants governed, identity-scoped access to distributed outputs, and when you cannot or do not want to expose an inbound endpoint. Desktop AI clients such as Claude Desktop use the MCP shim instead, and air-gapped deployments use direct on-prem MCP. Claude, VS Code, Cursor, and Cline can also connect directly with each user's own sign-in; see Direct OAuth sign-in for MCP clients. That direct sign-in needs your own Entra app registration: it is not available while the Copilot recipe uses the shared Reportworq multi-tenant Entra application. See Copilot, MCP, and trust paths.

Before you begin#

• The on-prem instance is registered with CloudHub (Enable Cloud API / the Cloud Connector is on). See Copilot, MCP, and trust paths.
• The instance is in OAuth access mode with the CloudHub relay channel enabled and a Cloud API key configured. The Copilot recipe only appears once these are set, because the production Copilot experience is per-user identity.
• You have the Cloud API URL (the CloudHub base URL) and the Cloud API key (the CloudHub connector key) to hand.
• A Microsoft Entra Global Administrator is available for one-time consent and deployment, and agent users have Microsoft 365 Copilot licenses.

Generate the agent package (administrator)#

1. Open Settings ▸ Integrations ▸ AI Agent Access (MCP).

2. Expand the Connect: Microsoft 365 Copilot recipe.

3. Fill in the package fields. Sensible defaults are supplied for each:

   Field	Notes
   Agent name	Defaults to "Reportworq". Shown to Copilot users.
   Description	A short and a long description. The default reads "Query your Reportworq reports in natural language. Find reports with available outputs, ask questions about them, preview their pages, and download or email outputs in Excel, PDF, or PowerPoint, all from inside Copilot."
   Instructions	Guidance the agent follows. Reportworq appends a fixed response-style policy that always wins.
   Conversation starters	Up to six suggested prompts. The four defaults are "What reports are available?", "Show me my most recent report.", "Email me a report as a PDF." and "What can you do with my reports?".
   Color and outline icons	Defaults shipped; if you replace them, match the exact required dimensions.
   Cloud API URL	The CloudHub base URL. Required.
   API key	The CloudHub connector key. This is a routing key, not a workspace selector.

4. Choose Download to get the agent package (.zip) and note the admin-consent link.

5. Hand the .zip and the consent link to your tenant's Microsoft Entra Global Administrator.

The agent's identity is stable across API-key rotations, so a later re-download uploads as an update, not a duplicate. The package does not list tools: Microsoft 365 discovers them from your instance at runtime, so a Reportworq upgrade that adds or changes tools needs no new package. Regenerate and re-upload only when you change the package itself (name, instructions, starters, icons, or sign-in).

Deploy the agent in Microsoft 365 (Entra Global Administrator)#

1. Grant one-time admin consent using the link supplied by the Reportworq administrator. The Reportworq Copilot application is a multi-tenant Entra app, so it works across tenants with tenant consent and no per-customer registration.
2. Deploy the package to users or groups. In the Microsoft 365 admin center, go to Settings ▸ Integrated apps and upload the agent .zip, then assign the recipient users or groups.
3. Consider a staged rollout: deploy to a small test group first, validate against Reportworq, then widen.

A Global Administrator can revoke the application at any time under Entra Enterprise applications.

Use the agent (integration user)#

The first time they use the agent, a Copilot user signs in with their Microsoft 365 work account. From then on, results are automatically limited to their Reportworq permissions. They can, for example:

• Ask what jobs are available.
• Ask for the figures in the latest quarterly forecast, answered from the job's latest output.
• Ask the agent to email a job's output in a chosen format. "Email me" goes to your own address. Copilot asks you to confirm once, showing the output and where it will be sent, before anything is sent.
• Ask it to compare two runs of a job, quoting the source values from each.

Notes and limits#

• Downloads go by identity-gated link or email. Over the CloudHub relay, Copilot is handed a download link that only the user it was issued to can retrieve, whatever the output size. If your policy keeps download links off, outputs are emailed instead.
• The agent works with outputs that already exist. It finds jobs that have available outputs, answers from them, previews their pages, and provides downloads or emails. It cannot run, schedule, refresh, or edit a job, and a job with no available outputs is not listed.
• The package holds no standing credentials. Entra issues short-lived per-user tokens; a token reaches a given instance only over that instance's own relay connection.
• Tools update without a new package. The package always uses dynamic tool discovery: Microsoft 365 reads the tool list from your instance at runtime, so a Reportworq upgrade that adds or changes tools needs no re-download or re-upload. There is no setting for this.

Going deeper. For the outbound-only relay model, the identity-versus-network security boundary, and how the same tools reach desktop clients, see Copilot, MCP, and trust paths. Every agent request is recorded; see MCP audit.