> ## 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**](../modules/protocols) module.

<Badge color="blue">AI Agent</Badge>

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

<ResponseField name="filename" type="str">
  No description available.
</ResponseField>

<ResponseField name="mime" type="str">
  No description available.
</ResponseField>

<ResponseField name="size" type="int">
  No description available.
</ResponseField>

<ResponseField name="data" type="Optional[str]">
  No description available.
</ResponseField>

<ResponseField name="ref_id" type="Optional[str]">
  No description available.
</ResponseField>

<Accordion title="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.
</Accordion>

## Source

<Card title="View on GitHub" icon="github" href="https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai-agents/praisonaiagents/gateway/protocols.py#L552">
  `praisonaiagents/gateway/protocols.py` at line 552
</Card>