Deleting Offloaded Media

Delete session rows, then attempt a best-effort sweep of their offloaded media.

Delete a session and request cleanup of its offloaded media with delete_media=True.

Session deletion and object cleanup are not atomic. Agno records the storage keys, deletes the session rows, then attempts a best-effort object sweep. A storage failure can leave orphaned objects after the rows are gone.

media_storage_delete.py

"""
Deleting Offloaded Media
========================

Demonstrates deleting a session's stored media along with its rows. Offloaded media outlives
the session by default, because the reference in the row is the only record of which object
belongs to which session — delete the rows first and nothing can find the objects again.

Pass delete_media=True and the keys are read before the rows, then the objects are swept.
The same flag exists on Agent, Team and Workflow, sync and async.

Requirements:
- uv pip install 'agno[s3]'
- AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
- Set MEDIA_S3_BUCKET to the destination bucket
Run: .venvs/demo/bin/python cookbook/06_storage/09_media_storage_delete.py
"""

import os

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

# ---------------------------------------------------------------------------
# Setup
# ---------------------------------------------------------------------------
DB_FILE = "tmp/media_delete.db"
PREFIX = "agno/media_delete/"
IMAGE_URL = "https://picsum.photos/id/15/800/600.jpg"

bucket = os.getenv("MEDIA_S3_BUCKET")
if not bucket:
    raise ValueError("MEDIA_S3_BUCKET must be set to the destination S3 bucket")

storage = S3MediaStorage(
    bucket=bucket,
    region=os.getenv("AWS_REGION"),
    prefix=PREFIX,
    presigned_url_expiry=3600,  # 1 hour
)

agent = Agent(
    model=OpenAIResponses(id="gpt-5.5"),
    media_storage=storage,
    db=SqliteDb(db_file=DB_FILE),
)


def stored_keys() -> list:
    import boto3

    client = boto3.client("s3", region_name=os.getenv("AWS_REGION"))
    listing = client.list_objects_v2(Bucket=bucket, Prefix=PREFIX)
    return sorted(obj["Key"] for obj in listing.get("Contents", []))


def describe(session_id: str, image_bytes: bytes) -> None:
    agent.run(
        "What do you see in this image?",
        session_id=session_id,
        images=[Image(content=image_bytes, format="jpeg", mime_type="image/jpeg")],
    )


# ---------------------------------------------------------------------------
# Run the Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    image_bytes = httpx.get(IMAGE_URL, follow_redirects=True).content
    describe("keeps-media", image_bytes)
    describe("sweeps-media", image_bytes)
    print("Stored in S3 after two sessions:", len(stored_keys()))

    # Without the flag the rows go and the objects stay
    agent.delete_session(session_id="keeps-media")
    print("After deleting one session without the flag:", len(stored_keys()))

    # With it, the keys are read off the rows first, then the objects are swept
    agent.delete_session(session_id="sweeps-media", delete_media=True)
    print("After deleting the other with delete_media=True:", len(stored_keys()))
    print("Left behind:", stored_keys())

Run the Example

1. Set up your virtual environment

   Mac

   uv venv --python 3.12
   source .venv/bin/activate
   
2. Install dependencies

   uv pip install -U "agno[s3]" botocore openai sqlalchemy
   
3. Export environment variables

   Mac/Linux

   export AWS_REGION="your_aws_region_here"
   export MEDIA_S3_BUCKET="your_media_s3_bucket_here"
   export OPENAI_API_KEY="your_openai_api_key_here"
   
4. Configure AWS credentials

   Configure the AWS SDK default credential chain with environment variables, a shared credentials file, or an IAM role.

5. Run the example

   Save the code above as media_storage_delete.py, then run:

   python media_storage_delete.py
   

Full source: cookbook/06_storage/09_media_storage_delete.py