コンテンツにスキップ
Subako Docs
日本語
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

添付ファイル

Agent にファイルを送り、Agent が返すファイルを受け取ります。

メッセージにはファイルを添付できます。確認してほしい契約書、整理してほしいスプレッドシート、Agent が書いたレポートなどです。メッセージに添付されたファイルを 添付ファイル と呼びます。添付ファイルは会話とともに保存されるコピーで、同じ ID のまま中身が変わることはなく、Session がある間は編集も削除もできません。

添付ファイルは、Agent のバージョンで有効にするまで使えません:

{ "attachments": { "type": "enabled" } }

コンソールでは、バージョンの編集画面 の Tool にある 添付ファイル で設定します。Session は実行するバージョンの設定に従います。ただし、別の Session から開始された Session では、バージョンの設定にかかわらず添付ファイルを使えません。Session 自体も、この設定を attachments として返します。

人のメッセージ Agent のメッセージ
ファイルの送り方 アップロードしてから、入力でそのファイルを指定します Session Volume にあるファイルを attach で添付します
必要な設定 attachments が有効 attachments が有効で、バージョンが Function を許可していること
Event message_user の attachments message_attachments_added。attach を呼び出した message_assistant に属します

ファイルを送る

ファイルは先に単独でアップロードし、続く入力でそのファイルを指定します。

# 1. ファイルをアップロードします。メディアタイプは名前の拡張子で決まります。
curl -X POST "https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/uploads?name=q3-review.pdf" \
  -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @q3-review.pdf
{
  "id": "01a08791-5c2e-7b10-8a4f-3d2e1f0a9b8c",
  "name": "q3-review.pdf",
  "media_type": "application/pdf",
  "bytes": 482113,
  "expires_at": "2026-11-20T18:48:16Z"
}
# 2. アップロードしたファイルを指定して、メッセージを送ります。
curl -X POST https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/events \
  -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "input", "text": "Summarize the risks in this review.", "upload_ids": ["01a08791-5c2e-7b10-8a4f-3d2e1f0a9b8c"]}'
  • name は report.pdf のような 1 つのパスセグメントで、1~200 byte です。リクエストボディはファイルのバイト列で、最大 1 GiB です。
  • 1 つの入力で指定できるアップロードは 20 個までです。ファイルだけを送る場合、text は空でもかまいません。
  • 1 つのアップロードを添付できるメッセージは 1 つだけです。送信すると、同じ id のままそのメッセージの添付ファイルになります。
  • どのメッセージにも添付されなかったアップロードは、expires_at (アップロードから 24 時間後) に削除されます。その後に指定すると 404 が返るので、アップロードし直してください。
  • 同じ Idempotency-Key で同じ名前と長さのアップロードを再試行すると、2 つ目を保存せずに最初のアップロードが返ります。

アップロードには、Session token か、Session › 管理 の権限を持つ API key を使います。Agent が添付ファイルを有効にしていない Session や、添付ファイルと送信待ちのアップロードの合計がすでに 10 GiB に達している Session では、409 が返ります。

ファイルを表示する

人のメッセージは message_user で、attachments に添付されたファイルが並びます。添付がない場合は空の配列です:

{
  "type": "message_user",
  "message": { "role": "user", "content": [{ "type": "text", "data": { "text": "Summarize the risks in this review." } }] },
  "source": "client",
  "attachments": [
    { "id": "01a08791-5c2e-7b10-8a4f-3d2e1f0a9b8c", "name": "q3-review.pdf", "media_type": "application/pdf", "bytes": 482113 }
  ]
}

Agent が添付したファイルは message_attachments_added で届きます。call_id はこの Event を生んだ attach の呼び出しなので、その呼び出しを含む message_assistant の下にファイルを表示してください:

{
  "type": "message_attachments_added",
  "call_id": "call_7d1e",
  "attachments": [
    { "id": "01a087a2-0b4c-7e21-9c3d-6f5e4d3c2b1a", "name": "risks.md", "media_type": "text/markdown", "bytes": 3912 }
  ]
}

どちらの場合も、ファイルのバイト列は次のルートで取得できます:

curl https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/attachments/$ATTACHMENT_ID \
  -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN" \
  -o q3-review.pdf

レスポンスは添付ファイルの media_type で返り、中身にかかわらず常にダウンロードとして配信されます。同じ ID のバイト列が変わることはないので、クライアントは好きなだけキャッシュできます。API key で取得するには Session › 読み取り の権限が必要です。

TypeScript SDK で使う

Session への接続の send は、ファイルのアップロードと指定を 1 回の呼び出しで行います。ターンを何度再試行しても、各ファイルのアップロードは 1 回だけです:

await session.send("Summarize the risks in this review.", { files: [file] });

人が入力している間など、送信より前にアップロードしておくには upload を呼び、返った ID を uploadIds に渡します:

const upload = await session.upload(file, { name: file.name });
await session.send("", { uploadIds: [upload.id] });

readAttachment は、message_user や message_attachments_added の attachments の要素が示す id を指定してファイルをダウンロードし、media_type を型に持つ Blob を返します。ブラウザーでは、ファイルの名前のまま人に保存してもらえます:

const blob = await session.readAttachment(attachment.id);
const url = URL.createObjectURL(blob);
const link = Object.assign(document.createElement("a"), { href: url, download: attachment.name });
link.click();
setTimeout(() => URL.revokeObjectURL(url), 0);

画像を表示するには、同じオブジェクト URL を <img> の src に渡します。API key を持つバックエンドからは、接続なしで client.sessions.readAttachment(sessionId, attachmentId) として同じファイルを取得できます。

@subako-ai/assistant-ui では、allowAttachments を指定すると、用意されたチャットの入力欄に添付ボタンが加わり、自分で組むスレッドではランタイムの添付ファイル用アダプターが有効になります。

Agent が添付ファイルでできること

添付ファイルを有効にしたバージョンには、builtin:attachments の組み込み Tool が提供されます。Policy はありません。添付ファイルを有効にすること自体が判断です。

Tool 提供される条件 動作
builtin__attachments__read 常に 添付ファイルを読みます。テキストは一部ずつ返ります。行単位 (既定は 200 行、指定すれば最大 10,000 行) か byte 単位で読み、1 回の呼び出しで最大 256 KiB です。画像はモデルに見せます。
builtin__attachments__copy_to_volume バージョンが Function を許可しているとき 添付ファイルを /volume/tmp/report.pdf のように Session Volume にコピーし、Function で扱えるようにします。
builtin__attachments__attach バージョンが Function を許可しているとき Volume にあるファイルを最大 20 個 (各 1 GiB まで)、Agent 自身のメッセージに添付します。

人が送ったファイルは、メッセージの中の <attachment id="…" name="…" media_type="…" bytes="…"/> という行としてモデルに伝わり、モデルは必要と判断したときだけ読みます。PDF やスプレッドシートのように read で表示できないファイルは、Agent が Volume にコピーし、Platform package などの Function で変換します。

attach は、呼び出した時点の各ファイルをコピーします。その後 Volume で何が起きても添付ファイルは変わらず、Agent は attach が返した ID でそのファイルを参照します。

上限、保持期間、課金

1 つのメッセージのファイル数 20 個 (人の入力、または 1 回の attach の呼び出し)
1 つのファイル 1 GiB
1 つの Session 添付ファイルと送信待ちのアップロードの合計 10 GiB。超えると、新しいアップロードや attach は拒否されます
どのメッセージにも添付されなかったアップロード アップロードから 24 時間後に削除されます
添付ファイル Session を削除するまで保持されます

Session の添付ファイルと送信待ちのアップロードは、削除されるまで、保持しているバイト数と期間に応じてストレージとして課金されます。価格は Plan と使用量 を参照してください。

このページは役に立ちましたか?