Attachment Ref • AI Agent SDK

AttachmentRef: A first-class attachment reference on the gateway wire protocol (Issue #5207).

AttachmentRef

Defined in the protocols module.

A first-class attachment reference on the gateway wire protocol (Issue #5207).

The gateway is the control plane every custom `/ws client builds on, yet the message frame carried only text or a free-form dict — a client had no supported, size-bounded, validated way to hand the agent a file or to receive an agent-generated artefact back. AttachmentRef` is that missing typed contract: one shape every client and gateway implementation agrees on, additive and backward-compatible (no existing frame changes shape).

An attachment is carried one of two ways:

• Inline — `data` holds base64 for a small file, bounded by the
• advertised `max_attachment_bytes` policy so a well-behaved client
• self-limits before sending rather than discovering the limit by being
• disconnected.
• By reference — `ref_id` names an entry the gateway materialised in
• its attachment store (see :class:AttachmentStoreProtocol), used for
• larger files streamed via chunked upload instead of a single frame.

The same shape is reused outbound: agent-generated files surface as `AttachmentRef` entries a generic client can fetch over the same connection, instead of relying on platform (Telegram/Slack/…) delivery.

Attributes: filename: Client-facing file name (display / download target). mime: MIME type of the payload (e.g. `image/png, application/pdf). size: Declared size in bytes (used to validate against policy ceilings). data: Inline base64 payload for a small file, or None when the attachment is carried by ref_id. ref_id: Identifier in the gateway attachment store for a chunked / large file, or None` for a purely inline attachment.

Properties

Source