Outbound Media Delivery

Deliver agent-generated images and files to users via Telegram, Slack, Discord, and other messaging adapters

Agents can now return images, charts, and files that are automatically delivered through the bot adapter’s native upload primitive — Telegram send_photo, Slack files_upload_v2, Discord file send, and more.

from praisonaiagents import Agent

chart_agent = Agent(
    name="ChartAgent",
    instructions="Generate charts and return file paths in the media field.",
)
chart_agent.start("Draw a sales chart for Q1 and send it to the user.")

The user messages the bot; generated images and files upload through the channel adapter automatically.

Quick Start

1. Simple Usage

   from praisonaiagents import Agent
   
   chart_agent = Agent(
       name="ChartAgent",
       instructions="""
       Generate the requested chart, save it under /tmp/agent-media/,
       then return a message that includes the file path in the 'media' field.
       """,
   )

2. With Configuration

   roles:
     - role: ChartAgent
       backstory: Generates and delivers charts.
       tasks:
         - description: Draw a chart for the user's request.
   
   media_delivery:
     enabled: true
     max_size_mb: 10
     strict: true
     allowlist_roots:
       - /tmp/agent-media
     recent_mtime_seconds: 300

   Start the bot:

   praisonai bot telegram --config bot.yaml

   Users receive text plus the chart image attached automatically.

How It Works

When an agent returns a media file path, the gateway’s outbound binding validates it through the path safety guard and delivers it via the adapter’s native primitive:

On the send_message path, uploads to an unattested <platform>:<chat_id> are refused upstream in BotOutboundMessenger.send() — the media path is never entered. See Destination Attestation.

Path safety guard

validate_media_delivery_path() runs two checks before any file is sent:

System directory denylist (always blocked): /etc, /proc, /sys, ~/.ssh, ~/.aws, ~/.gnupg, gateway secret/pairing directories.

Credential basename denylist (always blocked): .env, id_rsa, id_ecdsa, id_ed25519, .npmrc, .netrc, and similar credential filenames — matched from any directory.

Remote-sandbox media (Modal, E2B, Daytona, Fly.io, SSH, …)

When an agent runs off-box in a remote sandbox and generates a file, the gateway fetches the artifact back and delivers it through the same MEDIA path — the user gets the file automatically.

from praisonaiagents import Agent, SandboxConfig

chart_agent = Agent(
    name="ChartAgent",
    instructions=(
        "Generate the requested chart, save it under /workspace/, "
        "then return a MEDIA:/workspace/<filename>.png line."
    ),
    sandbox=SandboxConfig(sandbox_type="modal"),   # or e2b, daytona, flyio, ssh, novita
)
chart_agent.start("Draw a sales chart for Q1 and send it to the user.")

The user sends a message. The agent runs remotely, writes the chart on the sandbox filesystem, and returns MEDIA:/workspace/chart.png. The gateway detects the remote path, fetches it back, re-screens it, and delivers it — no extra wiring.

End-to-end flow

Behaviour

Unlike the old silent drop, the operator now always gets a logger.warning(...) when a MEDIA path is undeliverable, so the failure is visible in logs.

The RemoteMediaResolver protocol

Exported from praisonaiagents.gateway:

from praisonaiagents.gateway import RemoteMediaResolver

@runtime_checkable
class RemoteMediaResolver(Protocol):
    """Resolves a sandbox-local media path to a gateway-local deliverable path."""

    def owns_path(self, path: str) -> bool:
        """True if `path` refers to a file inside this sandbox."""
        ...

    async def fetch_to_local(self, remote_path: str) -> str:
        """Fetch `remote_path` out of the sandbox to a local path.
        The caller re-screens the returned path through the outbound-path guard."""
        ...

Each remote sandbox backend already has a download_file / read_file primitive (Modal read_file, E2B read_file, Daytona fs.download_file, Fly.io compute.download_file, SSH read_file, Docker download_file, Novita read_file, Subprocess read_file). The active sandbox backend for the turn is the resolver — application code does not implement this protocol itself.

Compatibility & safety

• Byte-for-byte backward compatible. With no resolver in play, split_media_from_output_async() returns the same dict shape and values as the existing split_media_from_output() — local paths and URLs are untouched.
• No new required parameters on Agent. No new dependencies added. No per-turn plumbing surfaced to user code.
• The exfiltration guard still runs. Fetched artifacts are re-screened by validate_media_delivery_path() before delivery, so the system-directory / credential-basename denylist, size cap, strict-mode allowlist, and recent_mtime_seconds window all still apply. See Path safety guard.
• Fail-open on error. A resolver failure (missing/wrong backend, download error, guard rejection) degrades to the historical silent drop plus an operator-visible warning — never a crash on the reply path.
• The sync split_media_from_output() is unchanged. Only the new async variant split_media_from_output_async() is remote-aware.

When does this fire?

Configuration (media_delivery YAML block)

media_delivery:
  enabled: true
  max_size_mb: 25
  strict: false
  allowlist_roots:
    - /var/agent/output
    - /tmp/agent-media
  recent_mtime_seconds: 600
  basename_denylist:
    - secret_config.yml

OutboundMediaPolicy fields

Platform Support

PlatformCapabilities.supports_media is checked per adapter — platforms that don’t support file uploads receive text-only replies and the attachment is skipped with a log entry.

Threaded media delivery

Attachments follow the same platform:channel_id:thread_id grammar the text path uses. When a route names a thread, both the text reply and any uploaded file land in that thread.

from praisonai.bots import DeliveryRouter

# Scheduled attachment into a Slack thread
router.send_media("slack:C0123456:1728987654.001234", "/tmp/report.pdf",
                  caption="Weekly report")
# → Slack files_upload_v2(..., thread_ts="1728987654.001234")

# Telegram forum topic
router.send_media("telegram:-1001234567890:42", "/tmp/chart.png",
                  caption="Q1 chart")
# → bot.send_photo(..., message_thread_id=42)

DeliveryRouter.send_media resolves the thread from the target and forwards it to deliver_media_to_adapter, which passes it through each transport’s native keyword only when the primitive accepts it — so non-threaded adapters never raise.

Discord thread targeting is scoped to the parent channel

A target shaped discord:<channel_id>:<thread_id> resolves the thread under the parent channel. If <thread_id> isn’t a thread of <channel_id>, the upload lands in the parent channel rather than being redirected to a channel that happens to share that global id. This matches how send_message‘s text path already resolves Discord threads.

Retry & backoff on transient failures

Media uploads go through the same deliver_with_retry wrapper as text replies. A transient transport failure — HTTP 5xx, rate limit, connection reset — is retried with bounded exponential backoff (honouring a server-mandated Retry-After hint) instead of silently dropping the attachment on the first blip.

Which backoff policy is used?

DeliveryRouter.send_media reuses the adapter’s already-configured _outbound_backoff BackoffPolicy if one is set (matching the text path). If the adapter exposes no policy, a sensible default is used:

To customise, set outbound_resilience on the channel in praisonai.yml (the same block that tunes text retries — see Outbound Resilience). The media upload picks up the same values automatically.

Non-retryable outcomes are preserved

Common Patterns

Chart generation bot

from praisonaiagents import Agent
import matplotlib.pyplot as plt
import os

chart_agent = Agent(
    name="ChartAgent",
    instructions="""
    When asked for a chart:
    1. Generate it using matplotlib
    2. Save to /tmp/agent-media/<filename>.png
    3. Return the file path in your response
    """,
)

media_delivery:
  enabled: true
  max_size_mb: 10
  strict: true
  allowlist_roots:
    - /tmp/agent-media
  recent_mtime_seconds: 300

Multi-tenant / hosted gateway (strict mode)

For hosted environments where multiple users share the same gateway, enable strict mode with an explicit output directory:

media_delivery:
  enabled: true
  max_size_mb: 5
  strict: true
  allowlist_roots:
    - /var/agent/output
  recent_mtime_seconds: 120
  basename_denylist:
    - config.yml
    - secrets.json

Disable media delivery

media_delivery:
  enabled: false

Or with quoted string (both are equivalent):

media_delivery:
  enabled: "false"

Summary Messages

When media delivery completes, BotOutboundMessenger.send appends a summary:

2 attachment(s) delivered, 1 skipped

Skipped files (denied by path guard, over size cap, etc.) are logged at debug level and never cause the message send to fail.

Best Practices