MediaReference

MediaReference is the pointer stored on a run in place of the media bytes. It records which backend holds the object and enough metadata to serve it without a further lookup.

Field	Type	Default	Description
`media_id`	`str`	-	ID of the media object this reference replaces.
`storage_key`	`str`	-	Key of the object in the backend.
`session_id`	`Optional[str]`	`None`	Session whose run uploaded the object.
`storage_backend`	`str`	-	Backend that holds the object, for example `"s3"`, `"gcs"`, or `"local"`.
`bucket`	`Optional[str]`	`None`	Bucket holding the object. For local storage, the resolved base path.
`region`	`Optional[str]`	`None`	Region of the bucket.
`url`	`Optional[str]`	`None`	Durable URL for the object, when the backend has one. Signed URLs expire, so they are never stored here.
`mime_type`	`Optional[str]`	`None`	Content type of the stored object.
`filename`	`Optional[str]`	`None`	Original filename.
`size`	`Optional[int]`	`None`	Size of the object in bytes.
`content_hash`	`Optional[str]`	`None`	SHA-256 of the content.
`media_type`	`Optional[str]`	`None`	One of `"image"`, `"audio"`, `"video"`, or `"file"`.
`metadata`	`Optional[Dict[str, Any]]`	`None`	Full metadata for the media. The backend may store a sanitized subset on the object itself.

Metadata

Image, Audio, Video and File take a metadata dict. It is written onto the stored object and kept in full on the reference.

Image(content=data, metadata={"source": "invoice-scan", "page": "3"})

Backends trim what they put on the object itself: S3 takes ASCII only within about 1800 bytes, GCS within 8000, and the local backend writes it to a .meta.json file beside the object. The reference keeps the whole dict either way. Over HTTP, send it to the agent or team run route as files_metadata, a JSON array matched to files[] by position. The array must stay under 8000 bytes or the request is rejected with 422.

Agno SDK Reference

AgentOS API Reference

Agno CLI

Agno Infra CLI

MediaReference

Metadata

​Metadata

Metadata