---
title: 添付ファイル
description: Agent にファイルを送り、Agent が返すファイルを受け取ります。
---

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

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

```json
{ "attachments": { "type": "enabled" } }
```

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

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

## ファイルを送る

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

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

```json
{
  "id": "01a08791-5c2e-7b10-8a4f-3d2e1f0a9b8c",
  "name": "q3-review.pdf",
  "media_type": "application/pdf",
  "bytes": 482113,
  "expires_at": "2026-11-20T18:48:16Z"
}
```

```bash
# 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` に添付されたファイルが並びます。添付がない場合は空の配列です:

```json
{
  "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` の下にファイルを表示してください:

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

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

```bash
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 回だけです:

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

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

```ts
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` を返します。ブラウザーでは、ファイルの名前のまま人に保存してもらえます:

```ts
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](/ja/functions/runtime#session-volume) にコピーし、Function で扱えるようにします。 |
| `builtin__attachments__attach` | バージョンが Function を許可しているとき | Volume にあるファイルを最大 20 個 (各 1 GiB まで)、Agent 自身のメッセージに添付します。 |

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

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

## 上限、保持期間、課金

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

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