Using Aprimo with Microsoft 365 Copilot
Agentic orchestration is one of the fastest-moving areas in enterprise software. Aprimo is actively investing in integrations, tooling, and guidance for platforms like Microsoft 365 Copilot. The patterns and approaches documented here reflect our current best understanding — check back regularly as this space develops. Have a use case or question not covered here? Reach out to your Aprimo Customer Success Manager and we will work with you to understand your use case.
Microsoft 365 Copilot is Microsoft's AI assistant embedded across Teams, Word, PowerPoint, Outlook, and other M365 apps. It can be extended with Declarative Agents — custom AI agents that surface inside the M365 Copilot experience and connect to external systems via API Plugins and Office Add-ins. This article covers those extensibility points and how each one maps to an Aprimo integration pattern.
The GitHub repository can be found at https://github.com/Aprimo-Connect/Aprimo.CoPilot.DeclarativeAgent.
Understanding Microsoft 365 Copilot's Extensibility Model
Declarative Agents are the primary extensibility mechanism for M365 Copilot. A Declarative Agent is a packaged Teams app that gives M365 Copilot a custom persona, a set of instructions, and one or more capabilities: API Plugins for calling external APIs, Office Add-ins for interacting with Office documents, and optional knowledge sources for grounding responses in external content.
Users access Declarative Agents through the Copilot agent store in Teams, Word, PowerPoint, and other M365 apps. The agent appears as a named participant in the Copilot chat experience and the M365 Copilot orchestrator decides which of its capabilities to invoke based on the user's request.
API Plugins
An API Plugin connects a Declarative Agent to an external REST API. It is defined via an OpenAPI specification embedded in the agent's Teams app package. The M365 Copilot orchestrator reads the spec — specifically the operation descriptions — and decides when to call the API based on the user's intent. Authentication is handled via an OAuth client registration in the Teams Developer Portal.
Aprimo connection — Invocation Pattern: The Aprimo REST API can be connected as an API Plugin. Once connected, the agent can search for assets, retrieve record metadata, and surface results directly in the Copilot conversation — all triggered by natural language.
Authentication: M365 Copilot API Plugins support OAuth 2.0 Authorization Code flow with PKCE via the Teams Developer Portal OAuth client registration. This is compatible with Aprimo's OAuth requirements.
Connecting the Aprimo REST API requires two registrations, in order:
- An OAuth client created inside the customer's Aprimo environment (produces the client ID, client secret, and redirect URL)
- A Teams Developer Portal OAuth client registration using those credentials (produces a registration ID that is injected into the agent's app package at build time)
Registration 2 cannot be created without Registration 1.
Office Add-in Insert Actions
Office Add-in Insert Actions are headless JavaScript runtimes bundled into the Declarative Agent's app package. They execute silently inside the active Office host (Word or PowerPoint) when invoked by the Copilot agent — the user never sees a UI. This allows the agent to insert content directly into the open document without requiring the user to copy and paste.
Insert actions only activate when the agent is running inside an Office desktop host. They are not invoked from the Copilot web interface or Teams chat.
Aprimo connection: The Aprimo Declarative Agent exposes two insert actions:
| Action | Description |
|---|---|
InsertImageAsset | Downloads the image binary from Aprimo and inserts it inline into the active Word or PowerPoint document |
InsertAssetReference | Inserts a text reference to an Aprimo record (title and link) into the active document |
The end-to-end flow combines the Invocation Pattern with a document-native output step: the agent calls the Aprimo REST API to find the asset (invocation), then triggers the add-in to insert it into the document (output). From the user's perspective, they search for an asset in the Copilot pane, confirm the selection, and the content appears in their document.
Hosting: The add-in's static files (commands.html, commands.js) must be served over HTTPS at a fixed URL that is referenced in the Teams app manifest.
Declarative Agents that include an Office Add-in runtime are classified by Microsoft as Advanced Declarative Agents. Some Microsoft 365 tenants restrict Advanced Declarative Agents from being deployed at shared (org-wide) scope. This is a tenant-level permission setting that the customer's M365 admin controls.
Aprimo Reference Implementation
Aprimo provides an open-source reference implementation of a Declarative Agent for Microsoft 365 Copilot. It includes:
- A Declarative Agent definition with system prompt
- An API Plugin connecting the Aprimo search and asset endpoints
- An Office Add-in with
InsertImageAssetandInsertAssetReferenceactions - A per-customer build script that substitutes the customer's tenant domain and OAuth registration ID into the app package
| Component | Repository |
|---|---|
| Declarative Agent + API Plugin + Office Add-in | aprimo-m365-copilot-agent |
Deployment Model
Because the Aprimo REST API is tenant-specific — each customer has a unique subdomain (e.g., customertenant.dam.aprimo.com) — there is no single universal app package. A separate package is built per customer using the provided PowerShell build script:
.\scripts\build-customer-package.ps1 `
-Tenant "customertenant" `
-AddinHostUrl "https://addin.aprimo.com" `
-OAuthRegistrationId "teams-portal-registration-id"
The script substitutes the customer's tenant domain into the OpenAPI spec, injects the OAuth registration ID and add-in host URL into the manifest, and produces a validated zip. The customer's M365 admin uploads this zip to the M365 Admin Center and deploys it to target users.
See the reference implementation repository for the full deployment guide including prerequisites, step-by-step instructions, and testing guidance.