Criar plugins para Copilot Cowork

Microsoft Copilot Cowork suporta a extensibilidade através dos Pacotes de Aplicações do M365, o mesmo mecanismo de distribuição utilizado pelas aplicações do Teams, agentes do Copilot e suplementos do Office. Pode prolongar Cowork com:

• Habilidades: fluxos de trabalho baseados em prompts que ensinam Cowork novos conhecimentos de domínio, como análise financeira, pesquisa jurídica ou fluxos de trabalho de RH.
• Conexões: servidores remotos que dão aos Cowork acesso a fontes de dados externas e APIs.

Ambos são empacotados em conjunto num pacote de aplicações padrão do Microsoft 365 e distribuídos através do Microsoft 365 App Store.

O que irá construir

Um plugin Cowork é um .zip pacote que contém:

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

As Capacidades utilizam o padrão aberto Agent Skills, o mesmo formato suportado pelo Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Junie e 30+ outras ferramentas de IA.

Escolha o seu ponto de partida

Importar um plug-in existente

Se já tiver um plug-in Claude Code ou Cursor com competências e servidores MCP, a CLI do Microsoft 365 Agents Toolkit (atk) importa-o diretamente. A CLI é executada no Windows, macOS e Linux.

1. Instale a CLI (requer a versão 1.1.12 ou posterior):

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Verifique a versão:

   atk --version
   

3. Importe o seu plugin:

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

O comando lê o diretório e o diretório do .claude-plugin/plugin.json plug-in (ou .cursor-plugin/plugin.json) .mcp.jsone skills/ , em seguida, cria um projeto do Agents Toolkit contendo appPackage/manifest.jsonsuas habilidades e ícones gerados.

Tem de incluir --privacy-url e --terms-url porque os manifestos do plug-in não têm campos equivalentes e o manifesto do Microsoft 365 requer ambos.

Compacte .zipo resultado em um :

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

O que é importado

O que não foi convertido

As seguintes funcionalidades de plug-in do Claude ainda não são suportadas no manifesto do Microsoft 365:

Importar opções

Detecção automática do tipo de autenticação:

Se a deteção automática não corresponder à sua configuração, utilize --default-auth-type para substituí-la.

Exportar de volta para um diretório de plug-ins

Para mover um projeto do Agents Toolkit de volta para um diretório de plug-ins — por exemplo, para manter um plug-in Claude Code e um pacote de Cowork sincronizados — useatk export openplugin:

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

Exportar grava um x-microsoft-365-agents-toolkit bloco no arquivo plugin.jsongerado . Esse bloco carrega o manifesto id, URLs do desenvolvedor e configurações de conector, portanto, uma viagem de ida e volta posterior atk import openplugin sem precisar --privacy-url ou --terms-url novamente.

Legado: script de conversão do PowerShell

Antes atk da importação de plug-ins suportada, a conversão utilizava um script do PowerShell apenas para Windows, que permanece disponível como script de conversão:

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

Utilize atk import openplugin em vez disso. É multiplataforma, suporta Cursor e fontes de código Claude e pode exportar de volta para um diretório de plugins.

Crie um plugin do zero

Siga estas etapas para criar um pacote de plug-in do zero, começando com sua primeira habilidade e construindo até um pacote completo e publicável.

Passo 1: Crie a sua primeira competência

Uma competência é uma pasta que contém um SKILL.md ficheiro. Crie a seguinte estrutura de pastas:

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

Escreva SKILL.md com a matéria frontal YAML e um corpo 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 campos Frontmatter

Campos obrigatórios:

Regras de nomenclatura (kebab-case): Utilize apenas carateres alfanuméricos minúsculos e hífenes. Não utilize hífenes consecutivos nem hífenes à esquerda ou à direita.

Passo 2: Adicionar materiais de referência (opcional)

Para habilidades complexas, mantenha a enxuta principal SKILL.md e mova o conteúdo detalhado para subdiretórios. Estes ficheiros adicionais são ficheiros complementares. A habilidade os carrega quando necessário.

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

Limites dos ficheiros complementares

Cada habilidade pode incluir até 20 arquivos complementares (qualquer arquivo diferente de SKILL.md). Aplicam-se os seguintes limites por competência:

Regras de ficheiros complementares

Os caminhos de ficheiros complementares têm de seguir estas regras:

• Utilizar apenas caminhos relativos (sem caminhos absolutos)
• Sem caminho transversal (.. segmentos)
• Sem barras invertidas ou bytes nulos em nomes de ficheiro
• Sem ficheiros ocultos (nomes a começar por .)
• Não existem nomes reservados do Windows (CON, PRN, AUX, NULCOM1, –COM9, –LPT9) LPT1
• O ficheiro SKILL.md em si não conta como um ficheiro complementar
• Os nomes de ficheiro têm de utilizar carateres seguros: alfanuméricos, hífenes, carateres de sublinhado, pontos, espaços e !

Para manter a janela de contexto eficiente, o sistema carrega habilidades em três camadas:

Faça referência aos subdiretórios explicitamente para SKILL.md que o agente saiba que eles existem:

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

Passo 3: adicionar um conector (opcional)

Se a extensão precisar de acesso a dados externos, adicione um servidor MCP remoto. Este passo é opcional. Os pacotes somente de habilidades funcionam bem para fluxos de trabalho baseados em prompts.

Requisitos do conector

Diretrizes de design de ferramentas

• Uma ferramenta por ação para pequenas APIs (menos de 15 operações): search_case_law, get_ruling, cite_precedent
• Pesquisa + execução para APIs grandes (50+ operações): search_actions + execute_action
• Nomes descritivos: get_bond_price não getData
• Esquemas de entrada avançados: inclua uma descrição para cada parâmetro — é isso que o agente lê
• Saída estruturada: retorna JSON que o agente pode formatar para o usuário
• Entradas de arquivo: Para aceitar um arquivo do espaço de trabalho do usuário, declare o parâmetro com contentEncoding: base64. Saiba mais em Aceitar ficheiros da área de trabalho do Cowork.

Descreva as ferramentas do conector (mcpToolDescription)

Cada remoteMcpServer conector deve incluir um mcpToolDescription objeto. Sua propriedade aninhada file aponta para um arquivo JSON de descrição de ferramenta que você empacota dentro do seu .zip e referencia por um caminho relativo da raiz do pacote. Se omitir mcpToolDescription, o serviço de pacote rejeita o carregamento com um erro HTTP 400:

As propriedades necessárias estão ausentes do objeto: mcpToolDescription.

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

O ficheiro referenciado (por exemplo, tools/contoso-legal-tools.json) descreve as ferramentas que o conector expõe e tem de estar presente no pacote ZIP. Inclua-o ao lado da sua manifest.json pasta e skills/ quando empacotar o plugin.

Tipos de autenticação suportados

Para OAuthPluginVault e ApiKeyPluginVault, os referenceId aponta para credenciais armazenadas no Microsoft Enterprise Token Store - segredos nunca aparecem no manifesto ou arquivos de habilidade. O referenceId valor é o ID de registro do cliente OAuth que você cria ao registrar um cliente OAuth com o Agents Toolkit.

Autenticação MCP

Para usar OAuth ou ApiKey para autenticação, consulte Configurar autenticação para plug-ins MCP e API em agentes no Microsoft 365 Copilot para obter detalhes de instalação e configuração.

Registo Dinâmico de Clientes

Se o seu servidor MCP suportar Registo Dinâmico de Clientes (DCR), pode omitir uma authentication configuração da sua definição de conector e Cowork cria automaticamente um cliente OAuth em nome do seu plug-in.

Pode omitir o authorization objeto, mas continua a precisar de incluir mcpToolDescription. Configure a URL do servidor MCP e a descrição da ferramenta e Cowork cuida do cliente OAuth:

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

Passo 4: Criar o manifesto

Crie manifest.json na raiz do seu pacote:

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

Para adicionar um conector, inclua 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"
          }
        }
      }
    }
  ]
}

Na configuração do conector, referenceId deve ser o ID de registro OAuth e mcpToolDescription.file deve apontar para um arquivo JSON de descrição da ferramenta que está incluído no pacote ZIP.

Passo 5: adicionar ícones

Crie dois ícones PNG:

Se ainda não tiver ícones, atk import openplugin gera marcadores de posição de cor sólida. Substitua-os antes da submissão à loja.

Passo 6: Pacote

Crie um arquivo ZIP com todos os conteúdos no nível raiz:

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

Se o pacote incluir uma agentConnectors entrada, inclua o arquivo JSON de descrição da ferramenta referenciado pelo mcpToolDescription.file. Os pacotes apenas de competências não precisam de uma tools/ pasta.

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/

Utilizar o Toolkit de Agentes do Microsoft 365

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

Passo 7: Teste

Para testar a sua aplicação, carregue o pacote de aplicação para o Teams, conforme descrito em Carregar a sua aplicação para o Teams.

Para testes pessoais, faça o sideload da aplicação utilizando a interface da linha de comandos do Microsoft 365 Agents Toolkit:

1. Instalar @microsoft/m365agentstoolkit-cli a partir de npm:

   npm install -g @microsoft/m365agentstoolkit-cli
   

2. Verifique a instalação executando:

   atk --version
   

3. Autentique-se com a sua conta profissional do Microsoft 365:

   atk auth login
   

4. Entre na sua conta profissional e instale o pacote do agente. Substitua o caminho do ficheiro pela localização do seu pacote ZIP:

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

   Uma instalação bem-sucedida retorna uma saída que inclui um TitleId e AppId para sua conta.

5. Guarde estes IDs para utilização posterior quando atualizar ou desinstalar.

Saiba mais na interface da linha de comandos do Microsoft 365 Agents Toolkit.

Passo 8: publicar no seu inquilino

1. Abrir o centro de administração do M365Gerir aplicações>Carregue a aplicação personalizada.>
2. Selecionar o botão de reticências (...) >Adicionar agente.
3. Carregue o seu .zip pacote.
4. Abra Cowork>Sources & Skills>Plugins. Seu plug-in aparece na seção Descobrir .

Passo 9: Publicar junto do público

Para plug-ins destinados a distribuição pública, submeta o seu plug-in para a App Store do Microsoft 365 através do Centro de Parceiros. Saiba mais em Publicar agentes para Microsoft 365 Copilot.

Testar um conector em relação a um servidor MCP local

Os conectores requerem um HTTPS mcpServerUrl, portanto, para testar um servidor em execução na sua máquina, você precisa expô-lo em uma URL HTTPS pública. Os túneis de desenvolvimento fornecem um relé que termina o TLS para você.

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

Resolução de Problemas

Padrões de embalagem

Escolha o padrão que se adapta à sua extensão:

Apenas competências (sem conexão)

Ideal para fluxos de trabalho baseados em pedidos, análise de documentos e assistência na escrita.

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

Competências + conector remoto

Ideal para análise de dados, integrações de API e sistemas empresariais.

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

Apenas conector (sem competências personalizadas)

Utilize esta opção para origens de dados que as competências incorporadas do Cowork já podem utilizar.

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

Código de Claude importado ou plug-in Cursor

Utilize esta opção para plug-ins existentes de outras ferramentas de IA que visam Cowork.

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

Melhores práticas de criação de competências

Siga estas diretrizes para criar habilidades que sejam ativadas de forma confiável e produzam resultados consistentes.

Escrever descrições eficazes

O description campo determina quando o agente ativa sua habilidade. Seja específico:

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

Escrever fluxos de trabalho eficazes

• Seja específico na descrição. Inclua frases de acionamento: "Utilizar quando o utilizador pedir..." Esta descrição é como o agente decide qual habilidade ativar.
• Estruturar como um fluxo de trabalho. Numere os passos. Cada etapa deve mapear para uma ação concreta (ler um arquivo, chamar uma ferramenta, gerar saída).
• Definir formato de saída. Mostre a tabela, lista ou estrutura de documento exata que os utilizadores devem esperar. Esta definição melhora drasticamente a consistência.
• Ferramentas de referência pelo nome. Se a sua competência depender das ferramentas de conexão, nomeie-as explicitamente: "Utilize a search_case_law ferramenta para..."
• Mantenha o SKILL.md principal enxuto. Mova material de referência detalhado para o references/ subdiretório. O corpo de habilidades deve ser o fluxo de trabalho, não uma enciclopédia.

Evite erros comuns

• Não incorpore segredos em SKILL.md ficheiros. Utilize agentConnectors com autenticação para credenciais de API.
• Não duplique competências incorporadas. Verifique a lista de competências incorporadas antes de criar.
• Não torne as competências demasiado amplas. "Fazer tudo com documentos legais" é pior do que habilidades específicas para "análise de contratos", "extração de cláusulas" e "pesquisa jurídica".
• Não faça hardcode caminhos de arquivo ou comandos do sistema. As competências devem ser portáteis em todos os ambientes.
• Não coloque tudo em SKILL.md. Se o seu corpo exceder ~3.000 palavras, mova o conteúdo detalhado para references/.

Regras de validação

Quando submete o seu pacote, a plataforma valida-o a vários níveis. Corrija estes erros antes da submissão para evitar a rejeição.

Validação ao nível do manifesto

Validação ao nível do pacote

Validação do conector

Validação de ficheiros complementares

O portal valida ficheiros complementares (materiais de referência, scripts e outros ficheiros SKILL.md) no momento do carregamento e sincronização:

Compatibilidade entre plataformas

As habilidades usam o padrão aberto Habilidades do agente. Os mesmos SKILL.md ficheiros funcionam em várias ferramentas de IA:

Se você está desenvolvendo habilidades para Claude Code e Cowork, comece com a estrutura do plugin Claude Code - é o 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)

Em seguida, importe-o para um projeto M365 quando estiver pronto para publicar no 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

Gestão de anotações e confirmações MCP

Copilot Cowork lê o objeto MCP annotations padrão em ferramentas das quais seu servidor retorna e o usa para decidir se uma chamada de ferramenta precisa da confirmação do tools/listusuário e qual rótulo mostrar no prompt.

Campos disponíveis

Regras de confirmação

É necessária confirmação se readOnlyHint == false ou destructiveHint == true.

Todas as ferramentas têm de ter anotações de segurança especificadas. As ferramentas sem anotações são tratadas como destrutivas e requerem confirmação. Saiba mais na referência de esquema MCP.

Exemplos de MCP

Uma ação destrutiva com um rótulo amigável:

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

Uma leitura segura que é executada automaticamente:

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

O que está disponível agora

• As ferramentas da Microsoft (Graph, Dataverse e outras) estão limitadas pela política incorporada do Cowork, independentemente das anotações.
• Para servidores MCP que não sejam da Microsoft, a confirmação orientada por anotação está sendo implementada progressivamente. Definir as sugestões agora é compatível com o futuro e os avisos de confirmação surgem à medida que a implementação se expande, sem que seja necessária qualquer alteração do programador.

Aceitar ficheiros a partir da área de trabalho do Cowork

Uma ferramenta de conexão pode tomar um arquivo da sessão de Cowork do usuário como entrada: um documento anexado pelo usuário, um anexo de e-mail Cowork salvo ou um arquivo produzido por uma etapa anterior. Declare o parâmetro com a palavra-chave contentEncoding: base64 padrão JSON Schema e Cowork lida com o resto. Nenhuma extensão de esquema específica da Microsoft é necessária, e a superfície da API do seu servidor não muda.

Cowork resolve o arquivo de espaço de trabalho e o codifica base64 antes de chamar o servidor, para que os bytes de arquivo nunca entrem no contexto do agente. O agente só vê e emite caminhos de ficheiros da área de trabalho.

Declarar um parâmetro de ficheiro

Uma propriedade de cadeia de caracteres com contentEncoding: base64 é reconhecida como uma entrada de arquivo:

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

Uma matriz dessas cadeias de caracteres também é reconhecida, para ferramentas que aceitam vários arquivos:

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

O que o agente vê

Para parâmetros de arquivo declarados no nível superior do , Cowork os substitui no esquema voltado inputSchema.propertiespara o modelo por uma única direct_attachment_file_paths matriz — o mesmo parâmetro que as ferramentas internas do Cowork usam, para que o agente já saiba como preenchê-lo. O esquema acima é apresentado ao agente como:

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

Se a ferramenta declarar mais de um parâmetro de arquivo de nível superior, todos eles serão recolhidos nessa única direct_attachment_file_paths matriz. No momento da chamada, Cowork os arquivos resolvidos voltam para os nomes dos parâmetros originais na ordem da declaração.

Parâmetros de ficheiro aninhados

Um parâmetro de arquivo aninhado dentro de um objeto ou uma matriz de objetos também é suportado e é tratado de forma diferente: em vez de ser recolhido, ele é reescrito em uma cadeia de caracteres de caminho em seu próprio local. Isto preserva a associação entre um ficheiro e os campos subordinados associados, por exemplo, um recibo por linha de despesa:

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

O agente preenche line_items[].receipt com um caminho de espaço de trabalho e Cowork troca cada caminho por conteúdo base64 no lugar antes de encaminhar a chamada.

O aninhamento é percorrido até uma profundidade de quatro níveis abaixo do topo do inputSchema. $ref Os ponteiros não são seguidos — defina parâmetros de arquivo embutidos em vez de atrás de um $refarquivo .

O que o servidor recebe

Seu servidor recebe um ordinário tools/call com seus nomes de parâmetros originais preenchidos com conteúdo codificado em base64:

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

O servidor não precisa saber se o agente usou uma interface baseada em caminho e as ferramentas que não declaram contentEncoding: base64 parâmetros não são afetadas.

Limites

Uma chamada que excede a contagem de ficheiros ou um limite de tamanho falha com um erro de ferramenta e nunca chega ao servidor. Dimensione sua API e seus tempos limite com o teto de 150 MiB em mente: o base64 infla a carga útil em aproximadamente um terço em relação ao tamanho do arquivo bruto, e o conteúdo codificado é enviado no corpo da solicitação JSON-RPC.

Recomendações

• Descreva o parâmetro para um leitor humano. O agente usa a descrição para decidir qual arquivo pertence a qual parâmetro. Por exemplo, "The signed contract PDF to analyze" funciona melhor do que "file".
• Indique os formatos aceitos na descrição do parâmetro. Cowork passa pelo que o usuário anexar. Valide o tipo de conteúdo do seu lado e devolva um erro de ferramenta claro se não for utilizável.
• Definir anotações. Uma ferramenta que recebe um ficheiro e atua sobre o mesmo normalmente não é só de leitura, pelo que pede uma confirmação. Consulte Gestão de anotações e confirmações MCP.
• Mantenha os parâmetros do ficheiro em linha. Um parâmetro atrás de um $ref, ou aninhado com profundidade superior a quatro níveis, não é reescrito. O servidor receberia uma cadeia de carateres de caminho onde espera conteúdo.
• Declare no máximo um parâmetro de arquivo de matriz por ferramenta. Com dois ou mais, Cowork não consegue saber a que ficheiro pertence a que matriz e a chamada falha com um erro de ferramenta. Utilize uma matriz, vários parâmetros escalares ou uma combinação de escalares e uma única matriz.
• Espere uma contagem exata de ferramentas apenas escalares. Se a ferramenta declarar apenas parâmetros de arquivo escalar, o número de arquivos que o agente passa deve corresponder ao número declarado. Marque os parâmetros de arquivo opcionais claramente em suas descrições para que o agente não forneça pouco ou em excesso.

Identificar Cowork tráfego para o servidor

Se o servidor MCP gates a visibilidade da ferramenta por cliente ou se pretender atribuir o tráfego que recebe, pode reconhecer pedidos provenientes de Cowork. Cowork apresenta uma identidade de software estável em dois canais:

Corresponder no prefixo copilot-cowork

Corresponda ao prefixo, não sensível às maiúsculas copilot-cowork e minúsculas, em qualquer um dos canais. Não correspondam à cadeia exata copilot-cowork/1.0 ou a um clientInfo.versionficheiro . A versão rastreia o contrato de identidade do cliente e espera-se que mude; Uma correspondência de prefixos mantém seu portão funcionando em todos os solavancos de versão.

# Correct: case-insensitive prefix match
copilot-cowork

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

Escolha o canal certo para o seu portão

Os dois canais têm âmbitos diferentes, por isso é fundamental naquele que corresponde à forma como o servidor impõe a sua porta:

• O User-Agent cabeçalho está presente em todos os pedidos, incluindo tools/list e tools/call. Se você porta ou atributo por solicitação, chave neste cabeçalho.
• clientInfo é enviado apenas no aperto de initialize mão. Se você cancelar por sessão no momento da conexão, você pode lê-lo lá, mas não será repetido em solicitações posteriores.

O que a identidade inclui e não inclui

A identidade apenas nomeia o software . É o mesmo para todos os Cowork usuários e conexão, e nunca carrega a identidade do usuário. A identidade do utilizador permanece no fluxo de autorização definido pela configuração de autenticação do conector.

Como não há qualificador por conector, atualmente não é possível usar essa identidade para saber qual conector fez uma chamada ou para separar um plug-in da Microsoft publicado de um servidor sideloaded apontado para a mesma URL. Se precisar dessa distinção, impeça-a através da configuração de autorização do conector em vez da identidade do cliente.

Perguntas comuns

Posso usar habilidades do pacote M365 no Claude Code?

Sim. As pastas de habilidades contêm Habilidades padrão do agente. Copie-os em .claude/skills/ qualquer projeto Claude Code ou execute-os atk export openplugin para converter todo o projeto em um plug-in Claude Code.

Preciso de um conector remoto?

Não. Os pacotes somente de habilidades funcionam bem para fluxos de trabalho baseados em prompts. Os conectores só são necessários quando a sua competência requer dados dinâmicos de um sistema externo.

Como as habilidades de plug-in são diferentes das habilidades integradas?

As habilidades de plug-in aparecem com o código-fonte "package" na API. Não podem substituir as competências incorporadas com o mesmo nome. Administração pacotes não implantados mostram isAdminDeployed: true.

Os administradores de TI podem controlar quais plug-ins estão disponíveis?

Sim. Aplicam-se controlos de administrador padrão do M365: listas de permissões/bloqueios ao nível do inquilino, implementações geridas pelo administrador e políticas de conformidade.

O que acontece se um plug-in for revogado?

No ciclo de sincronização seguinte, as competências e os conectores desse pacote são removidos da sessão do utilizador. As conversações ativas não são interrompidas, mas as novas sessões não têm as funcionalidades do pacote.

Qual é o número máximo de habilidades por pacote?

Vinte (20) habilidades (por ASKILL-M002). Para conectores, o limite é de 10 por pacote.

As competências podem referenciar ferramentas de conexão do mesmo pacote?

Sim, e deveriam. Atribua um nome explícito às ferramentas no fluxo SKILL.md de trabalho (por exemplo, "Utilizar a search_case_law ferramenta para..."). O agente liga-os em tempo de execução.

As ferramentas do meu plugin podem aceitar ficheiros do espaço de trabalho Cowork?

Sim. Declare o parâmetro tool com contentEncoding: base64, e Cowork resolve o arquivo de espaço de trabalho do usuário para o conteúdo base64 antes de chamar o servidor. O modelo passa caminhos de ficheiro, não conteúdo de ficheiro, pelo que os ficheiros grandes não consomem o contexto do modelo. Para obter detalhes e limites da declaração, saiba mais em Aceitar ficheiros a partir da área de trabalho Cowork.

Como devo proceder para gerar um GUID determinístico para o meu pacote?

atk import openplugin usa UUID v5 (baseado em SHA-1) do nome do seu plugin. Executar a importação duas vezes produz o mesmo GUID. Para definir o seu, passe --app-id. Para empacotamento manual, use qualquer gerador de GUID. Certifique-se de que o mantém estável em todas as versões.

Conteúdos relacionados

• Cowork visão geral
• Utilizar Cowork
• Gerir Cowork para a sua organização
• Gerir plug-ins para Cowork