> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Attachment Ref • AI Agent SDK

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

# AttachmentRef

> Defined in the [**protocols**](https://praison.ai/docs/sdk/reference/praisonaiagents/modules/protocols.md) 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

**filename** `str`

No description available.

**mime** `str`

No description available.

**size** `int`

No description available.

**data** `Optional[str]`

No description available.

**ref\_id** `Optional[str]`

No description available.

> **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

> **[View on GitHub](https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/gateway/protocols.py#L552)**
>
> `praisonaiagents/gateway/protocols.py` at line 552


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.