Laajennusten luominen Copilot Cowork

Microsoft Copilot Cowork tukee laajennettavuutta M365-sovelluspakettien kautta – samaa jakelumekanismia, jota käyttävät Teams-sovellukset, Copilot-agentit ja Office-apuohjelmat. Voit laajentaa Cowork-ominaisuutta seuraavilla tavoilla:

• Taidot: Kehotepohjaiset työnkulut, jotka opettavat Coworkille uutta alan asiantuntemusta, kuten talousanalyysiä, juridista tutkimusta tai HR-työnkulkuja.
• Liittimet: Etäpalvelimet, jotka antavat Cowork käyttää ulkoisia tietolähteitä ja ohjelmointirajapintoja.

Molemmat on pakattu tavalliseen Microsoft 365 -sovelluspakettiin, ja niitä jaetaan Microsoft 365 App Storen kautta.

Mitä luot

Cowork-laajennus on .zip paketti, joka sisältää:

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

Taidot käyttävät Agent Skills -avointa standardia – samaa muotoa, jota tukevat Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie ja 30+ muuta tekoälytyökalua.

Valitse aloituspiste

Aiemmin luodun laajennuksen tuominen

Jos sinulla on jo Claude-koodi- tai kohdistinlaajennus, jossa on taitoja ja MCP-palvelimia, Microsoft 365 Agents Toolkit CLI (atk) tuo sen suoraan. CLI toimii Windowsissa, macOS:ssä ja Linuxissa.

1. Asenna CLI (edellyttää versiota 1.1.12 tai uudempaa):

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Tarkista versio:

   atk --version
   

3. Laajennuksen tuominen:

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

Komento lukee laajennuksen .claude-plugin/plugin.json (tai .cursor-plugin/plugin.json), .mcp.jsonja skills/ hakemiston ja luo sitten Agents Toolkit -projektin, joka sisältää appPackage/manifest.jsontaitosi ja luodut kuvakkeet.

Sinun on sisällytettävä --privacy-url ja koska --terms-url laajennuksen luetteloissa ei ole vastaavia kenttiä, ja Microsoft 365 -luettelo edellyttää molempia.

Pakkaa tulos ladattavaan .zip:

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

Mitä tuodaan?

Mitä ei muunneta

Seuraavia Claude-laajennuksen ominaisuuksia ei vielä tueta Microsoft 365:n luettelossa:

Tuomisen asetukset

Todennustyypin automaattinen tunnistus:

Jos automaattinen tunnistus ei vastaa asetuksiasi, voit ohittaa sen käyttämällä sitä --default-auth-type .

Vie takaisin laajennushakemistoon

Jos haluat siirtää Agents Toolkit -projektin takaisin laajennushakemistoon, esimerkiksi pitääksesi Claude Code -laajennuksen ja Cowork-paketin synkronoituina, käytä seuraaviaatk export openplugin:

atk export openplugin --path ./my-plugin-project \
  --output ./my-claude-plugin --manifest-kind claude-plugin

Vienti kirjoittaa x-microsoft-365-agents-toolkit lohkon luotuun plugin.json. Tämä lohko sisältää luettelon id, kehittäjien URL-osoitteet ja yhdistimen asetukset, joten myöhemmät atk import openplugin kiertot ilman tarvetta --privacy-url tai --terms-url uudelleen.

Vanha: PowerShell-muuntokomentosarja

Ennen atk tuettua laajennuksen tuontia muunnoksessa käytettiin vain Windowsin PowerShell-komentosarjaa, joka on edelleen käytettävissä muunnoskomentosarjana:

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

Käytä atk import openplugin sen sijaan. Se on monialustainen, tukee sekä Kursor- että Claude-koodilähteitä ja voi viedä takaisin laajennushakemistoon.

Laajennuksen luominen alusta alkaen

Seuraa näitä ohjeita luodaksesi laajennuspaketin alusta alkaen, alkaen ensimmäisestä osaamisestasi ja rakentaen kokonaiseen, julkaistavaan pakettiin.

Vaihe 1: Luo ensimmäinen osaamisalueesi

Osaamisalue on kansio, joka sisältää tiedoston SKILL.md . Luo seuraava kansiorakenne:

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

Kirjoita SKILL.md käyttämällä YAML-etuosaa ja Markdown-tekstiä:

---
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 frontmatter-kentät

Pakolliset kentät:

Nimeämissäännöt (kebab-case): Käytä vain pieniä aakkosnumeerisia merkkejä ja yhdysmerkkejä. Älä käytä peräkkäisiä tavuviivoja äläkä alussa tai lopussa olevia tavuviivoja.

Vaihe 2: Viitemateriaalien lisääminen (valinnainen)

Monimutkaisten taitojen osalta pidä pääsisältö SKILL.md vähäisenä ja siirrä yksityiskohtainen sisältö alihakemistoihin. Nämä lisätiedostot ovat kumppanitiedostoja. Taito lataa ne tarvittaessa.

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

Kumppanitiedostojen rajoitukset

Kukin osaamisalue voi sisältää enintään 20 kumppanitiedostoa (mikä tahansa muu tiedosto kuin SKILL.md). Seuraavat rajoitukset koskevat osaamisaluetta:

Kumppanitiedostojen säännöt

Kumppanitiedostopolkujen on noudatettava seuraavia sääntöjä:

• Käytä vain suhteellisia polkuja (ei absoluuttisia polkuja)
• Ei polun ylitystä (.. segmentit)
• Ei kenoviivoja tai tyhjäarvoisia tavuja tiedostonimissä
• Ei piilotettuja tiedostoja (nimet, jotka alkavat kirjaimilla .)
• Ei Windowsille varattuja nimiä (, , NUL, –COM1COM9, –LPT9) LPT1AUXPRNCON
• Itse tiedostoa SKILL.md ei lasketa kumppanitiedostoksi
• Tiedostonimissä on käytettävä turvallisia merkkejä: aakkosnumeerisia, tavuviivoja, alaviivoja, pisteitä, välilyöntejä ja !

Jotta kontekstiikkuna pysyy tehokkaana, järjestelmä lataa taitoja kolmessa tasossa:

Viittaa alihakemistoihin eksplisiittisesti SKILL.md , jotta agentti tietää niiden olemassaolon:

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

Vaihe 3: Yhdistimen lisääminen (valinnainen)

Jos laajennuksesi tarvitsee ulkoisten tietojen käyttöoikeuden, lisää MCP-etäpalvelin. Tämä vaihe on valinnainen. Vain osaamisalueet -paketit toimivat hyvin kehotepohjaisissa työnkuluissa.

Yhdistimen vaatimukset

Työkalujen suunnitteluohjeet

• Yksi työkalu toimintoa kohti pienille ohjelmointirajapinnoille (alle 15 toimintoa): search_case_law, get_ruling, cite_precedent
• Haku + suoritus suurille ohjelmointirajapinnoille (50+ toimintoa): search_actions + execute_action
• Kuvaavat nimet: get_bond_price not getData
• Monipuoliset syöterakenteet: Sisällytä kuvaus jokaiselle parametrille – agentti lukee tämän
• Rakenteellinen tulos: Palauta JSON, jonka agentti voi muotoilla käyttäjää varten
• Tiedoston syötteet: Jos haluat hyväksyä tiedoston käyttäjän työtilasta, määritä parametri .contentEncoding: base64 Lisätietoja on kohdassa Tiedostojen hyväksyminen Cowork-työtilasta.

Kuvaile yhdistimen työkaluja (mcpToolDescription)

Jokaisessa remoteMcpServer yhdistimessä on oltava mcpToolDescription objekti. Sen sisäkkäinen file ominaisuus osoittaa työkalua kuvaavaan JSON-tiedostoon, jonka pakkaat omaan tiedostoosi .zip ja johon viitataan paketin juuren suhteellisen polun avulla. Jos jätät sen mcpToolDescriptionpois, pakettipalvelu hylkää latauksen HTTP 400 -virheellä:

Pakolliset ominaisuudet puuttuvat objektista: mcpToolDescription.

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

Viitattu tiedosto (esimerkiksi tools/contoso-legal-tools.json) kuvaa yhdistimen sisältämät työkalut, ja niiden on oltava ZIP-paketissa. Sisällytä se ja-kansion skills/ viereenmanifest.json, kun pakkaat laajennuksen.

Tuetut todennustyypit

OAuthPluginVault For and ApiKeyPluginVaultosoittaa referenceId tunnistetietoihin tallennettuna Microsoft Enterprise Token Store - salaisuudet eivät koskaan näy luettelossa tai osaamisaluetiedostoissa. Arvo referenceId on OAuth-asiakkaan rekisteröintitunnus, jonka luot, kun rekisteröit OAuth-asiakkaan Agents Toolkitin avulla.

MCP-todennus

Jos haluat käyttää OAuth- tai ApiKey-todentamista todentamiseen, katso määritys- ja määritystiedot kohdasta MCP- ja API-laajennusten todennuksen määrittäminen Microsoft 365 Copilot agenteissa.

Dynaaminen asiakasrekisteröinti

Jos MCP-palvelimesi tukee Dynaaminen asiakasrekisteröinti (DCR), voit jättää määrityksen pois authentication yhdistimen määrityksestä, jolloin Cowork luo automaattisesti OAuth-asiakkaan laajennuksen puolesta.

Voit jättää objektin authorization pois, mutta sinun on silti sisällytettävä mcpToolDescription. Määritä MCP-palvelimen URL-osoite ja työkalun kuvaus, niin Cowork huolehtii OAuth-asiakkaasta:

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

Vaihe 4: Luettelon luominen

Luo manifest.json paketin pääkansioon:

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

Lisää yhdistin seuraavasti 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"
          }
        }
      }
    }
  ]
}

Yhdistimen määrityksessä referenceId tulee olla OAuth-rekisteröintitunnus, ja mcpToolDescription.file sen on viitattava työkalua kuvaavaan JSON-tiedostoon, joka sisältyy ZIP-pakettiin.

Vaihe 5: Kuvakkeiden lisääminen

Kahden PNG-kuvakkeen luominen:

Jos sinulla ei vielä ole kuvakkeita, atk import openplugin luo tasaisen väriset paikkamerkit. Vaihda ne ennen myymälän lähettämistä.

Vaihe 6: Pakkaus

Luo ZIP-tiedosto, jonka koko sisältö on juuritasolla:

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

Jos paketti sisältää merkinnänagentConnectors, sisällytä työkalun kuvauksen JSON-tiedosto, johon .mcpToolDescription.file Vain taitopaketit eivät tarvitse kansiota 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 -agenttien työkalujen käyttäminen

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

Vaihe 7: Testi

Testaa sovellusta lataamalla sovelluspaketti Teamsiin artikkelissa Sovelluksen lataaminen Teamsiin kuvatulla tavalla.

Henkilökohtaista testausta varten ohilataa sovellus käyttämällä Microsoft 365 Agents Toolkit -komentoriviliittymää:

1. Asennus @microsoft/m365agentstoolkit-cli alkaen npm:

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Tarkista asennus suorittamalla seuraava komento:

   atk --version
   

3. Todenna Microsoft 365 -työtililläsi:

   atk auth login
   

4. Kirjaudu sisään työpaikan tiliisi ja asenna agenttipaketti. Korvaa tiedostopolku ZIP-paketin sijainnilla:

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

   Onnistunut asennus palauttaa tulosteen, joka sisältää ja-merkin TitleIdAppId tilillesi.

5. Tallenna tunnukset myöhempää käyttöä varten, kun päivität tai poistat asennuksen.

Lisätietoja on Microsoft 365 Agents Toolkit -komentoriviliittymässä.

Vaihe 8: Julkaiseminen vuokraajalle

1. Avaa M365-hallintakeskus>Sovellusten> hallintaLataa mukautettu sovellus.
2. Valitse kolme pistettä -painike (...)>Lisää agentti.
3. Lataa paketti palvelimeen .zip .
4. Avaa Cowork>Sources & Skills>Plugins. Laajennuksesi näkyy Discover-osiossa .

Vaihe 9: Julkaiseminen yleisölle

Jos laajennus on tarkoitettu julkiseen jakeluun, lähetä laajennus Microsoft 365 App Store Kumppanikeskuksen kautta. Lisätietoja on Microsoft 365 Copilot:n julkaisuagenteissa.

Yhdistimen testaaminen paikallista MCP-palvelinta vastaan

Yhdistimet edellyttävät HTTPS-protokollaa mcpServerUrl, joten jos haluat testata tietokoneessasi toimivaa palvelinta, sinun on paljastettava se julkisen HTTPS-URL-osoitteen kautta. Kehitystunnelit tarjoavat välityksen, joka katkaisee TLS:n puolestasi.

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

Vianmääritys

Pakkausmallit

Valitse laajennukseen sopiva kuvio:

Vain osaamisalueet (ei yhdistintä)

Sopii parhaiten kehotepohjaisiin työnkulkuihin, asiakirja-analyysiin ja kirjoitusapuun.

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

Taidot + etäyhdistin

Soveltuu parhaiten tietojen analysointiin, ohjelmointirajapintaintegraatioihin ja yritysjärjestelmiin.

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

Vain yhdistin (ei mukautettuja osaamisalueita)

Käytä tätä vaihtoehtoa tietolähteille, joita Cowork:n sisäänrakennetut taidot voivat jo käyttää.

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

Tuotu Claude-koodi tai kohdistinlaajennus

Käytä tätä vaihtoehtoa muiden Coworkiin kohdistettujen tekoälytyökalujen aiemmin luoduille laajennuksille.

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

Taitojen luomisen parhaat käytännöt

Näiden ohjeiden avulla voit luoda taitoja, jotka aktivoivat luotettavasti ja tuottavat johdonmukaisia tuloksia.

Kirjoita tehokkaita kuvauksia

Kenttä description määrittää, milloin agentti aktivoi taitosi. Ole tarkka:

# 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.

Tehokkaiden työnkulkujen luominen

• Ole tarkka kuvauksessa. Sisällytä käynnistinlauseet: "Käytä, kun käyttäjä pyytää..." Tämä kuvaus kertoo, miten agentti päättää, minkä taidon se aktivoidaan.
• Rakenne työnkulkuna. Numeroi vaiheet. Kunkin vaiheen tulisi liittyä konkreettiseen toimintoon (tiedoston lukeminen, työkalun kutsuminen, tulosteen luominen).
• Määritä siirtomuoto. Näytä tarkka taulukon, luettelon tai asiakirjan rakenne, jota käyttäjät odottavat. Tämä määritelmä parantaa johdonmukaisuutta huomattavasti.
• Viitetyökalut nimen mukaan. Jos taitosi ovat riippuvaisia yhdistintyökaluista, anna niille selkeä nimi.search_case_law
• Pidä pää SKILL.md kevyenä. Yksityiskohtaisten viitemateriaalien siirtäminen references/ alihakemistoon. Osaamisen rungon pitäisi olla työnkulku, ei tietosanakirja.

Yleisten virheiden välttäminen

• Älä upota salaisuuksia tiedostoihinSKILL.md. Käytä agentConnectors ohjelmointirajapinnan tunnistetietojen todennuksella.
• Älä käytä sisäisiä taitoja. Tarkista valmis osaamisluettelo ennen luomista .
• Älä tee osaamisesta liian laajaa. "Tee kaikki juridisilla asiakirjoilla" on huonompi kuin tietyt taidot "sopimusanalyysiin", "lausekkeiden poimimiseen" ja "oikeudelliseen tutkimukseen".
• Älä koodaa tiedostopolkuja tai järjestelmäkomentoja pysyvästi. Taitojen tulisi olla siirrettäviä eri ympäristöissä.
• Älä laita kaikkea SKILL.md. Jos tekstissä on yli ~3 000 sanaa, siirrä yksityiskohtainen sisältö .references/

Kelpoisuussäännöt

Kun lähetät pakettisi, alusta tarkistaa sen useilla tasoilla. Korjaa nämä virheet ennen lähettämistä, jotta vältät hylkäämisen.

Luettelotason vahvistus

Pakettitason vahvistus

Yhdistimen vahvistus

Oheistiedoston tarkistus

Portaali tarkistaa kumppanitiedostot (viitemateriaalit, komentosarjat ja muut tiedostot rinnalla SKILL.md) lataamisen ja synkronoinnin yhteydessä:

Käyttöympäristöjen välinen yhteensopivuus

Taidot käyttävät Agent Skills -avointa standardia. Samat SKILL.md tiedostot toimivat useissa tekoälytyökaluissa:

Jos kehität taitoja sekä Claude Codea että Cowork varten, aloita Claude Code -laajennusrakenteesta - se on superjoukko:

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)

Tuo se M365-projektiin, kun olet valmis julkaisemaan sen 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-huomautusten ja vahvistusten hallinta

Copilot Cowork lukee MCP-vakio-objektin annotations työkaluissa, joista palvelin palaa, tools/listja päättää sen perusteella, tarvitseeko työkalukutsu käyttäjän vahvistuksen ja mikä tunniste näytetään kehotteessa.

Käytettävissä olevat kentät

Vahvistussäännöt

Vahvistus vaaditaan, jos readOnlyHint == false tai destructiveHint == true.

Kaikissa työkaluissa on oltava turvallisuusmerkinnät. Työkaluja, joissa ei ole merkintöjä, käsitellään tuhoisina ja ne edellyttävät vahvistusta. Lisätietoja on MCP-rakenneviittauksessa.

MCP-esimerkkejä

Tuhoisa toiminta, jossa on ystävällinen leima:

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

Turvallinen luku, joka suoritetaan automaattisesti:

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

Mitä on saatavilla nyt

• Microsoft-työkalut (Graph, Dataverse ja muut) on rajoitettu Cowork:n sisäänrakennetulla käytännöllä merkinnöistä riippumatta.
• Muissa kuin Microsoftin MCP-palvelimissa huomautuspohjainen vahvistus otetaan käyttöön asteittain. Vihjeiden määrittäminen nyt on yhteensopivaa eteenpäin, ja vahvistuskehotteet tulevat näkyviin, kun käyttöönotto laajenee ilman kehittäjän muutoksia.

Hyväksy tiedostoja Cowork-työtilalta

Yhdistämistyökalu voi ottaa syötteenä tiedoston käyttäjän Cowork-istunnosta – käyttäjän liittämän asiakirjan, Cowork tallensiman sähköpostiliitteen tai aiemmassa vaiheessa luodun tiedoston. Määritä parametri vakio-JSON Schema -avainsanalla contentEncoding: base64 ja Cowork käsittelee loput. Microsoft-mallilaajennusta ei tarvita, eikä palvelimen ohjelmointirajapinnan pinta-ala muutu.

Cowork ratkaisee työtilatiedoston ja base64-koodaa sen ennen palvelimen kutsumista, joten tiedostotavut eivät koskaan siirry agentin kontekstiin. Agentti vain näkee ja lähettää vain työtilan tiedostopolut.

Tiedostoparametrin määritteleminen

Merkkijonon ominaisuus, jolla contentEncoding: base64 tunnistetaan tiedostosyötteeksi:

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

Myös tällaisten merkkijonojen matriisi tunnistetaan työkaluille, jotka hyväksyvät useita tiedostoja:

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

Mitä agentti näkee

, Cowork korvaa ylimmällä tasolla inputSchema.propertiesmääritellyt tiedostoparametrit malliin suuntautuvassa rakenteessa yhdellä direct_attachment_file_paths matriisilla – samalla parametrilla, jota Cowork:n sisäänrakennetut työkalut käyttävät, joten agentti tietää jo, miten se täytetään. Yllä oleva rakenne esitetään edustajalle seuraavasti:

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

Jos työkalu määrittää useamman kuin yhden ylätason tiedostoparametrin, ne kaikki tiivistetään yhdeksi direct_attachment_file_paths matriisiksi. Puhelun aikana Cowork tuulettaa ratkaistut tiedostot takaisin alkuperäisiin parametrinimiisi määritysjärjestyksessä.

Sisäkkäiset tiedostoparametrit

Objektin tai objektimatriisin sisäkkäisiä tiedostoparametreja tuetaan myös, ja niitä käsitellään eri tavalla: kutistamisen sijaan se kirjoitetaan uudelleen polkumerkkijonoksi omaan sijaintiinsa. Tämä säilyttää yhteyden tiedoston ja sen rinnakkaiskenttien välillä, esimerkiksi yksi kuitti kuluriviä kohti:

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

Agentti täyttää line_items[].receipt työtilapolun, ja Cowork vaihtaa kunkin polun base64-sisältöön ennen puhelun välittämistä.

Pesintä kulkee neljän tason syvyyteen yläreunan alapuolelle.inputSchema $refOsoittimia ei seurata—tiedostoparametrien määrittäminen tekstissä, ei .$ref

Mitä palvelimesi vastaanottaa?

Palvelimesi vastaanottaa tavallisen tools/call parametrin alkuperäisillä parametrien nimillä täytettynä base64-koodatulla sisällöllä:

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

Palvelimen ei tarvitse tietää, että agentti käyttää polkupohjaista liittymää, eikä se vaikuta työkaluihin, jotka eivät määritä contentEncoding: base64 parametreja.

Rajoitukset

Kutsu, joka ylittää tiedostojen määrän tai kokorajoituksen, epäonnistuu työkaluvirheellä eikä se koskaan saavuta palvelintasi. Määritä ohjelmointirajapinta ja sen aikakatkaisut 150 MiB:n enimmäiskoko huomioiden: base64 kasvattaa tietoja noin kolmanneksella raakatiedostokokoon nähden, ja koodattu sisältö lähetetään JSON-RPC-pyyntötekstiin.

Suositukset

• Kuvaile parametria ihmislukijalle. Agentti määrittää kuvauksen perusteella, mikä tiedosto kuuluu mihinkin parametriin. Toimii esimerkiksi "The signed contract PDF to analyze" paremmin kuin "file".
• Ilmoita hyväksymäsi muodot parametrin kuvauksessa. Cowork kulkee käyttäjän liittämien asioiden läpi. Vahvista sisältötyyppi puolestasi ja palauta selkeä työkaluvirhe, jos se ei ole käyttökelpoinen.
• Määritä huomautukset. Työkalu, joka vastaanottaa tiedoston ja käsittelee sen, ei yleensä ole vain luku -tilassa, joten se pyytää vahvistusta. Katso MCP-huomautusten ja vahvistusten hallinta.
• Pidä tiedostoparametrit tekstissä. Parametria, joka on $refupotettu yli neljää tasoa syvemmälle, ei kirjoiteta uudelleen. Palvelimesi vastaanottaa polkumerkkijonon siellä, missä se odottaa sisältöä.
• Määritä enintään yksi matriisitiedostoparametri työkalua kohti. Kun niitä on vähintään kaksi, Cowork ei pysty erottamaan, mikä tiedosto kuuluu mihinkin matriisiin, ja kutsu epäonnistuu työkaluvirheellä. Käytä yhtä matriisia tai useita skalaariparametreja tai skalaarien ja yhden matriisin sekoitusta.
• Odota tarkkaa määrää pelkillä skalaarityökaluilla. Jos työkalu ilmoittaa vain skalaaritiedostoparametreja, agentin välittämien tiedostojen määrän on vastattava ilmoitettua määrää. Merkitse valinnaiset tiedostoparametrit selkeästi niiden kuvauksiin, jotta agentilla ei ole ali- tai ylitarjontaa.

Tunnista palvelimellesi tuleva Cowork-liikenne

Jos MCP-palvelimesi rajaa työkalun näkyvyyden asiakkaan mukaan tai haluat määrittää sen vastaanottaman liikenteen, voit tunnistaa Coworkista tulevat pyynnöt. Cowork esittelee vakaan ohjelmistoidentiteetin kahdella kanavalla:

Ehto on sama copilot-cowork

Vastaavat copilot-cowork kumman tahansa kanavan etuliitettä (kirjainkoko ei ole merkitsevä). Eivät vastaa tarkkaa copilot-cowork/1.0 merkkijonoa tai tiettyä clientInfo.version. Versio seuraa asiakkaan identiteettisopimusta ja sen odotetaan muuttuvan; Etuliitteen vastaavuus pitää porttisi toimintakunnossa myös versioiden välillä

# Correct: case-insensitive prefix match
copilot-cowork

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

Valitse oikea kanava portillesi

Kanavilla on eri vaikutusalueet, joten valitse se, joka vastaa sitä, miten palvelimesi valvoo porttiaan:

• Otsikko User-Agent on jokaisessa pyynnössä, mukaan lukien tools/list ja.tools/call Jos rajaat tai määrität pyyntökohtaisesti, näppäile tämä otsikko.
• clientInfo lähetetään vaininitialize kättelyssä. Jos määrität istuntokohtaisen rajauksen yhteysaikana, voit lukea sen sieltä, mutta se ei toistu myöhemmissä pyynnöissä.

Mitä käyttäjätiedot sisältävät ja eivät sisällä

Käyttäjätiedot antavat vain ohjelmistolle nimiä. Se on sama kaikille Cowork-käyttäjille ja yhteyksille, eikä sillä ole koskaan käyttäjätietoja. Käyttäjätiedot pysyvät yhdistimen todennusmäärityksen määrittämässä valtuutustyönkulussa.

Koska yhdistinkohtaista tarkennetta ei ole, et voi tällä hetkellä käyttää tätä käyttäjätietoa kertomaan, mikä yhdistin soitti puhelun, tai erottamaan julkaistu Microsoft-laajennus samaan URL-osoitteeseen osoittavasta ohiladatusta palvelimesta. Jos tarvitset tällaista erottelua, pakota se yhdistimen valtuutusmäärityksen kautta asiakkaan käyttäjätietojen sijaan.

Yleisiä kysymyksiä

Voinko käyttää M365-paketin taitoja Claude Codessa?

Kyllä. Taitokansiot sisältävät vakioagenttitaitoja. Kopioi ne .claude/skills/ mihin tahansa Claude Code -projektiin tai suorita atk export openplugin koko projektin muuntaminen takaisin Claude Code -laajennukseksi.

Tarvitsenko etäliittimen?

Ei. Vain osaamisalueet -paketit toimivat hyvin kehotepohjaisissa työnkuluissa. Yhdistimiä tarvitaan vain silloin, kun taitosi edellyttävät reaaliaikaista tietoa ulkoisesta järjestelmästä.

Miten laajennustaidot eroavat sisäänrakennetuista taidoista?

Laajennuksen taidot näkyvät lähteen "package" kanssa ohjelmointirajapinnassa. He eivät voi ohittaa samannimisiä valmiita osaamisalueita. Hallinta käyttöön ottamat paketit näkyvät isAdminDeployed: true.

Voivatko IT-järjestelmänvalvojat hallita, mitkä laajennukset ovat käytettävissä?

Kyllä. Standard M365 -hallintatoiminnot ovat käytössä: vuokraajatason sallittujen/estettyjen luettelot, järjestelmänvalvojan hallitsemat käyttöönotot ja yhteensopivuuskäytännöt.

Mitä tapahtuu, jos laajennus kumotaan?

Seuraavassa synkronointijaksossa kyseisen paketin osaamisalueet ja yhdistimet poistetaan käyttäjän istunnosta. Aktiivisia keskusteluja ei keskeytetä, mutta uusissa istunnoissa ei ole paketin ominaisuuksia.

Mikä on enimmäismäärä taitoja pakettia kohden?

Kaksikymmentä (20) taitoa (ASKILL-M002:n mukaan). Yhdistimien kohdalla raja on 10 pakettia kohden.

Voivatko saman paketin osaamisviitteet viitata yhdistintyökaluihin?

Kyllä, ja heidän pitäisi. Nimeä työkalut eksplisiittisesti työnkulussa SKILL.md (esimerkiksi "Työkalun search_case_law avulla..."). Agentti yhdistää ne suorituksen aikana.

Voivatko laajennukseni työkalut hyväksyä tiedostoja Cowork-työtilasta?

Kyllä. Määritä työkaluparametri komennolla contentEncoding: base64, niin Cowork ratkaisee käyttäjän työtilatiedoston base64-sisällöksi ennen palvelimen kutsumista. Malli välittää tiedostopolkuja, ei tiedoston sisältöä, joten suuret tiedostot eivät kuluta mallin kontekstia. Lisätietoja määrittelystä ja rajoituksista on kohdassa Tiedostojen hyväksyminen Cowork-työtilasta.

Ohjevalikko deterministinen GUID paketilleni?

atk import openplugin käyttää laajennuksen nimestä UUID v5:tä (SHA-1-pohjaista). Tuonnin suorittaminen kahdesti tuottaa saman GUID-tunnuksen. Voit määrittää oman --app-idmäärittämällä . Käytä manuaaliseen pakkaamiseen mitä tahansa GUID-muodostinta. Varmista, että se pysyy vakaana eri versioissa.

Aiheeseen liittyvä sisältö

• Cowork-yleiskatsaus
• Käytä Cowork-ominaisuutta
• Organisaatiosi Cowork-palvelun hallinta
• Hallitse Cowork-laajennuksia