Skip to main content

Promo Render MCP

With this feature the agent can design promotional graphics (social posts, ads, banners) and export them as ready-to-use PNG images in the AION visual style. Users simply ask for a graphic, ideally with the graphic_designer profile. This page is for administrators who install the export tool (Playwright, a headless browser) and enable the profile, and for developers who maintain the templates. MCP (Model Context Protocol) servers are the plug-in tool providers the agent calls.

Server promo_render turns session React/HTML canvases into PNG files for social and ads, using Playwright and design tokens aligned with chat-ui.

Setup (once per host)​

Important: PNG export uses the MCP server Python (promo_render), not the per-chat session sandbox venv. Installing Playwright only inside a session does not fix promo_check_environment.

./scripts/setup-aion-env.sh and ./scripts/upgrade-aion.sh (with --prepare-runtime on a local upgrade) invoke runtime_extras_setup.py, which:

  • Appends AION_PROMO_CAPTURE_ENABLED=1 to .env if missing
  • Runs ./scripts/setup_promo_playwright.sh unless --skip-promo-playwright
./scripts/setup-aion-env.sh
# or, after a git pull
./scripts/upgrade-aion.sh

Filesystem policy details and flags: Filesystem policy and PNG promo export.

Manual​

From the AION_Agent repo root:

./scripts/setup_promo_playwright.sh

Or manually (use the same python that runs the AION backend / mcp_servers/promo_render/.venv/bin/python if present):

python3 -m pip install "playwright>=1.49.0"
python3 -m playwright install chromium

Then in chat: promo_check_environment must return "ok": true with the chromium path in detail.

Optional: AION_PROMO_CAPTURE_ENABLED=0 disables capture.

Troubleshooting​

SymptomCauseFix
ok: false, pip install playwrightPlaywright missing in MCP PythonRun setup_promo_playwright.sh
Capture fails after check OKChromium binaries missingpython -m playwright install chromium with MCP python
Works in sandbox script, not in promoTwo different venvsIgnore session venv for promo

Tools​

ToolDescription
promo_list_canvas_presetsInstagram 4:5 = instagram_portrait (1080×1350)
promo_get_component_catalogBento CSS classes (.promo-tile--*)
promo_get_style_guidePREMIUM_STYLE + aion-promo-theme.css
promo_scaffold_react_postlayout_style=bento_red (production) or minimal
promo_capture_to_pngPNG export (wait_ms ≥ 2000 for fonts)
promo_check_environmentMCP Python + Chromium (not sandbox venv)

Common issues​

SymptomCauseFix
Two conflicting postspromo_scaffold called twice + extra sandbox_writeUse promo_scaffold_social_pack once
Square/LinkedIn uglyinstagram_square used react_post.html placeholderNow uses bento_square_red / bento_linkedin_red
Cyan post, no logoAgent invented paletteRed only; default logo_url + product_image_url in scaffold
Blue/violet centered UIAgent ignored bento + red tokenslayout_style=bento_red, load promo_visual_system
workspace/workspace/promo/...Double workspace/ in artifact pathFixed in path normalizer; use filename: promo/x.html only
Playwright false after sandbox pipWrong Python env./scripts/setup_promo_playwright.sh
Blank/wrong fonts in PNGnetworkidle + slow CDNCapture uses load + document.fonts wait
Ugly generic layoutShipped minimal scaffoldDefault is bento_portrait_red.html

Profiles​

SlugRole
graphic_designerDedicated profile — promo workflow only (recommended)
aion_stdAlso includes promo_render + promotional_graphics

Select Graphic Designer in chat-ui profile picker, or pass profile: "graphic_designer" on /chat.

Download​

PNG path example: workspace/promo/my_campaign/output.png
GET /sessions/{session_id}/download?relative_path=workspace/promo/my_campaign/output.png