添付ファイル
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 と使用量 を参照してください。