0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

添付ファイルを業務APIへ渡す:Coworkのファイル入力連携とbase64・承認・容量制限の注意点

0
Posted at

執筆している2026年11月13日時点の情報です。Cowork は更新が速い機能のため、最新情報は必ず公開情報(本記事末尾の参考リンク)もあわせてご確認ください。

1. 添付ファイルを、専用の業務APIでも処理したい

Coworkにファイルを添付して内容を整理するだけでなく、組織で利用している専用の処理サービスにつなげたい場面があります。

  • 契約書を条項抽出APIに渡す
  • 画像を専用の解析サービスで処理する
  • 添付ファイルを、別の業務システムのレコードに関連付ける

このとき、AIに「ファイルをbase64にして、APIに渡して」と指示すれば十分なのでしょうか。

Coworkの公式開発ガイドは、その方法を避けるように説明しています。代わりに、ツールの入力スキーマでファイル用のパラメーターを宣言します。

この記事のテーマは、モデルにはファイルのパスを扱わせ、送信前のファイル解決とbase64変換はCoworkに任せる仕組みです。Officeファイルを直接編集する機能とは別の話です。

本稿は公開資料に基づく解説です。MCPサーバーへの接続、ファイル送信、承認、上限値の境界試験は実施していません。

参考情報

2. この記事で分かること

  • contentEncoding: base64でファイル入力を宣言する方法
  • モデルが見る入力と、サーバーが受け取る入力の違い
  • 複数ファイルと、入れ子のパラメーターの注意点
  • 送信先、サイズ上限、API側の検証を確認する観点

対象は、CoworkのコネクターやMCPツールを開発する担当者です。この記事だけで稼働するMCPサーバーを構築するものではなく、既存ツールへファイル入力を追加するときの契約を説明します。

3. 公式情報で確認できたこと

更新履歴では、ワークスペースのファイルをプラグインのツール入力に使える機能は2026年8月の拡張として掲載されています。11月の新機能とは扱いません。

11月11日更新の開発ガイドでは、次の仕組みが詳しく説明されています。

項目 内容
対象のファイル 利用者の添付、Coworkが保存したメール添付、前の処理で生成されたファイル
宣言 文字列パラメーターにcontentEncoding: base64を指定
モデルの役割 ワークスペースのファイルパスを指定する
Coworkの役割 呼び出し前にファイルを解決し、base64へ変換する
サーバーの入力 元のパラメーター名に入ったbase64文字列

Microsoft専用のJSON Schema拡張を追加する必要はないと説明されています。ただし、他のMCPクライアントでも同じファイル解決が行われるとは限りません。本稿はCoworkでの挙動です。

参考情報

4. AIにbase64文字列を作らせない

base64は、バイナリーの内容を文字列として表現する方式です。暗号化ではありません。

モデル自身に巨大なbase64文字列を生成・転記させると、コンテキストを消費し、内容が正確に再現されることにも依存します。公式ガイドは、小さなテストファイルで動いても実際のファイルでは失敗し得ると注意しています。

ファイル入力の仕組みでは、次のように役割を分けます。

利用者がファイルを指定
        |
モデルがワークスペースのパスを指定
        |
Coworkがファイルを解決してbase64へ変換
        |
コネクターツールへ実際の内容を送信
        |
サーバーがデコード・形式検証・処理を実行

base64から元のバイト列へ戻す処理はデコードであり、暗号の復号ではありません。

この入力経路のファイルバイト列はモデルのコンテキストに入らないと説明されています。ただし、別の処理でファイルを読んだ場合や、APIの結果に抽出した本文を返した場合まで、モデルに内容が渡らないという意味ではありません。

また、ファイルが外部サービスに送信されること自体は変わりません。モデルの入力容量を節約する仕組みと、情報の送信可否は別に判断します。

参考情報

5. 仮想例:契約書から確認事項を抽出する

架空の契約確認業務を想定します。実在する契約書や実行済みの結果ではありません。

承認された条項抽出サービスに文書を渡し、契約期間、解約条件、更新条件を抽出します。その結果をCoworkが確認用の一覧に整理する構成です。

添付した架空の契約書を、承認済みの条項抽出ツールで処理してください。
契約期間、解約条件、更新条件を一覧にしてください。
抽出できない項目は「要確認」とし、推測で埋めないでください。
外部ツールへ渡す対象ファイルと処理内容を、実行前に確認できるようにしてください。
メール送信や契約管理システムの更新は行わないでください。

これは依頼文の設計例です。承認画面の表示をプロンプトだけで保証するものではありません。ツールの安全性注釈、Coworkのポリシー、利用環境を含めて確認します。

抽出結果も法的な判断や正確性を保証するものではなく、担当者が原文と照合する前提です。

6. ファイル入力を宣言する

以下は、ファイルを受け取るMCPツールの定義例です。公開資料に基づく未実行のサンプルであり、認証やサーバー実装は含みません。

{
  "name": "extract_contract_terms",
  "description": "Extract key terms from a contract PDF.",
  "annotations": {
    "title": "Extract Contract Terms",
    "readOnlyHint": false,
    "destructiveHint": false
  },
  "inputSchema": {
    "type": "object",
    "properties": {
      "document": {
        "type": "string",
        "contentEncoding": "base64",
        "description": "The contract PDF selected by the user."
      },
      "language": {
        "type": "string",
        "description": "The requested output language."
      }
    },
    "required": ["document", "language"]
  }
}

この例では、ファイルの送信・処理を伴う操作としてreadOnlyHint: falseを設定しています。実際の注釈はツールの挙動に合わせ、単に承認を減らす目的で読み取り専用としないでください。

トップレベルのファイル入力は、モデル向けのスキーマではdirect_attachment_file_pathsという配列に置き換えられます。サーバーは、その名前のパラメーターを受け取るように変更する必要はありません。

サーバーに届く元のdocumentには、Coworkが解決したファイルのbase64文字列が入ります。サーバー側では、デコード、実際の形式、容量、処理可能な文書かを検証し、失敗は明示的なツールエラーとして返します。

複数ファイルと入れ子

複数ファイルには、次のような配列も使えます。

{
  "type": "array",
  "items": {
    "type": "string",
    "contentEncoding": "base64"
  },
  "description": "The PDF files selected for comparison."
}

配列型のファイルパラメーターは、ツールあたり最大一つです。トップレベルのファイル入力を複数宣言すると、モデル向けには一つの配列へまとめられ、元の宣言順で各パラメーターに振り分けられます。

一方、オブジェクトやオブジェクト配列の中にファイル入力を置く場合は、その位置でパスへ置き換えられます。同じレコードの番号や説明と、ファイルの対応関係を維持するためです。

参考情報

7. 接続と承認は、ファイル入力とは別に設計する

ファイルの宣言を追加しても、コネクターの認証や権限設定が不要になるわけではありません。

利用者向けガイドでは、接続先に初めてアクセスするときのサインイン・同意と、ファイルを必要とするツールを実行する前の承認が説明されています。

一方、開発ガイドでは、非MicrosoftのMCPサーバーに対する安全性注釈に基づく承認は段階的に展開中とされています。ツール定義を整えたことだけで、すべての環境で同じ承認画面になるとは断定できません。

管理者と開発者が確認したいのは次の点です。

  • 送信先サービスと、その保存・削除・ログ記録のルール
  • 本人の認証、必要権限、接続の取り消し方法
  • 実行前に対象ファイルと処理内容を確認できるか
  • Coworkの利用設定・従量課金と、接続先APIの費用
  • 入力や処理が不正な場合に、成功したような結果を返さないか

base64文字列をそのままログに残すと、元ファイルを復元できる情報を保存することになります。必要以上の本文・添付内容を記録しない設計を検討してください。

参考情報

8. 上限と、最初に試したい失敗ケース

公開されているファイル入力の主な制限は次のとおりです。Coworkへの一般的な添付上限や、接続先APIの上限とは区別してください。

項目 制限
ツール呼び出しあたりのファイル数 最大8
1ファイルの容量 最大150 MiB
1回の呼び出しの合計容量 最大150 MiB
配列型ファイルパラメーター ツールあたり最大1
入れ子 inputSchemaのトップから最大4レベル
$ref 参照先をたどらないため、ファイル入力はインラインで宣言

150 MiBのファイルを8個送れるわけではありません。合計の上限も150 MiBです。

上限を超える呼び出しはツールエラーとなり、サーバーには届かないと説明されています。また、base64で送るとデータ量は元の**約4/3倍(約33%増)**になります。APIのリクエスト上限やタイムアウトは、エンコード後のJSON本文も考慮します。

最初の検証では、例えば次のケースを用意するとよいでしょう。

ケース 確認すること
小さな対応形式のファイル 意図したファイルが届き、デコード後の内容が一致するか
非対応形式や破損ファイル APIが理由付きのエラーを返すか
容量または個数の超過 Cowork側のエラーになり、サーバーが処理を始めないか
複数の単一ファイル入力 ファイル数と各項目への割り当てが正しいか
$refの背後に置いた入力 パス文字列をファイル内容と誤認しないか
承認の取り消し 意図しない送信・処理が発生しないか

この表は検証案であり、結果ではありません。接続先APIが150 MiBまで扱えることや、各テナントの展開状況は未確認です。

参考情報

9. まとめ

Coworkのファイル入力連携では、ツールが受け取るファイルをスキーマで宣言し、Coworkが内容の解決とbase64変換を担当します。

モデルに巨大な文字列の転記を任せず、専用の処理サービスにつなげられる点が重要です。ただし、ファイルが送信される先と、その後の扱いは別途確認が必要です。

最初は、小さな架空のファイルを使い、正しいファイルが届くこと、失敗が明示されること、結果を原文と照合できることから確かめてください。

参考リンク

資料の更新日は、機能の提供開始日や全テナントへの展開完了日を意味しません。

本記事について

本記事は、公開情報をもとに内容を整理し、できるだけ分かりやすく解説することを目的として作成しています。記載内容は個人の見解であり、所属組織の公式見解を示すものではありません。少しでもお役に立てればうれしいです。

ご質問・追記要望は本ページのコメント欄までお寄せください。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?