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.

Outbound media delivery uses the same OutboundResilienceMixin now applied to all six channels: Slack, Discord, WhatsApp, Email, Linear, AgentMail, and Telegram. See Durable Delivery for retry and crash-safe persistence.

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:

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.

---

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

Field	Type	Default	Description
enabled	bool	True	Master switch. Quoted "false" in YAML also disables
max_size_mb	int	25	Per-file size cap in megabytes
strict	bool	False	If True, only deliver files inside allowlist_roots or with mtime within recent_mtime_seconds
allowlist_roots	list[str]	[]	Strict-mode: only files under these roots are delivered
recent_mtime_seconds	int	600	Strict-mode: only files modified within this window (seconds) are delivered
basename_denylist	list[str]	[]	Extra basenames added on top of the built-in denylist

---

Platform Support

Platform	Native primitive	Media types
Telegram	send_photo, send_document	Images, documents
Slack	files_upload_v2	Any file type
Discord	File attachment	Any file type

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.

---

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

Write agent output to a dedicated directory

Configure your agent to save all generated files to a single directory like /tmp/agent-media/ and set that as the allowlist_roots entry. This keeps the path guard simple and predictable.

Enable strict mode for production

In production or multi-tenant gateways, set strict: true with explicit allowlist_roots. This prevents agents from accidentally delivering files from unexpected locations.

Set a reasonable size cap

Default is 25 MB. Telegram and Slack have their own size limits — set max_size_mb below those limits to fail fast at the gateway rather than at the adapter.

Never save credentials near the output directory

The basename denylist blocks common credential filenames, but keep your output directory completely separate from config directories. Symlink attacks are also blocked (symlinks are resolved before path checks).

---

Related

Messaging Bots

Full bot setup and configuration guide

Channels Gateway

Gateway channel routing and configuration

Gateway

Gateway architecture and YAML reference

Bot Inbound Media

Handle images and files sent by users