Plug-ins bouwen voor Copilot Cowork

  • Van toepassing op: Microsoft Copilot

Microsoft Copilot Cowork ondersteunt uitbreidbaarheid via M365-app-pakketten, hetzelfde distributiemechanisme dat wordt gebruikt door Teams-apps, Copilot-agents en Office-invoegtoepassingen. Je kunt Cowork uitbreiden met:

  • Vaardigheden: Werkstromen op basis van prompts die Cowork nieuwe domeinexpertise leren, zoals financiële analyse, juridisch onderzoek of HR-werkstromen.
  • Connectors: servers op afstand die Cowork toegang geven tot externe gegevensbronnen en API's.

Beide zijn samen verpakt in een standaard Microsoft 365-app-pakket en worden gedistribueerd via de Microsoft 365 App Store.

Important

Microsoft Purview Informatiebarrières (IB) worden momenteel niet ondersteund voor invoegtoepassings- of vaardigheidsbeheer en delen. In tenants waar IB is ingeschakeld, worden uploads van ingesloten kennisbestanden geblokkeerd op tenantniveau. Hiermee voorkomt u dat de betrokken invoegtoepassingen en vaardigheden worden geüpload of gepubliceerd.

Microsoft maakt of onderhoudt geen permanente index, knowledge graph (inclusief de Microsoft Graph) of database die ISV-inhoud bevat, hetzij door crawlen, scrapen, oogsten, bulksgewijze export, gegevensinvoer of enige andere methode (via API, MCP-server of anderszins). Microsoft kan ISV-inhoud tijdelijk verwerken als dat nodig is om te reageren op de realtimequery van een gebruiker, maar bewaart ISV-inhoud niet langer dan de duur van die sessie. Op schriftelijk verzoek van ISV verwijdert Microsoft binnen 10 werkdagen alle ISV-inhoud die zij in haar bezit of beheer heeft en bevestigt zij dit schriftelijk. Meer informatie in Zakelijke gegevensbescherming in Microsoft Copilot en Microsoft Copilot Chat.

Wat u gaat bouwen

Een Cowork-plug-in is een .zip pakket met:

my-extension.zip
├── manifest.json          # M365 Unified App Manifest (v1.28)
├── color.png              # 192×192 full-color app icon
├── outline.png            # 32×32 outline icon
└── skills/                # Agent Skills (SKILL.md files)
    ├── skill-one/
    │   ├── SKILL.md
    │   └── references/    # Optional deep-dive docs
    └── skill-two/
        └── SKILL.md

Vaardigheden maken gebruik van de Agent Skills-open standaard: dezelfde indeling die wordt ondersteund door Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie en meer dan 30 andere AI-hulpprogramma's.

Uw beginpunt kiezen

Bouw uw plug-in met de wiqd CLI. De CLI maakt het pakket en houdt manifest.json en uw vaardigheidsmappen gesynchroniseerd. Het voert ook de eigen validatieregels van het platform uit voordat u uploadt, waarna het resultaat wordt ingericht en gedeeld. De CLI is in preview, dus de opdrachten en gegenereerde uitvoer kunnen veranderen voordat ze algemeen beschikbaar zijn. Er wordt alleen een eenvoudig Microsoft 365-app-pakket gegenereerd, zodat u de bestanden nog steeds rechtstreeks kunt openen, bewerken en van versies kunt voorzien.

Stel het pakket alleen handmatig samen wanneer u geen hulpprogramma's kunt installeren of wanneer u uw eigen verpakkingspijplijn bouwt. In dat geval hebt u de referentie voor de pakketindeling in dit artikel nodig: het beschrijft precies wat wiqd oplevert.

Beginpunt Doe u het volgende Tijd tot eerste pakket
Ik begin bij nul Een invoegtoepassing bouwen met wiqd ongeveer 10 minuten
Ik heb een bestaande invoegtoepassing voor Claude Code Converteer het ongeveer 5 minuten
Ik kan geen hulpprogramma's installeren, of ik schrijf mijn eigen verpakkingsscripts Een pakket met de hand samenstellen ongeveer 30 minuten

Een invoegtoepassing bouwen met wiqd

De wiqd-CLI doorloopt dezelfde levenscyclus die u anders handmatig uitvoert: creëren, mogelijkheden toevoegen, valideren, inrichten, inpakken en delen. Het pakket dat wordt geproduceerd, voldoet al aan de validatieregels in dit artikel.

Stap 1: Installeer wiqd en meld u aan

Installeer de wiqd CLI door de wiqd-installatiehandleiding te volgen, die betrekking heeft op Windows, macOS en Linux. Meld u vervolgens aan bij de Microsoft 365-tenant waarvoor u ontwikkelt, omdat het inrichten en delen beide gebruikmaken van uw tenant:

wiqd auth login --interactive

Het installatieprogramma registreert ook een GitHub Copilot CLI-invoegtoepassing, zodat u dezelfde levenscyclus in het gesprek kunt beheren. Je kunt bijvoorbeeld zeggen: maak een standalone plugin genaamd Triage Helper of Valideer mijn plugin. Het gesprekspad voert dezelfde opdrachten uit als deze sectie. Gebruik de opdrachten rechtstreeks wanneer u een script voor een pijplijn aan het uitvoeren bent of reproduceerbare, niet-interactieve automatisering wilt.

Stap 2: maak de invoegtoepassing en voeg mogelijkheden toe

Maak de plugincontainer en voeg vervolgens alle mogelijkheden toe die u nodig hebt, in een willekeurige combinatie:

wiqd plugin create --name my-plugin
wiqd plugin add skill --name "Contract Analysis"
wiqd plugin add connector --name "Contoso Legal" --description "Case law and statutes over MCP" --url https://api.contoso.com/legal/mcp

add skill genereert de basis voor appPackage/skills/contract-analysis/SKILL.md en registreert het in agentSkills[]. add connector schrijft de agentConnectors[] vermelding. Beide opdrachten dwingen de naamgeving en groottelimieten van het platform af voordat ze schrijven, dus een mapnaam die niet overeenkomt of een te lange id bereikt nooit het manifest.

Schrijf uw vaardigheidslogica in de gegenereerde SKILL.md. De frontmatter-velden, het model voor progressief laden en de limieten voor companion-bestanden zijn dezelfde als beschreven in Stap 1: Maak uw eerste vaardigheid en Stap 2: Voeg referentiemateriaal toe (optioneel).

Important

wiqd plugin create maakt het pakket vast aan manifestVersion: "1.29", terwijl in dit artikel handmatig opgestelde voorbeelden met 1.28 worden gebruikt. Het verschil is van belang voor connectors. Bij 1,28 is mcpToolDescription vereist en het bestand dat het noemt, moet zich in de postcode bevinden. Bij 1.29 zijn de agentConnectors[] vermeldingen alleen URL's en is mcpToolDescription optioneel, zodat een door wiqd gegenereerd pakket nooit een uploadfout krijgt. WIQD ondersteunt nog geen connectorverificatie. Configureer deze rechtstreeks zoals beschreven in Ondersteunde verificatietypen.

Stap 3: Valideren tijdens het maken

Continu valideren in plaats van een pakket samen te stellen en hopen dat de upload slaagt:

wiqd plugin validate
wiqd plugin validate --mode deep

validate is de offline statische controle over het declaratieve agentoppervlak. Een invoegtoepassing met alleen vaardigheden of connectors slaagt zonder iets te controleren, wat te verwachten is. Het is een controle voor uw buildlus, niet voor volledige dekking. validate --mode deep verpakt eerst de invoegtoepassing en valideert vervolgens de gebouwde .zip aan de hand van dezelfde app-validatiebibliotheek die voor het uploaden wordt gebruikt. Dat is waar de ASKILL-codes en connectorregels opduiken.

Stap 4: Implementeren, verpakken en delen

Voer deze drie opdrachten in de aangegeven volgorde uit:

wiqd plugin provision
wiqd plugin package
wiqd plugin share --scope users --email you@contoso.com

Voer eerst provision uit, omdat dat het omgevingsbestand schrijft waarvan package en share beide afhankelijk zijn. Gebruik --scope users om te delen met de personen die u opgeeft, of --scope tenant om te delen met iedereen in uw organisatie. Hoe dan ook, de plug-in verschijnt in Gedeeld met mij onder Cowork>Bronnen & Skills>Plugins. Als het pakket in de sectie Ontdekken wordt weergegeven, uploadt een beheerder het pakket. Meer informatie vindt u in stap 8: Publiceren naar uw tenant. Als u wilt verwijderen wat provision heeft gemaakt, voert u wiqd plugin delete --env local --yes uit.

Inzending in de openbare Store is nog steeds een handmatig proces in het Partnercentrum. Meer informatie vindt u in stap 9: publiceren voor het publiek.

Een invoegtoepassing overzetten naar een andere host

Als je je vaardigheden wilt gebruiken in Claude Code, Cursor of een andere Agent Skills-host, exporteer je het project in plaats van mappen handmatig te kopiëren:

wiqd plugin export --format claude-plugin

export is standaard ingesteld op --format open-plugin en accepteert ook cursor-plugin. Het schrijft een niet-gecomprimeerde map onder <path>/export/<format>.

Een bestaande invoegtoepassing importeren

Als u al een Claude Code-invoegtoepassingen hebt met vaardigheden en MCP-servers, hebt u twee conversieroutes. De route die je kiest, hangt af van of je van plan bent de plugin te blijven ontwikkelen of gewoon uit te brengen wat je hebt.

Doel Gebruiken
Blijf de invoegtoepassingen ontwikkelen, valideren en uitbrengen vanuit Microsoft 365 wiqd plugin import
Maak nu een publiceerbaar .zip vanuit een bestaande Claude-invoegtoepassing Het conversiescript

Importeren met wiqd

wiqd plugin import herkent een Open Plugin, Claude plugin of Cursor plugin source en produceert er een wiqd plugin project van. De geïmporteerde plug-in doorloopt dezelfde levenscyclus als een plug-in die u met wiqd plugin create hebt gemaakt:

wiqd plugin import --path ./my-claude-plugin --privacy-url https://contoso.com/privacy --terms-url https://contoso.com/terms

--privacy-url en --terms-url zijn alleen vereist voor de eerste import van een invoegtoepassing. Als de bron afkomstig is van een vorige wiqd plugin export, bevat de roundtrip-metadata die gegevens al.

Important

Een geïmporteerd project ondersteunt alleen het alleen-lezen deel van de levenscyclus—wiqd plugin validate, show, en list. Het kan nog niet worden ingepakt, ingericht of gedeeld, omdat tijdens het importeren niet de lokale implementatiebestanden worden ondersteund die nodig zijn voor deze stappen. Dit is een getraceerd hiaat. Controleer de wiqd CLI-referentie voor de huidige status. Als u vandaag een publiceerbaar pakket nodig hebt, gebruikt u het conversiescript.

Converteren met het conversiescript

Het conversiescript vertaalt een Claude-plug-in rechtstreeks naar een publiceerbaar M365-pakket:

  1. Installeer de CLI (versie 1.1.12 of hoger vereist):

    npm install -g @microsoft/m365agentstoolkit-cli

  2. Controleer de versie:

    atk --version

  3. Importeer uw invoegtoepassing:

    atk import openplugin --path ./my-claude-plugin --output ./my-plugin-project \
  --privacy-url https://contoso.com/privacy \
  --terms-url https://contoso.com/terms

De opdracht leest uw invoegtoepassingsmap .claude-plugin/plugin.json (of .cursor-plugin/plugin.json), .mcp.json en skills/ en vervolgens een Agents Toolkit-project met appPackage/manifest.json, uw vaardigheden en gegenereerde pictogrammen.

U moet --privacy-url en --terms-url opnemen, omdat invoegtoepassingsmanifesten geen overeenkomende velden hebben en het Microsoft 365-manifest beide vereist.

Notitie

atk import openpluginzoekt een invoegtoepassingsmanifest in een map met een puntvoorvoegsel—.claude-plugin/plugin.json, .cursor-plugin/plugin.json of .plugin/plugin.json—naast een .mcp.json. De Agent Plugins 1.0.0-specificatie bepaalt dat het manifest zich op het hoogste niveau in plugin.json bevindt en de MCP-configuratie in mcp.json. Als u een invoegtoepassing wilt importeren met de 1.0.0-indeling, verplaatst u het manifest naar .plugin/plugin.json en hernoemt u mcp.json naar .mcp.json.

Verpak het resultaat in een uploadbare .zip:

cd my-plugin-project
atk package --manifest-file ./appPackage/manifest.json \
  --output-package-file ./appPackage/build/appPackage.zip \
  --output-folder ./appPackage/build

Notitie

atk import openplugin genereert een devPreview manifest. De manifestvoorbeelden elders in dit artikel zijn bedoeld voor schema v1.28. Als u publiceert via een kanaal dat v1.28 vereist, werkt u manifestVersion bij en $schema in de gegenereerde appPackage/manifest.json.

Wat wordt geïmporteerd

Invoegtoepassingsartefact M365-equivalent Opmerkingen
.claude-plugin/plugin.json manifest.json Naam-, beschrijvings- en ontwikkelaarsvelden toegewezen; GUID automatisch gegenereerd (deterministische UUID v5)
skills/*/SKILL.md agentSkills[] vermeldingen + skills/ map Letterlijk gekopieerd - identieke indeling
.mcp.json servers agentConnectors[] vermeldingen URL en verificatietype automatisch gedetecteerd
color.png / outline.png Pictogrammen in pakket Gebruikt indien aanwezig; Tijdelijke aanduidingen gegenereerd als deze ontbreken

Important

Voor elke connector die wordt geïmporteerd uit .mcp.json, is de gegenereerde authorization.referenceId een tijdelijke aanduiding die is afgeleid van de naam van de invoegtoepassing en de server. Vervang deze door de werkelijke OAuth-clientregistratie-id voordat u publiceert. Zie Ondersteunde verificatietypen voor meer informatie.

Wat wordt niet geconverteerd

De volgende functies van de Claude-invoegtoepassing worden nog niet ondersteund in het Microsoft 365-manifest:

Claude-invoegtoepassingsfunctie Status
commands/ (slash-opdrachten) Nog niet ondersteund
agents/ (sub-agents) Nog niet ondersteund
hooks/ (gebeurtenis-handlers) Nog niet ondersteund
settings.json Niet van toepassing
bin/ (uitvoerbare bestanden) Niet van toepassing

Opties voor importeren

Option Description
--path, -p Required. Invoegtoepassingsmap met .claude-plugin/plugin.json, .cursor-plugin/plugin.json of .plugin/plugin.json
--output, -o Doelprojectmap (standaard: ./<plugin-name>)
--privacy-url developer.privacyUrl voor het gegenereerde manifest
--terms-url developer.termsOfUseUrl voor het gegenereerde manifest
--website-url developer.websiteUrl. Valt terug op homepage, vervolgens author.url
--app-id De deterministische UUID v5 die voor het manifest is gegenereerd, overschrijven id
--default-auth-type Auto (standaard), None, OAuthPluginVault, of ApiKeyPluginVault

Automatische detectie van het verificatietype:

Source Standaard authenticatietype Reason
Externe HTTPS-URL's OAuthPluginVault De meeste externe API's hebben verificatie nodig
localhost en niet-HTTPS-URL's None Lokale ontwikkelservers

Als de automatische detectie niet overeenkomt met uw instellingen, gebruik --default-auth-type om dit te overschrijven.

Terug exporteren naar de map met invoegtoepassingen

Om een Agents Toolkit-project terug te verplaatsen naar een plug-inmap, bijvoorbeeld om een Claude Code-plug-in en een Cowork-pakket gesynchroniseerd te houden, gebruikt uatk export openplugin:

atk export openplugin --path ./my-plugin-project \
  --output ./my-claude-plugin --manifest-kind claude-plugin
Option Description
--path, -p Required. Projectmap van Agents Toolkit die appPackage/manifest.json bevat
--output, -o Invoegtoepassingsmap met doel (standaard: ./<plugin-name>-openplugin)
--manifest-kind open-plugin (standaard, schrijft .plugin/plugin.json), claude-plugin, of cursor-plugin

Export schrijft een x-microsoft-365-agents-toolkit-blok naar het gegenereerde plugin.json. Dat blok bevat het manifest id, de ontwikkelaars-URL's en de connectorinstellingen, dus een latere atk import openplugin round-trip zonder dat --privacy-url weer nodig is of --terms-url.

Notitie

Het x-microsoft-365-agents-toolkit blok is specifiek voor Agents Toolkit en het standaardtype open-plugin schrijft het manifest naar .plugin/plugin.json. Agent Plugins 1.0.0 maakt gebruik van een topniveau plugin.json en draagt clientspecifieke gegevens onder een extensions sleutel met een reverse-domain namespace, zodat andere clients dit blok negeren in plaats van erop te handelen. Wanneer Claude Code of Cursor uw doelplatform is, gebruikt u --manifest-kind claude-plugin of cursor-plugin.

Verouderd: PowerShell-conversiescript

Voordat atk de import van een invoegtoepassing ondersteunde, werd voor de conversie een PowerShell-script gebruikt dat alleen onder Windows beschikbaar is en beschikbaar blijft als het conversiescript:

.\Convert-ClaudePluginToMOS3.ps1 -PluginPath ./my-claude-plugin -OutputPath ./output

Gebruik in plaats daarvan atk import openplugin. Het is platformonafhankelijk, ondersteunt zowel Cursor- als Claude Code-bronnen en kan terug exporteren naar een plug-inmap.

Een pakket handmatig samenstellen

Deze sectie is de referentie voor pakketformaten: het beschrijft precies wat Build a plugin with wiqd genereert, veld voor veld. Volg dit proces van begin tot eind wanneer u geen tools kunt installeren of wanneer u uw eigen verpakkingspijplijn opzet. Gebruik het als referentie wanneer u een gegenereerd pakket wilt begrijpen of fouten in een gegenereerd pakket wilt opsporen.

Stap 1: Maak je eerste vaardigheid

Een skill is een map die een SKILL.md bestand bevat. Maak de volgende mapstructuur:

my-extension/
└── skills/
    └── contract-analysis/
        └── SKILL.md

Schrijf SKILL.md met YAML-frontmatter en een hoofdtekst in Markdown:

---
name: contract-analysis
description: |
  Analyzes contracts for key terms, risks, and obligations.
  Use when user asks to "review this contract", "find the liability clause",
  "summarize the key terms", or "compare these two agreements".
license: MIT
metadata:
  author: Contoso Legal Tech
  version: "1.0"
---

# Contract Analysis

## What This Skill Does

Guides Cowork through systematic contract review, identifying:
- Key commercial terms (pricing, payment, renewal)
- Risk clauses (indemnification, limitation of liability, IP)
- Obligations and deadlines
- Non-standard or unusual provisions

## Workflow

1. Read the uploaded contract document
2. Extract and categorize all clauses
3. Flag risk areas with severity ratings
4. Generate a structured summary with recommendations

## Output Format

Present findings in a structured table:

| Clause | Category | Risk Level | Summary |
|--------|----------|------------|---------|
| Section 4.2-Indemnification | Risk | High | Unlimited indemnification for IP claims |
| Section 7.1-Term | Commercial | Low | 12-month auto-renewal with 30-day notice |

SKILL.md-frontmattervelden

Vereiste velden:

Veld Beperkingen Description
name 1-64 karakters, kebab-case Vaardigheids-id - moet exact overeenkomen met de naam van de map
description 1-1024 tekens Wanneer gebruikt u deze vaardigheid - voeg triggerzinnen toe

Important

  • De naam van de map moet overeenkomen met het name-veld in de frontmatter. Deze afwijking is de meest voorkomende oorzaak van fouten met vaardigheden.
  • Velden in pluginvermeldingen mogen geen oproepen tot actie bevatten die gebruikers naar externe marktplaatsen leiden om abonnementen te kopen.
Mappad name veld Geldig? Waarom
skills/contract-analysis/SKILL.md contract-analysis Yes Map en naam komen overeen
skills/contract-analysis/SKILL.md ContractAnalysis No De naam is in PascalCase in plaats van overeen te komen met de mapnaam
skills/my-skill/SKILL.md contract-analysis No Map is my-skill maar de naam is contract-analysis

Naamgevingsregels (kebab-case): Gebruik alleen alfanumerieke tekens in kleine letters en afbreekstreepjes. Gebruik geen opeenvolgende afbreekstreepjes en geen afbreekstreepjes aan het begin of einde.

Example Geldig? Issue
bond-relative-value Yes Kleine letters met koppeltekens
fx-carry-trade Yes Kleine letters met koppeltekens
email Yes Eén woord, geen koppeltekens nodig
Bond_Relative_Value No Onderstrepingstekens en hoofdletters
--my-skill-- No Interlinie- en navolgende koppeltekens
my--skill No Opeenvolgende koppeltekens

Stap 2: Referentiemateriaal toevoegen (optioneel)

Voor complexe vaardigheden houdt u de hoofd- SKILL.md compact en verplaatst u gedetailleerde inhoud naar submappen. Deze extra bestanden zijn begeleidende bestanden. De vaardigheid laadt deze indien nodig.

skills/
└── contract-analysis/
    ├── SKILL.md               # Core workflow (~1,500-2,000 words ideal)
    ├── references/            # Deep-dive docs loaded on demand
    │   ├── clause-taxonomy.md
    │   └── risk-scoring.md
    └── scripts/               # Executable utilities
        └── extract-clauses.py

Limieten voor bijbehorende bestanden

Elke vaardigheid kan maximaal 20 begeleidende bestanden bevatten (elk bestand behalve SKILL.md). Per vaardigheid gelden de volgende limieten:

Limit Value
Maximum aantal bijbehorende bestanden 20
Maximale grootte per begeleidend bestand 5 MB
Maximale totale grootte van het bijbehorende bestand 10 MB
Time-out downloaden (alle bijbehorende bestanden) 15 seconden

Regels voor begeleidende bestanden

Begeleidende bestandspaden moeten voldoen aan de volgende regels:

  • Gebruik alleen relatieve paden (geen absolute paden).
  • Geen padtraversal (.. segmenten).
  • Geen backslashes of nulbytes in bestandsnamen.
  • Geen verborgen bestanden (namen die beginnen met .).
  • Geen gereserveerde namen voor Windows (CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9).
  • Het bestand SKILL.md zelf telt niet mee als begeleidend bestand.
  • Bestandsnamen moeten veilige tekens bevatten: alfanumeriek, koppeltekens, onderstrepingstekens, punten, spaties en !.

Om het contextvenster efficiënt te houden, laadt het systeem vaardigheden in drie lagen:

Laag Indien geladen Doelgrootte
Voorwerk (name + description) Altijd - bij het opstarten ~100 tokens
SKILL.md body Wanneer de vaardigheid wordt geactiveerd Minder dan 5.000 tokens (1.500-2.000 woorden)
Referenties (references/) Op verzoek van de agent Unlimited
Scripts (scripts/) Uitgevoerd, niet in de context geladen N/A

Verwijs expliciet in SKILL.md naar de submappen, zodat de agent weet dat ze bestaan:

## Additional Resources

- **`references/clause-taxonomy.md`**-Full taxonomy of contract clause types
- **`references/risk-scoring.md`**-Risk scoring methodology and thresholds
- **`scripts/extract-clauses.py`**-Automated clause extraction utility

Stap 3: Een verbindingslijn toevoegen (optioneel)

Als uw extensie toegang nodig heeft tot externe gegevens, voegt u een externe MCP-server toe. Deze stap is optioneel. Pakketten met alleen vaardigheden werken goed voor op prompts gebaseerde werkstromen.

Tip

Als uw server de zichtbaarheid van hulpprogramma's per client regelt of inkomend verkeer toewijst, gaat u naar Cowork-verkeer naar uw server identificeren voor de clientidentiteit die Cowork presenteert.

Notitie

Aangepaste invoegtoepassingen worden niet ondersteund voor Cowork op mobiele apparaten.

Connectorvereisten

Requirement Details
Transport Streamable HTTP (HTTPS vereist, TLS 1.2+)
Protocol JSON-RPC 2.0-berichtindeling
Ontdekking van tools Ondersteuning van tools/list voor dynamische detectie (aanbevolen)
Uitvoering van softwaretools Ondersteuning van tools/call voor aanroep
Availability Een SLA voor 99,9% beschikbaarheid aanbevolen voor apps die in de store zijn gepubliceerd
Responstijd Minder dan 30 seconden per hulpprogramma-aanroep

Richtlijnen voor toolontwerp

  • Eén hulpprogramma per actie voor kleine API's (minder dan 15 bewerkingen): search_case_law, get_ruling, cite_precedent
  • Search + execute voor grote API's (50+ bewerkingen): search_actions + execute_action
  • Beschrijvende namen: get_bond_price niet getData
  • Uitgebreide invoerschema's: neem een beschrijving op voor elke parameter. Dit is wat de agent leest
  • Gestructureerde uitvoer: Retourneer JSON dat de agent kan opmaken voor de gebruiker
  • Bestandsinvoer: Als u een bestand wilt accepteren vanuit de werkruimte van de gebruiker, declareert u de parameter met contentEncoding: base64. Meer informatie vindt u in Bestanden accepteren uit de Cowork-werkruimte.

Beschrijf de hulpprogramma's van uw connector (mcpToolDescription)

Een remoteMcpServer connector kan optioneel een mcpToolDescription object bevatten. Als deze is opgegeven, verwijst de geneste file eigenschap naar een JSON-bestand met een hulpprogrammabeschrijving, dat u in uw .zip verpakt en waarnaar wordt verwezen via een relatief pad vanaf de hoofdmap van het pakket. Cowork detecteert hulpprogramma's dynamisch van uw MCP-server en gebruikt dit bestand niet, zelfs niet als het aanwezig is.

"remoteMcpServer": {
  "mcpServerUrl": "https://api.contoso.com/legal/mcp",
  "mcpToolDescription": {
    "file": "./tools/contoso-legal-tools.json"
  },
  "authorization": {
    "type": "OAuthPluginVault",
    "referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
  }
}

Als u mcpToolDescription opneemt, beschrijft het bestand waarnaar wordt verwezen (bijvoorbeeld tools/contoso-legal-tools.json) de hulpprogramma's die de connector beschikbaar stelt en aanwezig moet zijn in het ZIP-pakket. Voeg deze toe aan uw manifest.json en skills/ map wanneer u de invoegverpakking verpakt.

Tip

Deze vereiste geldt voor manifestversie 1.28. Pakketten die wiqd plugin create doel 1.29 genereren, waarbij agentConnectors[] vermeldingen alleen URL's zijn, mcpToolDescription is optioneel en er is geen hulpprogrammabeschrijvingsbestand om te vergeten.

Ondersteunde authenticatietypen

Verificatietype Wanneer gebruiken Gebruikerservaring
None Openbare of anonieme API's, interne diensten Transparant - geen authenticatieprompt
OAuthPluginVault OAuth 2.0 API's (aanbevolen voor productie) De gebruiker hoeft slechts één keer OAuth-toestemming te geven
ApiKeyPluginVault Services op basis van API-sleutels De gebruiker voert de sleutel één keer in

Notitie

  • Ondersteuning voor API-sleutelverificatie is nog niet beschikbaar in Cowork.
  • Als uw MCP-server een API-sleutel vereist, gebruikt u OAuthPluginVault of Dynamic Client Registration of stelt u een eindpunt beschikbaar dat None accepteert.

U vindt een referentiepatroon dat Cowork verbindt met een met API-sleutel beveiligde service via een met Entra beveiligd MCP-eindpunt in Build a plugin voor een Line-Of-Business-API.

Voor OAuthPluginVault en ApiKeyPluginVault, verwijst de referenceId naar referenties die zijn opgeslagen in de Microsoft Enterprise Token Store. Geheimen worden nooit weergegeven in het manifest- of vaardigheidsbestand. De referenceId waarde is de OAuth-clientregistratie-id die u maakt wanneer u een OAuth-client registreert bij Agents Toolkit.

Important

Wanneer u uw OAuth-client registreert, stelt u het gebruik per organisatie in op Elke Microsoft 365-organisatie zodat uw invoegtoepassing op alle tenants werkt.

MCP-verificatie

Raadpleeg Authenticatie configureren voor MCP- en API-plug-ins in agents in Microsoft 365 Copilot voor installatie- en configuratiedetails als u OAuth of ApiKey wilt gebruiken voor authenticatie.

Dynamische clientregistratie

Als uw MCP-server Dynamic Client Registration (DCR) ondersteunt, kunt u een authentication-configuratie uit uw connectordefinitie weglaten en maakt Cowork automatisch een OAuth-client namens uw invoegtoepassing.

Notitie

Het weglaten van de authentication configuratie wordt alleen ondersteund in Cowork. Het wordt niet ondersteund in Copilot Chat. Als uw invoegtoepassing ook moet werken in Copilot Chat, configureert u OAuthPluginVault verificatie, zoals beschreven in Ondersteunde verificatietypen.

U kunt het authorization object helemaal weglaten. Configureer de URL van uw MCP-server en Cowork zorgt voor de OAuth-client:

"remoteMcpServer": {
  "mcpServerUrl": "https://api.contoso.com/legal/mcp"
}

Stap 4: Het manifest maken

Maak manifest.json aan in de hoofdmap van je pakket. In het voorbeeld wordt gebruikgemaakt van manifestversie 1.28; wiqd plugin create zet in plaats daarvan versie 1.29 vast, waar connectorvermeldingen alleen uit URL's bestaan.

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.28/MicrosoftTeams.schema.json",
  "manifestVersion": "1.28",
  "version": "1.0.0",
  "id": "YOUR-GUID-HERE",
  "developer": {
    "name": "Contoso Legal Tech",
    "websiteUrl": "https://contoso.com",
    "privacyUrl": "https://contoso.com/privacy",
    "termsOfUseUrl": "https://contoso.com/terms"
  },
  "name": {
    "short": "Contoso Legal Tools",
    "full": "Contoso Legal Tools for Copilot Cowork"
  },
  "description": {
    "short": "Contract analysis, clause extraction, and legal research",
    "full": "Comprehensive legal tools for Copilot Cowork including contract analysis, clause extraction, risk assessment, and legal research capabilities."
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "accentColor": "#2B579A",
  "agentSkills": [
    { "folder": "./skills/contract-analysis" }
  ]
}

Om een connector toe te voegen, neemt u agentConnectors op:

{
  "agentConnectors": [
    {
      "id": "contoso-legal-api",
      "displayName": "Contoso Legal Database",
      "description": "Access to case law, statutes, and regulatory databases",
      "toolSource": {
        "remoteMcpServer": {
          "mcpServerUrl": "https://api.contoso.com/legal/mcp",
          "mcpToolDescription": {
            "file": "./tools/contoso-legal-tools.json"
          },
          "authorization": {
            "type": "OAuthPluginVault",
            "referenceId": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u"
          }
        }
      }
    }
  ]
}

In de connectorconfiguratie moet referenceId de OAuth-registratie-id zijn. Als u mcpToolDescription opneemt, moet de bijbehorende file verwijzen naar een JSON-bestand met de beschrijving van het hulpprogramma dat is opgenomen in het ZIP-pakket.

Important

Het manifestschema van v1.28 is streng: het stelt additionalProperties: false op rootniveau in, dus elk veld dat niet in het schema is gedefinieerd, wordt geweigerd. Velden die geldig zijn in standaard Teams-app-manifesten, zoals packageName, zorgen ervoor dat het uploaden mislukt met een fout zoals Property 'packageName' has not been defined and the schema does not allow additional properties. Alleen de hier getoonde velden opnemen.

Stap 5: Pictogrammen toevoegen

Maak twee PNG-pictogrammen:

Pictogram Size Purpose
color.png 192×192 px App-pictogram in kleur weergegeven in Store en lijst met apps
outline.png 32×32 px Contourpictogram in één kleur voor compacte weergaven

Als u nog geen pictogrammen hebt, genereert u atk import openplugin effen plaatsaanduidingen. Vervang ze voordat u deze indient bij de Store.

Stap 6: Verpakken

Maak een ZIP-bestand met alle inhoud in de hoofdmap. (wiqd plugin package produceert dezelfde structuur na wiqd plugin provision.)

contoso-legal-tools.zip
├── manifest.json
├── color.png
├── outline.png
├── tools/
│   └── contoso-legal-tools.json   # Referenced by mcpToolDescription (optional, connectors only)
└── skills/
    └── contract-analysis/
        ├── SKILL.md
        └── references/
            └── clause-taxonomy.md

Als een connector mcpToolDescription bevat, moet u het JSON-bestand met de beschrijving van het hulpprogramma opnemen waarnaar dit verwijst. Pakketten die geen gebruikmaken van mcpToolDescription, waaronder pakketten met alleen vaardigheden, hebben geen tools/ map nodig.

Windows (PowerShell):

Compress-Archive -Path manifest.json, color.png, outline.png, tools, skills -DestinationPath contoso-legal-tools.zip

macOS/Linux:

zip -r contoso-legal-tools.zip manifest.json color.png outline.png tools/ skills/

Microsoft 365 Agents Toolkit gebruiken

 atk package --manifest-file ./appPackage/manifest.json \
       --output-package-file ./appPackage/build/appPackage.zip \
       --output-folder ./appPackage/build

Stap 7: Test

Als u uw app wilt testen, uploadt u het app-pakket naar Teams, zoals beschreven in Uw app uploaden naar Teams.

Als u de plug-in met wiqd hebt gebouwd, voert u in plaats daarvan wiqd plugin provision uit: het registreert de plug-in voor u bij uw tenant. Voor persoonlijk testen van een met de hand samengesteld pakket, sideload de app met behulp van de opdrachtregelinterface van de Microsoft 365 Agents Toolkit:

  1. Installeer @microsoft/m365agentstoolkit-cli vanaf npm:

    npm install -g @microsoft/m365agentstoolkit-cli

  2. Controleer de installatie door het volgende uit te voeren:

    atk --version

  3. Aanmelden met uw Microsoft 365-werkaccount:

    atk auth login

  4. Meld u aan bij uw werkaccount en installeer het agentpakket. Vervang het bestandspad door die van uw ZIP-bestand:

    atk install --file-path "C:/Users/myuser/myPackage.zip" --scope Personal

    Een geslaagde installatie retourneert uitvoer met een TitleId en AppId voor uw account.

  5. Sla deze id's op voor later gebruik wanneer u ze bijwerkt of deïnstalleert.

Meer informatie vindt u in de opdrachtregelinterface van de Microsoft 365 Agents Toolkit.

Stap 8: Publiceren naar uw tenant

Upload het pakket in het beheercentrum om uw plug-in te vermelden in de sectie Discover, waar iedereen in uw organisatie de plug-in kan vinden:

  1. M365-beheercentrum> openenApps> beherenAangepaste app uploaden.
  2. Selecteer het beletselteken (...) >Agent toevoegen.
  3. Laad uw .zip pakket op.
  4. Open Cowork>Bronnen & vaardigheden>Invoegtoepassingen. Uw invoegtoepassing wordt weergegeven in de sectie Ontdekken.

wiqd plugin share plaatst de plugin in Gedeeld met mij in plaats van Discover. Gebruik het voor tests en voor gerichte implementatie bij specifieke personen. Uploads vanuit het Beheercentrum zorgen ervoor dat een invoegtoepassing wordt gedetecteerd.

Stap 9: Publiceer voor het publiek

Voor invoegtoepassingen die zijn bedoeld voor openbare distributie, dient u uw invoegtoepassing in bij de Microsoft 365 App Store via Partner Center. Meer informatie in Agents publiceren voor Microsoft 365 Copilot.

Een connector testen met een lokale MCP-server

Voor connectors is een HTTPS mcpServerUrlvereist. Als u een server die op uw computer wordt uitgevoerd, wilt testen, moet u deze toegankelijk maken via een openbare HTTPS-URL. Dev-tunnels bieden een relay waarmee TLS voor u wordt beëindigd.

devtunnel port create <tunnel> -p <port> --protocol http

Important

Gebruik --protocol http, niet https. De --protocol vlag beschrijft de lokale service waarnaar de tunnel doorstuurt, niet de URL van de openbare tunnel. De meeste lokale MCP-servers spreken gewoon HTTP, dus als u --protocol https instelt terwijl uw server HTTP aanbiedt, retourneert elke aanvraag door de tunnel een 502 fout. De relay beëindigt TLS en stelt de publieke URL via HTTPS beschikbaar, ongeacht deze vlag.

Troubleshooting

Symptom Oorzaak Repareren
Elk getunneld verzoek retourneert 502 en de lokale server spreekt HTTP devtunnel port create werd uitgevoerd met --protocol https Maak de poort opnieuw met --protocol http
Getunnelde verzoeken geven 502 terug op macOS, zelfs als de lokale server actief is De server is gebonden aan 0.0.0.0 (IPv4-only), maar de tunnel maakt verbinding met localhost, wat eerst oplost naar ::1 (IPv6) Bind de server aan :: zodat deze zowel IPv4- als IPv6-verbindingen accepteert
Uploaden is mislukt met Property '<field>' has not been defined and the schema does not allow additional properties Het manifest bevat een veld dat niet is toegestaan in het v1.28-schema (bijvoorbeeld packageName) Verwijder het veld; het v1.28-schema gebruikt additionalProperties: false

Verpakkingspatronen

Kies het patroon dat bij jouw extensie past:

Alleen Skills (geen connector)

Geschikt voor werkstromen op basis van prompts, documentanalyse en hulp bij het schrijven.

my-skills-pack.zip
├── manifest.json          # agentSkills only, no agentConnectors
├── color.png
├── outline.png
└── skills/
    ├── skill-one/SKILL.md
    └── skill-two/SKILL.md

Vaardigheden + externe connector

Ideaal voor gegevensanalyse, API-integraties en bedrijfssystemen.

my-data-skills.zip
├── manifest.json          # agentSkills + agentConnectors
├── color.png
├── outline.png
├── tools/                 # Tool-description file(s) for mcpToolDescription (optional)
│   └── my-connector.json
└── skills/
    ├── analysis-workflow/SKILL.md
    └── reporting-workflow/SKILL.md

Alleen de connector (geen aangepaste vaardigheden)

Gebruik deze optie voor gegevensbronnen die de ingebouwde vaardigheden van Cowork al kunnen gebruiken.

my-connector.zip
├── manifest.json          # agentConnectors only, no agentSkills
├── color.png
├── outline.png
└── tools/                 # Tool-description file(s) for mcpToolDescription (optional)
    └── my-connector.json

Geïmporteerde Claude Code of Cursor-invoegtoepassing

Gebruik deze optie voor bestaande plug-ins voor het Claude-ecosysteem die gericht zijn op Cowork. Als u de invoegtoepassing in Microsoft 365 wilt blijven ontwikkelen, importeert u deze:

wiqd plugin import --path ./claude-plugin --privacy-url https://contoso.com/privacy --terms-url https://contoso.com/terms

Gebruik het conversiescript om een publiceerbaar .zip te produceren vanuit de invoegtoepassing zoals die er nu uitziet:

atk import openplugin --path ./claude-plugin --output ./my-plugin-project \
  --privacy-url https://contoso.com/privacy \
  --terms-url https://contoso.com/terms

Best practices voor het ontwerpen van vaardigheden

Volg deze richtlijnen om vaardigheden te ontwikkelen die betrouwbaar worden geactiveerd en consistente resultaten produceren.

Effectieve beschrijvingen schrijven

Het description veld bepaalt wanneer de agent je vaardigheid activeert. Wees specifiek:

# Good-specific trigger phrases, concrete scenarios
description: |
  Analyzes bond relative value using Z-spreads, ASW spreads, and butterfly analysis.
  Use when user asks to "analyze bond spreads", "compare bonds",
  "rich-cheap analysis", "relative value", or "Z-spread calculation".

# Bad-vague, no trigger phrases
description: Provides bond analytics capabilities.

Schrijf effectieve werkstromen

  • Wees specifiek in de beschrijving. Voeg triggerzinnen toe: "Gebruik wanneer de gebruiker vraagt om..." Met deze beschrijving bepaalt de agent welke vaardigheid moet worden geactiveerd.
  • Structureer als een workflow. Geef de stappen een nummer. Elke stap moet worden toegewezen aan een concrete actie (een bestand lezen, een tool aanroepen, uitvoer genereren).
  • Uitvoerindeling definiëren. Geef de exacte tabel-, lijst- of documentstructuur weer die gebruikers mogen verwachten. Deze definitie verbetert de consistentie drastisch.
  • Verwijs naar tools bij naam. Als uw vaardigheid afhankelijk is van connectors, noem die dan expliciet: "Gebruik het hulpprogramma search_case_law om..."
  • Houd de SKILL.md beknopt. Verplaats gedetailleerd referentiemateriaal naar de references/ submap. De inhoud van de vaardigheid moet de werkstroom zijn, geen encyclopedie.

Veelvoorkomende fouten voorkomen

  • Neem geen geheimen op in SKILL.md-bestanden. Gebruik agentConnectors voor verificatie met API-inloggegevens.
  • Dupliceer geen ingebouwde vaardigheden. Controleer de lijst met ingebouwde vaardigheden voordat u gaat bouwen.
  • Maak geen vaardigheden te breed. "Alles doen met juridische documenten" werkt slechter dan specifieke vaardigheden voor "contractanalyse", "clausule-extractie" en "juridisch onderzoek".
  • Hardcodeer geen bestandspaden of systeemopdrachten. Vaardigheden moeten in verschillende omgevingen inzetbaar zijn.
  • Zet niet alles in SKILL.md. Als uw hoofdtekst meer dan ~3.000 woorden bevat, verplaatst u gedetailleerde inhoud naar references/.

Validatieregels

Wanneer u uw pakket indient, valideert het platform het op meerdere niveaus. Corrigeer deze fouten voordat u ze inzendt om afwijzing te voorkomen.

Als u ze tijdens het bouwen wilt opvangen in plaats van tijdens het uploaden, voert u het volgende uit wiqd plugin validate --mode deep. Deze opdracht verpakt de invoegtoepassing en voert dezelfde regels lokaal uit. Meer informatie in Stap 3: Valideren tijdens het bouwen.

Validatie op manifestniveau

Code Rule Severity
ASKILL-M001 folder is vereist voor elke agentSkills vermelding Fout
ASKILL-M002 agentSkills array kan maximaal 20 items bevatten Fout
ASKILL-M003 folder pad mag maximaal 256 tekens bevatten Fout

Validatie op pakketniveau

Code Rule Standaardoplossing Severity
ASKILL-P001 Map waar in het manifest naar wordt verwezen, bestaat in het ZIP-bestand Controleer uw ZIP-structuur Fout
ASKILL-P002 Map bevat een SKILL.md bestand Ontbrekende SKILL.md toevoegen Fout
ASKILL-P003 SKILL.md heeft geldige YAML-frontmatter tussen --- scheidingstekens YAML-syntaxis corrigeren Fout
ASKILL-P004 Frontmatter bevat het veld name Voeg name: toe aan de frontmatter Fout
ASKILL-P005 Frontmatter bevat het veld description Voeg description: toe aan de frontmatter Fout
ASKILL-P006 name komt overeen met de mapnaam (laatste padsegment) Wijzig de naam van de map of herstel name: Fout
ASKILL-P007 name is kebab-case Gebruik my-skill niet MySkill of my_skill Fout
ASKILL-P008 Geen dubbele folder waarden in de matrix Dubbele items verwijderen Fout

Connectorvalidatie

Rule Severity
Voor elke connector is een id en displayName vereist Fout
Alle waarden van connector id moeten binnen het manifest uniek zijn Fout
Precies één van plugin of remoteMcpServer Fout
mcpServerUrl moet een geldige HTTPS-URL zijn Fout
Als mcpToolDescription aanwezig is, moet de file aanwezig zijn in het ZIP-bestand Fout
authorization.referenceId is vereist, tenzij het type None is Fout
authorization.referenceId mag niet aanwezig zijn wanneer het type is None Fout

Validatie van bijbehorend bestand

Het portaal valideert begeleidende bestanden (referentiemateriaal, scripts en andere bestanden naast SKILL.md) tijdens het uploaden en synchroniseren:

Rule Severity
Maximaal 20 companion-bestanden per skill (met uitzondering van SKILL.md) Fout
Elk bijbehorend bestand mag niet groter zijn dan 5 MB Fout
De totale grootte van bijbehorende bestanden mag per vaardigheid maximaal 10 MB zijn Fout
Bestandspaden moeten relatief zijn (geen absolute paden) Fout
Geen path traversal-segmenten (..) Fout
Geen backslashes of nulbytes in bestandsnamen Fout
Geen verborgen bestanden (namen die beginnen met .) Fout
Geen door Windows gereserveerde namen (CON, AUX, PRN, NUL, COM1–COM9, LPT1–LPT9) Fout
Bestandsnamen mogen alleen veilige tekens bevatten (alfanumeriek, streepjes, onderstrepingstekens, punten, spaties, !) Fout

Platformoverschrijdende compatibiliteit

Skills maken gebruik van de open standaard van Agent Skills. Dezelfde SKILL.md bestanden werken in meerdere AI-hulpprogramma's:

Platform Compatibility
Claude Code Exact dezelfde SKILL.md indeling
Claude.ai Projecten Volledige vaardigheden kunnen als projectbestanden worden geüpload
VS Code/GitHub Copilot Volledige agentvaardigheden worden ondersteund in de agentmodus
Gemini CLI Volledige agentvaardigheden worden ondersteund
JetBrains Junie Volledige agentvaardigheden worden ondersteund
OpenAI Codex Volledige agentvaardigheden worden ondersteund
Cursor Volledige agentvaardigheden worden ondersteund

Als u vaardigheden ontwikkelt voor zowel Claude Code als Copilot Cowork, schrijf de invoegtoepassing dan met wiqd. Voer vervolgens wiqd plugin export --format claude-plugin uit om de Claude Code-indeling te genereren. Als u liever begint met de structuur van de Claude Code-invoegtoepassing — dat is de meest uitgebreide variant — dan is de indeling:

my-plugin/
├── .claude-plugin/
│   └── plugin.json        # Claude plugin manifest
├── skills/
│   ├── skill-one/
│   │   ├── SKILL.md       # Works in both Claude Code AND M365
│   │   └── references/
│   └── skill-two/
│       └── SKILL.md
└── .mcp.json              # MCP server config (optional)

Breng het vervolgens naar Microsoft 365 wanneer u klaar bent om in de Microsoft 365 App Store te publiceren, met wiqd plugin import of met het conversiescript:

atk import openplugin --path ./my-plugin --output ./my-plugin-project \
  --privacy-url https://contoso.com/privacy \
  --terms-url https://contoso.com/terms

Beheer van MCP-annotaties en bevestigingen

Copilot Cowork leest het standaard MCP-object annotations bij hulpprogramma's die uw server van tools/list retourneert en gebruikt dit om te bepalen of een hulpprogramma-aanroep door de gebruiker moet worden bevestigd en welk label op de prompt moet worden weergegeven.

Beschikbare velden

Veld Type Effect
readOnlyHint bool false: bevestiging vereist voordat het hulpprogramma wordt uitgevoerd.
destructiveHint bool true: bevestiging vereist voordat het hulpprogramma wordt uitgevoerd.
title string Een leesbaar label dat wordt weergegeven in het bevestigingsdialoogvenster. Valt terug op de naam van het hulpprogramma als die ontbreekt.

Bevestigingsregels

Bevestiging is vereist als readOnlyHint == false of destructiveHint == true.

Voor alle gereedschappen moeten veiligheidsannotaties zijn gespecificeerd. Hulpprogramma's zonder aantekeningen worden als destructief beschouwd en vereisen bevestiging. Meer informatie vindt u in de MCP-schemaverwijzing.

MCP-voorbeelden

Een destructieve actie met een vriendelijk label:

{
  "name": "send_email",
  "description": "Send an email message.",
  "annotations": {
    "title": "Send Email",
    "destructiveHint": true
  },
  "inputSchema": { ... }
}

Een veilige leesbewerking die automatisch wordt uitgevoerd:

{
  "name": "search_docs",
  "annotations": {
    "title": "Search Documents",
    "readOnlyHint": true
  }
}

Wat is er nu beschikbaar

  • Microsoft-hulpprogramma's (Graph, Dataverse en andere) vallen onder het ingebouwde beleid van Cowork, ongeacht eventuele aantekeningen.
  • Voor MCP-servers die niet van Microsoft zijn, wordt aantekeninggestuurde bevestiging geleidelijk geïmplementeerd. Het instellen van de hints is nu toekomstbestendig en bevestigingsprompts verschijnen wanneer de implementatie wordt uitgebreid, zonder dat er een wijziging van de ontwikkelaar nodig is.

Accepteer bestanden uit de Cowork-werkruimte

Een connectorhulpprogramma kan een bestand uit de Cowork-sessie van de gebruiker als invoer gebruiken: een document dat de gebruiker heeft bijgevoegd, een e-mailbijlage die door Cowork is opgeslagen of een bestand dat een eerdere stap heeft geproduceerd. Definieer de parameter met het standaard JSON Schema-trefwoord contentEncoding: base64 en Cowork regelt de rest. Er is geen vereiste Microsoft-specifieke schema-extensie en het API-oppervlak van uw server verandert niet.

Cowork bepaalt het werkruimtebestand en base64 codeert het voordat uw server wordt aangeroepen, zodat bestandsbytes nooit in de context van de agent belanden. De agent ziet en geeft alleen werkruimtebestandspaden door.

Notitie

Geef de agent niet de opdracht om zelf een bestand met base64 te coderen en de blob in een hulpprogramma-aanroep te plakken. Met deze benadering wordt het hele bestand in de context van het model geladen en is deze afhankelijk van het model dat de blob exact reproduceert. Het lijkt te werken bij kleine testbestanden en werkt niet bij echte bestanden.

Een bestandsparameter declareren

Een tekenreekseigenschap met contentEncoding: base64 wordt herkend als bestandsinvoer:

{
  "name": "analyze_contract",
  "description": "Extract key terms from a contract document.",
  "annotations": {
    "title": "Analyze Contract",
    "readOnlyHint": true
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "document": {
        "type": "string",
        "contentEncoding": "base64",
        "description": "The contract file to analyze."
      },
      "jurisdiction": {
        "type": "string",
        "description": "Two-letter country code governing the contract."
      }
    },
    "required": ["document"]
  }
}

Een lijst van dergelijke tekenreeksen wordt ook herkend voor hulpprogramma's die meerdere bestanden accepteren:

"attachments": {
  "type": "array",
  "items": { "type": "string", "contentEncoding": "base64" },
  "description": "Receipt images to attach to the expense line."
}

Wat de agent ziet

Voor bestandsparameters die op het hoogste niveau zijn inputSchema.propertiesgedeclareerd, vervangt Cowork deze in het modelgerichte schema door een enkele direct_attachment_file_paths array - dezelfde parameter die de ingebouwde tools van Cowork gebruiken, zodat de agent al weet hoe deze moet worden ingevuld. Het bovenstaande schema wordt aan de agent gepresenteerd als:

{
  "type": "object",
  "properties": {
    "direct_attachment_file_paths": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Workspace file paths to attach."
    },
    "jurisdiction": { "type": "string" }
  }
}

Als uw hulpprogramma meer dan één bestandsparameter op het hoogste niveau declareert, worden deze allemaal samengevouwen in die ene direct_attachment_file_paths array. Op het moment van aanroepen wijst Cowork de opgeloste bestanden opnieuw toe aan uw oorspronkelijke parameternamen in declaratievolgorde.

Geneste bestandsparameters

De agent ondersteunt een bestandsparameter die is genest in een object of een matrix van objecten. De agent verwerkt deze parameter anders: in plaats van deze samen te voegen, herschrijft de agent deze op dezelfde plaats naar een padstring op de oorspronkelijke locatie. Bij deze benadering blijft de koppeling tussen een bestand en de verwante velden behouden. U ontvangt bijvoorbeeld één kwitantie per onkostenpost:

"line_items": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "amount": { "type": "number" },
      "receipt": { "type": "string", "contentEncoding": "base64" }
    }
  }
}

De agent vult line_items[].receipt met een werkruimtepad en Cowork vervangt elk pad ter plekke door base64-inhoud voordat de aanroep wordt doorgeschakeld.

Geneste structuren worden doorlopen tot een diepte van vier niveaus onder de top van inputSchema. $ref aanwijzers worden niet gevolgd: definieer bestandsparameters inline in plaats van achter een $ref.

Wat uw server ontvangt

Je server ontvangt een standaard tools/call met je oorspronkelijke parameternamen ingevuld met inhoud die is gecodeerd met base64:

{
  "method": "tools/call",
  "params": {
    "name": "analyze_contract",
    "arguments": {
      "document": "JVBERi0xLjQKJcfsj6IKNSAwIG9iago8PC9MZW5...",
      "jurisdiction": "US"
    }
  }
}

Uw server hoeft niet te weten dat de agent een op paden gebaseerde interface heeft gebruikt en hulpprogramma's die geen parameters declareren contentEncoding: base64 , worden niet beïnvloed.

Limits

Limit Value
Bestanden per hulpprogramma-aanroep 8
Grootte per bestand 150 MiB
Totale grootte per gereedschapsoproep 150 MiB
Parameters voor matrixbestanden per hulpprogramma 1 (combineer het met een willekeurig aantal scalaire bestandsparameters)
Maximale nestdiepte 4 niveaus onder de top van inputSchema

Een aanroep die het maximale aantal bestanden of een groottelimiet overschrijdt, mislukt met een hulpprogrammafout en bereikt uw server nooit. Bepaal de grootte van uw API en de time-outs met het plafond van 150 MiB in gedachten: base64 blaast de payload met ongeveer een derde op ten opzichte van de onbewerkte bestandsgrootte en de gecodeerde inhoud wordt verzonden in de JSON-RPC-aanvraagtekst.

Recommendations

  • Beschrijf de parameter voor een menselijke lezer. De agent bepaalt aan de hand van de beschrijving welk bestand bij welke parameter hoort. Bijvoorbeeld werkt "The signed contract PDF to analyze" beter dan "file".
  • Geef de notaties op die u accepteert in de parameterbeschrijving. Cowork voert alles wat de gebruiker bijvoegt door. Valideer het inhoudstype aan jouw kant en retourneer een duidelijke toolfout als deze niet bruikbaar is.
  • Aantekeningen instellen. Een hulpprogramma dat een bestand ontvangt en hierop bewerkingen uitvoert, is normaal gesproken niet alleen-leesbaar, dus vraagt het om bevestiging. Lees meer in Beheer van MCP-annotaties en -bevestiging.
  • Houd bestandsparameters inline. Een parameter achter een $ref, of meer dan vier niveaus diep genest, wordt niet opnieuw geschreven. De server zou een padtekenreeks ontvangen waar inhoud wordt verwacht.
  • Definieer ten hoogste één arraybestandsparameter per hulpprogramma. Bij twee of meer bestanden kan Cowork niet bepalen welk bestand bij welke matrix hoort, en mislukt de oproep met een hulpprogrammafout. Gebruik één matrix of meerdere scalaire parameters of een combinatie van scalaire waarden en één matrix.
  • Verwacht een exacte telling voor hulpprogramma's die alleen scalaire waarden ondersteunen. Als je hulpprogramma alleen scalaire bestandsparameters declareert, moet het aantal bestanden dat de agent doorgeeft overeenkomen met het gedeclareerde aantal. Markeer optionele bestandsparameters duidelijk in hun beschrijvingen, zodat de agent niet te weinig of te veel levert.

Notitie

Dit mechanisme dateert van vóór het eigen bestandsinvoerwerk van het Model Context Protocol, dat wordt gestandaardiseerd door de MCP File Uploads Working Group. Cowork voegt mogelijk ondersteuning toe voor de gestandaardiseerde vorm van declaratieve bestandsinvoer zodra die beschikbaar is. Het contentEncoding: base64 contract dat hier wordt beschreven, blijft van kracht.

Detecteer het Cowork-verkeer naar uw server

Als uw MCP-server de zichtbaarheid van hulpprogramma's per client beperkt, of als u het verkeer dat deze ontvangt wilt toewijzen, kunt u verzoeken van Cowork herkennen. Cowork presenteert een stabiele software-identiteit op twee kanalen:

Channel Waar u dit ziet Value
User-Agent aanvraagheader Elk uitgaand verzoek dat Cowork naar uw server verzendt copilot-cowork/1.0
clientInfoin de MCP-handshake initialize Alleen het initialize verzoek { "name": "copilot-cowork", "version": "<version>" }

Zoeken op het copilot-cowork voorvoegsel

Laat het copilot-coworkvoorvoegsel (niet hoofdlettergevoelig) overeenkomen op beide kanalen. Laat geen exacte copilot-cowork/1.0 tekenreeks of een specifiek clientInfo.version overeenkomen. De versie volgt het client-identiteitscontract en zal naar verwachting veranderen; een voorvoegselovereenkomst zorgt ervoor dat uw poort blijft werken bij versiewijzigingen.

# Correct: case-insensitive prefix match
copilot-cowork

# Incorrect: exact match breaks when the version changes
copilot-cowork/1.0

Het juiste kanaal kiezen voor uw poort

De twee kanalen hebben verschillende bereiken, dus baseer u op het kanaal dat overeenkomt met de manier waarop uw server de toegang afdwingt:

  • De User-Agent header is aanwezig op elk verzoek, inclusief tools/list en tools/call. Als u de toegang beperkt of toewijst per aanvraag, baseer dit dan op deze header.
  • clientInfo wordt alleen verzonden op de initialize handshake. Als u de toegang per sessie beperkt bij het tot stand brengen van de verbinding, kunt u dit daar lezen, maar het wordt niet herhaald bij latere aanvragen.

Wat de identiteit wel en niet omvat

De identiteit benoemt alleen de software. Het is hetzelfde voor elke Cowork-gebruiker en -verbinding, en het draagt nooit een gebruikersidentiteit. De gebruikers-id blijft aanwezig in de autorisatiestroom die door de verificatieconfiguratie van de connector wordt gedefinieerd.

De identiteit omvat De identiteit bevat geen
Een stabiele softwarenaam (copilot-cowork) en een contractversie Elke tenant-, gebruikers-, sessie- of gespreks-id
Dezelfde waarde op elke verzoek en elke verbinding Een kwalificatie per connector

Omdat er geen kwalificatie per connector is, kunt u deze identiteit momenteel niet gebruiken om te bepalen welke connector een aanroep heeft gedaan of om een gepubliceerde Microsoft-invoegtoepassing te scheiden van een zijdelings geladen server die naar dezelfde URL wijst. Als u dat onderscheid nodig hebt, dwingt u dit af via de autorisatieconfiguratie van uw connector in plaats van via de clientidentiteit.

Veelgestelde vragen

Kan ik vaardigheden uit het M365-pakket gebruiken in Claude Code?

Yes. De vaardigheidsmappen bevatten standaard agentvaardigheden. Voer wiqd plugin export --format claude-plugin uit om de Claude Code-indeling te genereren, of kopieer de vaardigheidsmappen naar .claude/skills/ in elk willekeurig Claude Code-project.

Heb ik een externe connector nodig?

No. Pakketten met alleen vaardigheden werken goed voor op prompts gebaseerde werkstromen. Connectors zijn alleen nodig wanneer uw vaardigheid livegegevens uit een extern systeem vereist.

Hoe verschillen invoegtoepassingsvaardigheden van ingebouwde vaardigheden?

Plugin-vaardigheden verschijnen met de bron "package" in de API. Ze kunnen ingebouwde vaardigheden met dezelfde naam niet overschrijven. Pakketten die door beheer zijn geïmplementeerd tonen isAdminDeployed: true.

Kunnen IT-beheerders bepalen welke invoegtoepassingen beschikbaar zijn?

Yes. Standaard M365-beheerelementen zijn van toepassing: lijsten voor toestaan/blokkeren op tenantniveau, door beheerders beheerde implementaties en nalevingsbeleid.

Wat gebeurt er als een invoegtoepassing wordt ingetrokken?

Bij de volgende synchronisatiecyclus worden de vaardigheden en connectors uit dit pakket verwijderd uit de sessie van de gebruiker. Actieve gesprekken worden niet onderbroken, maar nieuwe sessies hebben niet de mogelijkheden van het pakket.

Wat is het maximum aantal skills per pakket?

Twintig (20) vaardigheden (per ASKILL-M002). Voor de connectoren geldt een limiet van 10 per pakket.

Kunnen hulpprogramma's voor vaardigheden verwijzen naar connectortools uit hetzelfde pakket?

Ja, en dat zouden ze ook moeten doen. Geef de hulpprogramma's expliciet een naam in uw SKILL.md werkstroom (bijvoorbeeld 'Gebruik het search_case_law hulpprogramma om...'). De agent verbindt ze tijdens runtime.

Kunnen de hulpprogramma's van mijn invoegtoepassing bestanden accepteren vanuit de werkruimte Cowork?

Yes. Declareer de hulpprogrammaparameter met contentEncoding: base64, en Cowork zet het werkruimtebestand van de gebruiker om naar base64-inhoud voordat u uw server aanroept. Het model passeert bestandspaden, geen bestandsinhoud, zodat grote bestanden de context van het model niet gebruiken. Meer informatie over declaraties en limieten vindt u in Bestanden accepteren vanuit de Cowork-werkruimte.

Hoe genereer ik een deterministische GUID voor mijn pakket?

wiqd plugin create genereert en legt de app-id vast. Het conversiescript gebruikt UUID v5 (op basis van SHA-1) van de naam van uw plugin, dus als u de conversie twee keer uitvoert, wordt dezelfde GUID geproduceerd. Gebruik voor handmatig verpakken een GUID-generator. Zorg ervoor dat deze over verschillende versies heen stabiel blijft.

Op welke manifestversie moet ik me richten?

Gebruik 1.29 als u met wiqd bouwt, want dat zet de versie voor u vast. Bij 1.29 bevatten de agentConnectors[]-vermeldingen alleen een URL en mcpToolDescription is optioneel. De handmatig opgestelde voorbeelden in dit artikel gebruiken 1.28, waarin mcpToolDescription vereist is en het bestand waarnaar het verwijst zich in het ZIP-bestand moet bevinden. atk import openplugin maakt gebruik van UUID v5 (SHA-1 gebaseerd) op basis van de naam van uw invoegtoepassing. Als u de import tweemaal uitvoert, levert dit dezelfde GUID op. Om je eigen waarde in te stellen, geef --app-id op. Gebruik voor handmatig verpakken een GUID-generator. Zorg ervoor dat deze over verschillende versies heen stabiel blijft.

  • Laatst bijgewerkt om