Plug-ins bouwen voor Copilot Cowork

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: Op prompts gebaseerde workflows die Cowork nieuwe domeinexpertise leren, zoals financiële analyse, juridisch onderzoek of HR-workflows.
• Connectors: Externe servers 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.

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

Skills maken gebruik van de Agent Skills open standard, dezelfde indeling die wordt ondersteund door Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Jenie en 30+ andere AI-hulpprogramma's.

Kies je startpunt

Een bestaande invoegtoepassing importeren

Als u al een invoegtoepassing voor Claude Code of Cursor met vaardigheden en MCP-servers hebt, importeert de Microsoft 365 Agents Toolkit CLI (atk) deze rechtstreeks. De CLI draait op Windows, macOS en Linux.

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

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Controleer de versie:

   atk --version
   

3. Uw invoegtoepassing importeren:

   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 de plugin's .claude-plugin/plugin.json (of .cursor-plugin/plugin.json), .mcp.jsonen skills/ directory en vervolgens een Agents Toolkit-project met appPackage/manifest.jsonje vaardigheden, en gegenereerde pictogrammen.

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

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

Wat wordt geïmporteerd

Wat niet wordt geconverteerd

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

Opties voor importeren

Automatische detectie van verificatietype:

Als de automatische detectie niet overeenkomt met uw instellingen, overschrijft --default-auth-type u deze.

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

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

Verouderd: PowerShell-conversiescript

Vóór atk het importeren van ondersteunde plug-ins, werd bij de conversie een PowerShell-script gebruikt dat alleen voor Windows beschikbaar is, dat beschikbaar blijft als het conversiescript:

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

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

Een volledig nieuwe invoegtoepassing bouwen

Volg deze stappen om een volledig nieuw plug-inpakket te maken, beginnend met uw eerste vaardigheid en opbouwend tot een compleet, publiceerbaar pakket.

Stap 1: Uw eerste vaardigheid maken

Een vaardigheid 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 Markdown-hoofdtekst:

---
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 velden

Verplichte velden:

Naamgevingsregels (kebab-case): Gebruik alleen kleine letters, alfanumerieke tekens en afbreekstreepjes. Gebruik geen opeenvolgende afbreekstreepjes en geen voor- of volgstreepjes.

Stap 2: Referentiemateriaal toevoegen (optioneel)

Voor complexe vaardigheden houdt u de belangrijkste SKILL.md informatie en verplaatst u gedetailleerde inhoud naar submappen. Deze aanvullende bestanden zijn companion-bestanden. De vaardigheid laadt ze wanneer dat nodig is.

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 begeleidende bestanden

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

Regels voor begeleidende bestanden

Begeleidende bestandspaden moeten voldoen aan de volgende regels:

• Alleen relatieve paden gebruiken (geen absolute paden)
• Geen padtraversal (.. segmenten)
• Geen backslashes of null-bytes in bestandsnamen
• Geen verborgen bestanden (namen die beginnen met .)
• Geen gereserveerde namen in Windows (CON, , AUXPRN, NUL, COM1–COM9, LPT1–LPT9)
• Het bestand SKILL.md zelf telt niet als begeleidend bestand
• Bestandsnamen moeten veilige tekens bevatten: alfanumeriek, streepjes, onderstrepingstekens, punten, spaties en !

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

Verwijs expliciet 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. Vaardigheidspakketten werken goed voor op prompts gebaseerde workflows.

Vereisten voor connectors

Richtlijnen voor het ontwerpen van hulpprogramma's

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

Beschrijf de hulpprogramma's van uw connector (mcpToolDescription)

Elke remoteMcpServer verbindingslijn moet een mcpToolDescription object bevatten. De geneste file eigenschap verwijst naar een JSON-bestand met de beschrijving van het hulpprogramma dat u in uw .zip pakket verpakt en waarnaar u verwijst via een relatief pad vanaf de pakkethoofdmap. Als u dit weglaat mcpToolDescription, wordt de upload door de pakketdienst geweigerd met een HTTP 400-fout:

Vereiste eigenschappen ontbreken in object: mcpToolDescription.

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

In het bestand waarnaar wordt verwezen (bijvoorbeeld tools/contoso-legal-tools.json) worden de hulpprogramma's beschreven die de connector weergeeft en die aanwezig moeten zijn in het ZIP-pakket. Voeg deze toe aan je manifest.json en skills/ map wanneer je de plugin verpakt.

Ondersteunde verificatietypen

Voor OAuthPluginVault en ApiKeyPluginVault, de referenceId verwijzingen 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.

MCP-verificatie

Raadpleeg Verificatie configureren voor MCP- en API-invoegtoepassingen in agents in Microsoft 365 Copilot voor installatie- en configuratiedetails als u OAuth of ApiKey wilt gebruiken voor verificatie.

Dynamic Client Registration

Als uw MCP-server Dynamic Client Registration (DCR) ondersteunt, hoeft u geen authentication configuratie uit de connectordefinitie weg te laten en maakt Cowork automatisch een OAuth-client namens uw plugin.

U kunt het authorization object weglaten, maar u moet nog steeds .mcpToolDescription Configureer de URL van uw MCP-server en de beschrijving van de tool, en Cowork zorgt voor de OAuth-client:

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

Stap 4: Het manifest maken

Maak manifest.json in de hoofdmap van het pakket:

{
  "$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" }
  ]
}

Voeg de volgende onderdelen toe om een connector toe te voegen agentConnectors:

{
  "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 configuratie referenceId van de connector moet de OAuth-registratie-id staan en mcpToolDescription.file moet deze verwijzen naar een JSON-bestand met een beschrijving van het hulpprogramma dat is opgenomen in het ZIP-pakket.

Stap 5: Pictogrammen toevoegen

Maak twee PNG-pictogrammen:

Als u nog geen pictogrammen hebt, atk import openplugin genereert u tijdelijke aanduidingen met een effen kleur. Vervang ze voordat u ze bij de Store indient.

Stap 6: Pakket

Een ZIP-bestand maken met alle inhoud op hoofdniveau:

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

Als het pakket een agentConnectors vermelding bevat, voegt u het JSON-bestand met de hulpprogrammabeschrijving waarnaar wordt verwezen door mcpToolDescription.file. Vaardigheidspakketten hebben geen map nodig tools/ .

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.

Voor persoonlijke tests kunt u de app sideloaden met behulp van de opdrachtregelinterface van de Microsoft 365 Agents Toolkit:

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

   npm install -g @microsoft/m365agentstoolkit-cli
   

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

   atk --version
   

3. Verifiëren met uw Microsoft 365-werkaccount:

   atk auth login
   

4. Meld u aan bij uw werkaccount en installeer het agentpakket. Vervang het bestandspad door de locatie van het ZIP-pakket:

   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 bijwerkt of verwijdert.

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

Stap 8: Publiceren naar uw tenant

1. M365-beheercentrum> openenApps> beherenAangepaste app uploaden.
2. Selecteer de knop met de drie puntjes (...)>Agent toevoegen.
3. Upload uw .zip pakket.
4. Open Cowork>Bronnen &invoegtoepassingen voor vaardigheden>. Uw invoegtoepassing wordt weergegeven in de sectie Ontdekken .

Stap 9: publiceren voor het publiek

Voor invoegtoepassingen die zijn bedoeld voor openbare distributie, dient u uw invoegtoepassing in bij de Microsoft 365 App Store via het Partnercentrum. 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 wilt testen die op uw computer wordt uitgevoerd, moet u deze dus weergeven via een openbare HTTPS-URL. Dev-tunnels bieden een relais waarmee TLS voor je wordt afgesloten.

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

Problemen oplossen

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
│   └── my-connector.json
└── skills/
    ├── analysis-workflow/SKILL.md
    └── reporting-workflow/SKILL.md

Alleen Connector (geen aangepaste vaardigheden)

Gebruik deze optie voor gegevensbronnen die al kunnen worden gebruikt met de ingebouwde vaardigheden van Cowork.

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

Geïmporteerde Claude Code of Cursor-invoegtoepassing

Gebruik deze optie voor bestaande plug-ins van andere AI-hulpprogramma's die gericht zijn op Cowork.

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 maken van vaardigheden

Volg deze richtlijnen om vaardigheden te ontwikkelen die betrouwbaar activeren 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.

Effectieve werkstromen schrijven

• 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. De stappen nummeren. Elke stap moet worden toegewezen aan een concrete actie (een bestand lezen, een tool aanroepen, uitvoer genereren).
• Uitvoerformaat definiëren. Geef de exacte tabel-, lijst- of documentstructuur weer die gebruikers mogen verwachten. Deze definitie verbetert de consistentie drastisch.
• Verwijs naar hulpmiddelen op naam. Als uw vaardigheid afhankelijk is van verbindingslijngereedschappen, noem ze dan expliciet: "Gebruik het search_case_law hulpprogramma om..."
• Houd de hoofd SKILL.md slank. Verplaats gedetailleerd referentiemateriaal naar de references/ submap. Het vaardigheidslichaam moet de workflow zijn, geen encyclopedie.

Veelvoorkomende fouten vermijden

• Sluit geen geheimen inSKILL.md bestanden in. Gebruik agentConnectors met verificatie voor API-referenties.
• Dupliceer ingebouwde vaardigheden niet. Controleer de ingebouwde lijst met vaardigheden voordat u gaat bouwen.
• Maak vaardigheden niet te breed. "Alles doen met juridische documenten" is erger dan specifieke vaardigheden voor "contractanalyse", "clausule-extractie" en "juridisch onderzoek".
• Codeer bestandspaden of systeemopdrachten niet hardcodeer . Vaardigheden moeten overdraagbaar zijn in verschillende omgevingen.
• Zet niet alles in SKILL.md. Als uw lichaam 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.

Validatie op manifestniveau

Validatie op pakketniveau

Validatie van connector

Validatie van begeleidende bestanden

De portal valideert begeleidende bestanden (referentiemateriaal, scripts en andere bestanden SKILL.md) op het moment van uploaden en synchroniseren:

Compatibiliteit met meerdere platforms

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

Als je vaardigheden ontwikkelt voor zowel Claude Code als Cowork, begin dan met de Claude Code-plug-instructuur - het is de superset:

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)

Importeer het vervolgens in een M365-project wanneer u klaar bent om te publiceren naar de Microsoft 365 App Store:

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

MCP-annotatie- en bevestigingsbeheer

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

Beschikbare velden

Bevestigingsregels

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

Voor alle gereedschappen moeten veiligheidsannotaties zijn opgegeven. Gereedschappen zonder aantekeningen worden als destructief beschouwd en moeten worden bevestigd. 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": { ... }
}

Veilig lezen 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) worden afgesloten door het ingebouwde beleid van Cowork, ongeacht annotaties.
• Voor MCP-servers die niet van Microsoft zijn, wordt bevestiging op basis van aantekeningen geleidelijk uitgerold. Het instellen van de hints is nu compatibel met de toekomst 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 connector-tool kan een bestand uit de Cowork-sessie van de gebruiker als invoer gebruiken: een document dat de gebruiker heeft bijgevoegd, een e-mailbijlage die als Cowork is opgeslagen of een bestand dat een eerdere stap heeft geproduceerd. Declareer de parameter met het standaard JSON-schemasleutelwoord contentEncoding: base64 en Cowork handelt de rest af. Er is geen Microsoft-specifieke schema-extensie vereist en het API-oppervlak van uw server verandert niet.

Cowork lost het werkruimtebestand op en codeert het met base64 voordat je de server aanroept, zodat bestandsbytes nooit in de context van de agent terechtkomen. De agent ziet en verzendt alleen werkruimtebestandspaden.

Een bestandsparameter declareren

Een tekenreekseigenschap wordt contentEncoding: base64 herkend als een 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 matrix 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 matrix. Op het moment van aanroepen verspreidt Cowork de opgeloste bestanden terug naar uw oorspronkelijke parameternamen in declaratievolgorde.

Geneste bestandsparameters

Een bestandsparameter die is genest in een object of een matrix van objecten wordt ook ondersteund en wordt op verschillende manieren verwerkt: in plaats van samengevouwen te worden, wordt deze op zijn plaats herschreven in een padtekenreeks op zijn eigen locatie. Hierdoor blijft de koppeling tussen een bestand en de bijbehorende velden behouden, bijvoorbeeld één factuur per onkostenregel:

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

De agent vult line_items[].receipt een werkruimtepad en Cowork wisselt elk pad voor base64-inhoud voordat de oproep wordt doorgeschakeld.

Het nestelen wordt doorkruist tot een diepte van vier niveaus onder de top van inputSchema. $ref Pointers aren't follow - Definieer bestandsparameters inline in plaats van achter een $ref.

Wat uw server ontvangt

Uw server ontvangt een gewone tools/call met uw 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.

Limieten

Een aanroep die het aantal bestanden overschrijdt of een groottelimiet 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.

Aanbevelingen

• Beschrijf de parameter voor een menselijke lezer. De agent bepaalt aan de hand van de beschrijving welk bestand bij welke parameter hoort. Werkt bijvoorbeeld "The signed contract PDF to analyze" beter dan "file".
• Vermeld in de beschrijving van de parameter welke notaties u accepteert. Cowork passeert alles wat de gebruiker toevoegt. Valideer het inhoudstype aan jouw kant en retourneer een duidelijke hulpmiddelfout als deze niet bruikbaar is.
• Aantekeningen instellen. Een hulpprogramma dat een bestand ontvangt en hierop bewerkingen uitvoert, is normaal gesproken niet alleen-lezen, zodat om bevestiging wordt gevraagd. Zie MCP-annotatie- en bevestigingsbeheer.
• Houd bestandsparameters inline. Een parameter achter een $ref, of genest dieper dan vier niveaus, wordt niet herschreven. De server ontvangt een padtekenreeks waar inhoud wordt verwacht.
• Declareer ten hoogste één matrixbestandsparameter per hulpprogramma. Met twee of meer gegevens kan Cowork niet zien welk bestand in welke matrix thuishoort, en de aanroep mislukt met een hulpprogrammafout. Gebruik één matrix of meerdere scalaire parameters of een combinatie van scalaire waarden en één matrix.
• Verwacht een exacte telling voor scalaire tools. 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.

Identificeer het Cowork-verkeer naar uw server

Als uw MCP-server de zichtbaarheid van tools per client poort, of als u het verkeer dat het ontvangt wilt toeschrijven, kunt u verzoeken van Cowork herkennen. Cowork presenteert een stabiele software-identiteit op twee kanalen:

Overeenkomsten met het copilot-cowork voorvoegsel

Zorg dat het copilot-coworkvoorvoegsel (niet hoofdlettergevoelig) op een van beide kanalen overeenkomt. Records komen niet overeen met de exacte copilot-cowork/1.0 tekenreeks of een specifiek clientInfo.version. De versie volgt het client-identiteitscontract en zal naar verwachting veranderen; Een overeenkomst met voorvoegsels zorgt ervoor dat uw poort blijft werken bij oneffenheden in de versie.

# Correct: case-insensitive prefix match
copilot-cowork

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

Kies het juiste kanaal voor uw poort

De twee kanalen hebben verschillende bereiken, dus sleutel op het kanaal dat overeenkomt met hoe uw server zijn gate afdwingt:

• De User-Agent header is aanwezig op elke aanvraag, inclusief tools/list en tools/call. Als u poort of kenmerk per aanvraag, sleutel op deze header.
• clientInfo wordt alleen verzonden bij de initialize handdruk. Als je per sessie gate op het moment van verbinding, kun je dit daar lezen, maar het wordt niet herhaald bij latere aanvragen.

Wat de identiteit wel en niet omvat

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

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

Veelgestelde vragen

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

Ja. De vaardigheidsmappen bevatten standaard agentvaardigheden. Kopieer ze naar .claude/skills/ in een willekeurig Claude Code-project of voer ze uit atk export openplugin om het hele project terug te converteren naar een Claude Code-plug-in.

Heb ik een externe connector nodig?

Nee. Vaardigheidspakketten werken goed voor op prompts gebaseerde workflows. Connectors zijn alleen nodig wanneer voor uw vaardigheid live gegevens uit een extern systeem moeten worden opgeslagen.

Waarin verschillen plug-in-vaardigheden van ingebouwde vaardigheden?

Plugin-vaardigheden verschijnen met de bron "package" in de API. Ze kunnen ingebouwde vaardigheden met dezelfde naam niet vervangen. Door Beheer geïmplementeerde pakketten tonen isAdminDeployed: true.

Kunnen IT-beheerders bepalen welke plug-ins beschikbaar zijn?

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

Wat gebeurt er als een plugin 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 vaardigheden per pakket?

Twintig (20) vaardigheden (per ASKILL-M002). Voor connectors is de limiet 10 per pakket.

Kunnen 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 tools van mijn plugin bestanden uit de Cowork-werkruimte accepteren?

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

Hoe kan ik een deterministische GUID genereren voor mijn pakket?

atk import openplugin gebruikt UUID v5 (gebaseerd op SHA-1) van de naam van uw plugin. Als u de import tweemaal uitvoert, levert u dezelfde GUID op. Om je eigen in te stellen, passeer --app-idje . Gebruik een willekeurige GUID-generator voor handmatig verpakken. Zorg ervoor dat deze stabiel is in alle versies.

Verwante onderwerpen

• Cowork overzicht
• Gebruik Cowork
• Beheer Cowork voor uw organisatie
• Plug-ins voor Cowork beheren