Media - GroundForge

Channels can carry audio, images, and documents. The Channel receives and verifies the attachment. The external Agent SDK prepares the content before invoking the Agent. This keeps media-model credentials with the Agent instead of the Channel.

Custom handlers

init_groundforge(
    agent=agent,
    media={
        "audio_transcriber": transcribe_audio,
        "document_extractor": extract_document,
        "image_handler": analyse_image,
    },
    # connection values omitted
)

A handler receives a bounded attachment and returns text or another small value that can be added to the Agent request.

Provider configuration

media={
    "audio": {
        "provider": "openai",
        "model": "gpt-4o-mini-transcribe",
    }
}

Here, provider means the media model used by the Agent process. It is not the Channel provider.

Safe handling

verify the Channel request before downloading media;
enforce file-size and content limits;
do not log raw media bytes;
keep media credentials off the Channel configuration;
return bounded extracted text or descriptions;
treat untrusted documents and archives carefully.

Example

Use the media handlers with the external weather Agent only after the Channel has verified and normalized the incoming attachment. Keep provider credentials in the Channel and model-processing credentials with the Agent.

Last modified on July 27, 2026

Related topics

Security Configuration