Criar plug-ins para o Copilot Cowork

Microsoft Copilot Cowork dá suporte à extensibilidade por meio de pacotes de aplicativos do M365, o mesmo mecanismo de distribuição usado por aplicativos do Teams, agentes do Copilot e suplementos do Office. Você pode estender o Cowork com:

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

Ambos são empacotados juntos em um pacote de aplicativo padrão do Microsoft 365 e distribuídos pela Microsoft 365 App Store.

O que você criará

Um plugin do 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 habilidades usam o padrão aberto Agent Skills - o mesmo formato compatível com Claude Code, Visual Studio Code Copilot, Gemini CLI, Cursor, JetBrains Janie e 30+ outras ferramentas de IA.

Escolha seu ponto de partida

Importar um plug-in existente

Se você já tiver um plug-in de Código Claude ou Cursor com habilidades e servidores MCP, a CLI do Kit de Ferramentas de Agentes do Microsoft 365 (atk) importará 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 seu plug-in:

   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 .claude-plugin/plugin.json diretório (ou .cursor-plugin/plugin.json), .mcp.jsone skills/ do seu plug-in e, em seguida, cria um projeto do Agents Toolkit contendo appPackage/manifest.json, suas habilidades e ícones gerados.

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

Empacotar o resultado em um arquivo :.zip

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 é convertido

Os seguintes recursos do plug-in de Claude ainda não têm suporte no manifesto do Microsoft 365:

Opções de importação

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

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

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

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

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

A exportação grava um x-microsoft-365-agents-toolkit bloco no arquivo .plugin.json Esse bloco carrega o manifesto id, URLs de 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.

Herdado: script de conversão do PowerShell

Antes da atk importação de plug-in com suporte, a conversão usava um script do PowerShell somente Windows, que permanece disponível como o script de conversão:

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

Use atk import openplugin em vez disso. É multiplataforma, oferece suporte a fontes Cursor e Claude Code e pode exportar de volta para um diretório de plug-ins.

Criar um plug-in do zero

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

Etapa 1: Criar sua primeira habilidade

Uma habilidade é uma pasta que contém um SKILL.md arquivo. Crie a seguinte estrutura de pastas:

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

Escreva SKILL.md com frontmatter 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 de frontmatter

Campos obrigatórios:

Regras de nomenclatura (kebab-case): Use apenas caracteres alfanuméricos minúsculos e hifens. Não use hifens consecutivos e não use hifens à esquerda ou à direita.

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

Para habilidades complexas, mantenha o lean principal SKILL.md e mova o conteúdo detalhado para subdiretórios. Esses arquivos adicionais são arquivos 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 de arquivos complementares

Cada habilidade pode incluir até 20 arquivos complementares (qualquer arquivo diferente de SKILL.md). Os seguintes limites se aplicam por habilidade:

Regras de arquivos complementares

Os caminhos de arquivo complementares devem seguir estas regras:

• Use apenas caminhos relativos (sem caminhos absolutos)
• Nenhuma travessia de caminho (.. segmentos)
• Nenhuma barra invertida ou bytes nulos em nomes de arquivo
• Não há arquivos ocultos (nomes iniciados com .)
• Nenhum nome reservado do Windows (CON, PRN, COM1AUXNUL, , –COM9, –) LPT1LPT9
• O arquivo SKILL.md em si não conta como um arquivo complementar
• Os nomes de arquivo devem usar caracteres seguros: alfanuméricos, hifens, sublinhados, 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

Etapa 3: Adicionar um conector (opcional)

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

Requisitos do conector

Diretrizes de design de ferramentas

• Uma ferramenta por ação para APIs pequenas (menos de 15 operações): search_case_law, get_ruling, cite_precedent
• Pesquisar + executar 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 é o que o agente lê
• Saída estruturada: JSON de retorno 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 arquivos do espaço de trabalho do Cowork.

Descreva as ferramentas do conector (mcpToolDescription)

Cada remoteMcpServer conector deve incluir um mcpToolDescription objeto. Sua propriedade aninhada aponta para um arquivo JSON tool-description que você empacota dentro de seu .zip e referencia file por um caminho relativo da raiz do pacote. Se você omitir mcpToolDescription, o serviço de pacote rejeitará o upload 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 arquivo referenciado (por exemplo, tools/contoso-legal-tools.json) descreve as ferramentas que o conector expõe e devem estar presentes no pacote ZIP. Inclua-o junto com sua manifest.json pasta and skills/ ao empacotar o plug-in.

Tipos de autenticação com suporte

Para OAuthPluginVault e ApiKeyPluginVault, os referenceId pontos para as credenciais armazenadas no Microsoft Enterprise Token Store - os segredos nunca aparecem nos arquivos de manifesto ou de habilidade. O referenceId valor é a 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 a autenticação para plug-ins MCP e API em agentes no Microsoft 365 Copilot para obter detalhes de instalação e configuração.

Registro dinâmico de clientes

Se o servidor MCP der suporte a Registro dinâmico de clientes (DCR), você poderá omitir uma authentication configuração da definição do conector e Cowork criará automaticamente um cliente OAuth em nome do plug-in.

Você pode omitir o authorization objeto, mas ainda precisa incluir mcpToolDescription. Configure a URL do servidor MCP e a descrição da ferramenta, e o Cowork cuida do cliente OAuth:

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

Etapa 4: criar o manifesto

Criar manifest.json na raiz do 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 a ID de registro do OAuth e mcpToolDescription.file deve apontar para um arquivo JSON de descrição da ferramenta incluído no pacote ZIP.

Etapa 5: adicionar ícones

Crie dois ícones PNG:

Se você ainda não tiver ícones, atk import openplugin gera espaços reservados de cor sólida. Substitua-os antes do envio à loja.

Etapa 6: Pacote

Crie um arquivo ZIP com todo o conteúdo 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 tool-description referenciado por mcpToolDescription.file. Os pacotes somente de habilidades 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/

Usando o Kit de Ferramentas de Agentes do Microsoft 365

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

Etapa 7: teste

Para testar seu aplicativo, carregue seu pacote de aplicativos no Teams conforme descrito em Carregue seu aplicativo no Teams.

Para testes pessoais, faça o sideload do aplicativo usando a interface de linha de comando 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 sua conta corporativa do Microsoft 365:

   atk auth login
   

4. Entre em sua conta corporativa e instale o pacote do agente. Substitua o caminho do arquivo pelo local do 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. Salve essas IDs para uso posterior ao atualizar ou desinstalar.

Saiba mais na interface de linha de comando do Kit de Ferramentas de Agentes do Microsoft 365.

Etapa 8: Publicar em seu locatário

1. Abra o centro >de administração do M365Gerenciar aplicativosCarregar aplicativo> personalizado.
2. Selecione o botão de reticências (...) >Adicionar agente.
3. Carregue seu .zip pacote.
4. Abra Cowork>Fontes & Plug-ins de habilidades>. Seu plug-in aparece na seção Descobrir .

Etapa 9: Publicar para o público

Para plug-ins destinados à distribuição pública, envie seu plug-in para a Microsoft 365 App Store por meio do Partner Center. Saiba mais em Publicar agentes para o Microsoft 365 Copilot.

Testar um conector em um servidor MCP local

Os conectores exigem um HTTPS mcpServerUrl, portanto, para testar um servidor em execução em seu computador, você precisa expô-lo por meio de uma URL HTTPS pública. Os túneis de desenvolvimento fornecem uma retransmissão que encerra o TLS para você.

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

Solução de problemas

Padrões de embalagem

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

Somente habilidades (sem conector)

Ideal para fluxos de trabalho baseados em prompts, análise de documentos e assistência de redação.

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

Habilidades + 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

Somente conector (sem habilidades personalizadas)

Use esta opção para fontes de dados que as habilidades internas do Cowork já podem usar.

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 Claude importado ou plug-in de cursor

Use essa opção para plug-ins existentes de outras ferramentas de IA direcionadas ao Cowork.

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

Práticas recomendadas de criação de habilidades

Siga estas diretrizes para criar habilidades que são ativadas de forma confiável e produzem resultados consistentes.

Escreva descrições efetivas

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.

Escreva fluxos de trabalho eficazes

• Seja específico na descrição. Inclua frases de gatilho: "Use quando o usuário pedir..." Essa descrição é como o agente decide qual habilidade ativar.
• Estrutura como um fluxo de trabalho. Numere as etapas. Cada etapa deve mapear para uma ação concreta (ler um arquivo, chamar uma ferramenta, gerar saída).
• Defina o formato de saída. Mostre a estrutura exata de tabela, lista ou documento que os usuários devem esperar. Essa definição melhora drasticamente a consistência.
• Ferramentas de referência por nome. Se sua habilidade depender de ferramentas de conector, nomeie-as explicitamente: "Use a search_case_law ferramenta para..."
• Mantenha o SKILL.md principal enxuto. Mova o material de referência detalhada para o references/ subdiretório. O corpo da habilidade deve ser o fluxo de trabalho, não uma enciclopédia.

Evite erros comuns

• Não insira segredos em SKILL.md arquivos. Use agentConnectors com autenticação para credenciais de API.
• Não duplique habilidades internas. Verifique a lista de habilidades internas antes de criar.
• Não torne as habilidades muito 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 codifique caminhos de arquivo ou comandos do sistema. As habilidades devem ser portáteis entre ambientes.
• Não coloque tudo no SKILL.md. Se o corpo exceder ~3.000 palavras, mova o conteúdo detalhado para references/.

Regras de validação

Quando você envia seu pacote, a plataforma o valida em vários níveis. Corrija esses erros antes do envio para evitar a rejeição.

Validação no nível do manifesto

Validação no nível do pacote

Validação do conector

Validação de arquivo complementar

O portal valida arquivos complementares (materiais de referência, scripts e outros arquivos ao lado SKILL.md) no momento do upload e da sincronização:

Compatibilidade entre plataformas

As habilidades usam o padrão aberto Agent Skills. Os mesmos SKILL.md arquivos funcionam em várias ferramentas de IA:

Se você está desenvolvendo habilidades para o Claude Code e o Cowork, comece com a estrutura do plugin Claude Code - é o superconjunto:

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 do M365 quando estiver pronto para publicar na 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

Gerenciamento de anotação e confirmação de MCP

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

Campos disponíveis

Regras de confirmação

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

Todas as ferramentas devem ter as anotações de segurança especificadas. Ferramentas sem anotações são tratadas como destrutivas e exigem confirmação. Saiba mais na referência do 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) são controladas pela política interna do Cowork, independentemente das anotações.
• Para servidores MCP que não são da Microsoft, a confirmação controlada por anotação está sendo implementada progressivamente. A definição das dicas agora é compatível com versões anteriores, e os prompts de confirmação são exibidos à medida que a distribuição se expande sem a necessidade de alteração de desenvolvedor.

Aceitar arquivos do espaço de trabalho do Cowork

Uma ferramenta de conector pode usar um arquivo da sessão do Cowork do usuário como entrada - um documento que o usuário anexou, um anexo de email que o Cowork salvou ou um arquivo produzido por uma etapa anterior. Declare o parâmetro com o palavra-chave contentEncoding: base64 de esquema JSON padrão e Cowork lida com o resto. Nenhuma extensão de esquema específica da Microsoft é necessária, e a superfície de API do servidor não é alterada.

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

Declarar um parâmetro de arquivo

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 inputSchema.properties, o Cowork os substitui no esquema voltado para 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 sua 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, o Cowork ventila os arquivos resolvidos de volta para seus nomes de parâmetros originais na ordem da declaração.

Parâmetros de arquivo aninhados

Um parâmetro de arquivo aninhado dentro de um objeto ou de uma matriz de objetos também tem suporte e é tratado de forma diferente: em vez de ser recolhido, ele é reescrito em um lugar em uma cadeia de caracteres de caminho em seu próprio local. Isso preserva a associação entre um arquivo e seus campos irmãos, 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 o Cowork troca cada caminho por conteúdo base64 no local antes de encaminhar a chamada.

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

O que seu 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"
    }
  }
}

Seu servidor não precisa saber que 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 arquivos 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: base64 aumenta a carga em aproximadamente um terço sobre o 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 por tudo o que o usuário anexa. Valide o tipo de conteúdo do seu lado e retorne um erro de ferramenta claro se ele não for utilizável.
• Definir anotações. Uma ferramenta que recebe um arquivo e age sobre ele normalmente não é somente leitura, portanto, solicita confirmação. Consulte o gerenciamento de anotações e confirmações de MCP.
• Mantenha os parâmetros do arquivo embutidos. Um parâmetro por trás de um $ref, ou aninhado em mais de quatro níveis, não é reescrito. Seu servidor receberia uma cadeia de caracteres de caminho onde espera conteúdo.
• Declare no máximo um parâmetro de arquivo de matriz por ferramenta. Com dois ou mais, o Cowork não consegue dizer qual arquivo pertence a qual matriz e a chamada falha com um erro de ferramenta. Use uma matriz, ou vários parâmetros escalares, ou uma combinação de escalares e uma única matriz.
• Espere uma contagem exata em ferramentas apenas escalares. Se a ferramenta declarar apenas parâmetros de arquivo escalares, o número de arquivos que o agente passa deverá 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 excesso ou excesso de oferta.

Identificar o tráfego do Cowork para o seu servidor

Se o seu servidor MCP tem visibilidade da ferramenta por cliente, ou você deseja atribuir o tráfego que ele recebe, você pode reconhecer as solicitações que vêm do Cowork. O Cowork apresenta uma identidade de software estável em dois canais:

Corresponder no prefixo copilot-cowork

Corresponda ao prefixocopilot-cowork, sem diferenciar maiúsculas de minúsculas, em qualquer canal. Não correspondam à cadeia de caracteres exata copilot-cowork/1.0 ou a um .clientInfo.version A versão rastreia o contrato de identidade do cliente e espera-se que mude; Uma correspondência de prefixo mantém seu portão funcionando em colisões 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 escopos diferentes, portanto, escolha aquele que corresponde à forma como seu servidor impõe seu portão:

• O User-Agent cabeçalho está presente em todas as solicitações, incluindo tools/list e tools/call. Se você bloquear ou atribuir por solicitação, digite esse cabeçalho.
• clientInfo é enviada somente no initialize handshake. Se você fizer o gate por sessão no momento da conexão, poderá lê-lo lá, mas não será repetido em solicitações posteriores.

O que a identidade inclui e o que não inclui

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

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

Perguntas comuns

Posso usar as habilidades do pacote M365 no Claude Code?

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

Preciso de um conector remoto?

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

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

As habilidades de plug-in são exibidas com a fonte "package" na API. Elas não podem substituir as habilidades internas de mesmo nome. Administração pacotes implantados mostram isAdminDeployed: true.

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

Sim. Os controles de administrador do M365 Standard se aplicam: listas de permissões/bloqueios em nível de locatário, implantações gerenciadas pelo administrador e políticas de conformidade.

O que acontece se um plug-in for revogado?

No próximo ciclo de sincronização, as habilidades e conectores desse pacote são removidos da sessão do usuário. As conversas ativas não são interrompidas, mas as novas sessões não têm os recursos 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 habilidades podem fazer referência a ferramentas do conector do mesmo pacote?

Sim, e deveriam. Nomeie as ferramentas explicitamente em seu SKILL.md fluxo de trabalho (por exemplo, "Use a search_case_law ferramenta para..."). O agente os conecta em tempo de execução.

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

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

Como fazer gerar um GUID determinístico para meu pacote?

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

Conteúdo relacionado

• Visão geral Cowork
• Usar o Cowork
• Gerenciar o Cowork para sua organização
• Gerir plugins para o Cowork