S3 Media Storage

S3MediaStorage uploads media to an S3 bucket and keeps only a MediaReference in the database. It also supports MinIO and other S3-compatible services through endpoint_url.

Usage

Install the required packages:

uv pip install "agno[s3]" openai sqlalchemy

Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or pass the credentials directly. Pass region explicitly: left unset, boto3 falls back to AWS_DEFAULT_REGION or ~/.aws/config, and it does not read AWS_REGION.

media_storage_s3.py

import os

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.media.storage import S3MediaStorage
from agno.models.openai import OpenAIResponses

storage = S3MediaStorage(
    bucket=os.getenv("MEDIA_S3_BUCKET"),
    region=os.getenv("AWS_REGION"),
    prefix="agno/media/",
    presigned_url_expiry=3600,
)

agent = Agent(
    model=OpenAIResponses(id="gpt-5.5"),
    db=SqliteDb(db_file="tmp/data.db"),
    media_storage=storage,
)

Async

AsyncS3MediaStorage takes the same parameters and uses aioboto3.

from agno.media.storage import AsyncS3MediaStorage

storage = AsyncS3MediaStorage(bucket=os.getenv("MEDIA_S3_BUCKET"))

URLs

get_url returns a presigned URL that expires after presigned_url_expiry seconds. A presigned URL is never written to the database, since it would expire and it carries credentials, so a fresh one is signed on each read. Above the SigV4 maximum of seven days, no URL is signed and readers stream the bytes instead. Set acl="public-read" to return the unsigned object URL instead. That URL does not expire, so it is stored on the reference. A bucket with ACLs disabled, the default for new buckets, rejects the argument with a ValueError.

S3-compatible Services

Point endpoint_url at the service and set region to match its own site region.

storage = S3MediaStorage(
    bucket="media",
    endpoint_url="http://localhost:9000",
    region="us-east-1",
)

A presigned URL carries the region in its signature. A service whose region differs from the one configured here rejects the URL.

Params

Parameter	Type	Default	Description
`bucket`	`str`	-	Name of the destination S3 bucket.
`prefix`	`str`	`"agno/media/"`	Key prefix for stored objects.
`region`	`Optional[str]`	`None`	AWS region. Falls back to `AWS_DEFAULT_REGION` or `~/.aws/config`.
`acl`	`Optional[str]`	`None`	Object ACL applied on upload. `"public-read"` also makes `get_url` return the unsigned object URL instead of a presigned one.
`presigned_url_expiry`	`int`	`3600`	Signed URL lifetime in seconds. Above the SigV4 maximum of seven days, URLs fall back to streaming.
`endpoint_url`	`Optional[str]`	`None`	Endpoint of an S3-compatible service such as MinIO.
`aws_access_key_id`	`Optional[str]`	`None`	AWS access key ID. Falls back to the standard credential chain.
`aws_secret_access_key`	`Optional[str]`	`None`	AWS secret access key. Falls back to the standard credential chain.
`persist_remote_urls`	`bool`	`False`	Download and store media passed as a URL. Skipped when `False`.

See the full example here.

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

S3 Media Storage

Usage

Async

URLs

S3-compatible Services

Params

​Usage

​Async

​URLs

​S3-compatible Services

​Params

Usage

Async

URLs

S3-compatible Services

Params