HTML to Image

What the tool does

HTML to Image is a native agent tool. It sends an HTML/CSS document to a rendering service and returns a static image. Use it for cards, banners, coupons, receipts, and posts whose layout must follow explicit rules.

It does not work like Generate Image with LLM: the agent must compose the markup, CSS, and text in the result. This provides more control over structure and typography, but it does not turn a short description into a generative illustration.

Permission and activation

To open the agent editor and change its tools, a person needs the agents.write capability.

1. Open Agents and select the agent.
2. Go to Tools and choose Add Tool.
3. Under Native Tools, select HTML to Image.
4. Review all four parameters and choose AI decides or Manual for each one.
5. Select Save.

The tool is created as active. There is no separate organization activation or provider key to configure on this screen.

Parameters

Parameter	AI decides	Manual
html	The agent must send the complete HTML/CSS document on every call.	The same HTML is used on every call.
width	The agent may choose the width; if omitted, the runtime uses 1080.	Fixes the width in pixels.
height	The agent may choose the height; if omitted, the runtime uses 1080.	Fixes the height in pixels.
format	The agent may choose it; if omitted, the runtime uses webp.	Fixes webp, png, or jpeg.

A Manual value is no longer exposed to the model and takes precedence over anything it tries to send. Use this to standardize dimensions and format. Keep html on AI decides when content or layout should vary per request.

Manual template limit

The manual html field currently accepts at most 500 characters. Complete templates commonly exceed that limit. Until the product expands the field, prefer AI decides and put the layout rules the agent must follow in its prompt.

How to instruct the agent

The tool contract asks for complete HTML, with inline CSS or a <style> block. In the agent prompt, define:

• the goal and required content;
• width, height, and format when they are not fixed;
• palette, typography, spacing, and hierarchy;
• which data may vary and which elements must remain constant;
• meaningful alternative text for when the image is presented.

Example instruction:

When the customer requests a promotion card, use HTML to Image. Create a complete HTML document, keep a dark-blue background, white heading, and highlighted price. Use 1080 × 1080 and WebP unless the customer requests a different format.

After a successful execution, the agent receives { "status": "success", "imageUrl": "..." } and should present the image in Markdown. It is instructed not to repeat the same rendering automatically. On compatible external channels, the pipeline extracts the image from Markdown for delivery; in Hub, it appears in the response itself.

Content reliability and security

• Prefer self-contained HTML, inline CSS or <style>, and system fonts.
• Remote assets, web fonts, scripts, animations, dates, and dynamic content may change the result or fail. Therefore, the same HTML does not guarantee the same image when it depends on external state.
• Do not include secrets, tokens, unnecessary personal data, or internal URLs in the HTML. The document is sent to a rendering service outside the SquadOS pipeline.
• Use positive, moderate dimensions. The interface does not show minimum and maximum limits; larger areas automatically reduce the quality sent to the service and may increase time, size, and failure risk.
• The HTML to Image service is not in the SquadOS repository. Its network policy, file retention, and returned-URL lifetime therefore cannot be proven from the audited implementation. Do not treat the URL as permanent storage.

Failures and usage

If HTML is missing, the service is not configured, the response contains no image, or rendering fails, the tool returns { "status": "error", "error": "..." }. The agent is instructed to explain the failure and not retry on its own. For an error associated with a 30-second timeout, the message asks for a simpler layout.

Execution does not enter the image-model ledger used by Generate Image with LLM. The text model that creates the HTML and conducts the conversation still has its normal usage. The product does not display a separate rendering-service price in this configuration; do not promise that the operation is free.