​

AttachmentRef

Defined in the protocols module.

AI Agent 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

Internal & Generic Methods

• from_dict: Validate a raw attachment dict into a typed ref.
• to_dict: Serialize to a wire dict, omitting the unused carrier field.

​

Source