What is Save Screenshot?
Save Screenshot as Run Attachment is a specialized tool that captures the current screen state and saves it as an attachment to your workflow run. Unlike regular screenshots used for navigation, these are specifically preserved as outputs that can be accessed after the workflow completes.
In your prompts, always refer to this tool as save_screenshot_as_run_attachment (lowercase, with underscores).
- Proof of Completion: Transaction confirmations, submission receipts
- Medical Imaging: X-rays, scans, patient charts
- Quality Assurance: Visual verification of results
- Compliance: Audit trails and visual evidence
- Data Capture: Charts, graphs, or visual data that’s hard to extract
This tool ensures important visual moments are captured even during cached runs, providing consistent documentation across all executions.
How It Works
- When the agent reaches a specified point in the workflow
- It calls
save_screenshot_as_run_attachment with a descriptive filename
- The current screen is captured and saved
- The screenshot is attached to the Run record
- The attachment ID is added to the Run’s
output_attachment_ids array
Screenshots are captured at full screen resolution and saved in PNG format for maximum quality and compatibility.
You can optionally pass a zoom_bounding_box parameter to capture a zoomed-in crop for analysis. Format: [x1, y1, x2, y2] in pixels relative to the full screenshot. After analyzing a zoomed image, always take a fresh full screenshot before generating coordinate actions.
zoom_bounding_box is clamped to the screenshot bounds if values go out of range, and coordinates are always interpreted in the full-screenshot pixel space (not the zoomed image). Consider including a small padding margin in your bbox to avoid cropping labels/edges.
When to Use Screenshot Attachments
1. Confirmation Screens
"After submitting the payment, wait for the confirmation page to load,
then use save_screenshot_as_run_attachment to capture the confirmation
as 'payment_confirmation_{invoice_number}.png'"
2. Medical Images
"Navigate to the patient's imaging results. Open the chest X-ray dated {scan_date}
and use save_screenshot_as_run_attachment to save it as
'{patient_id}_chest_xray_{scan_date}.png'"
3. Dashboard Captures
"After the analytics dashboard loads with data for {month}, use
save_screenshot_as_run_attachment to capture the full dashboard
as '{client_name}_analytics_{month}.png'"
4. Error Documentation
"If any error message appears during processing, use save_screenshot_as_run_attachment
to capture it as 'error_{timestamp}.png' before attempting to resolve"
How to Prompt for Screenshots
Best Practices
- Descriptive Filenames: Use clear, contextual names for easy identification
- Include Context: Specify when and what to capture
- Use Variables: Incorporate input variables for dynamic naming
- Be Specific: Clearly indicate the exact moment to capture
Prompt Template
"[Navigate to specific screen/state], [wait for specific element if needed],
then use save_screenshot_as_run_attachment to capture [what's being captured]
as '[descriptive_filename].png'"
Zoomed Captures
"Zoom into the billing subtotal region by passing zoom_bounding_box [x1, y1, x2, y2], then use save_screenshot_as_run_attachment as '{customer_id}_subtotal.png'. After analysis, take a fresh full screenshot before any clicking."
Real-World Examples
Healthcare: Patient Documentation
"Open patient {patient_name}'s record and navigate to the vitals chart.
Ensure the last 30 days of data is visible, then use save_screenshot_as_run_attachment
to save the vitals trend as '{patient_id}_vitals_trend_{date}.png'.
This screenshot is critical for the physician's review."
E-commerce: Order Processing
"Complete the order for customer {customer_id}. On the order confirmation page,
use save_screenshot_as_run_attachment to capture the full page including
order number, items, and total as 'order_{order_number}_confirmation.png'"
Finance: Transaction Records
"After executing the wire transfer of ${amount} to {recipient_bank},
wait for the success screen, then use save_screenshot_as_run_attachment
to document the transaction as 'wire_transfer_{transaction_id}.png'.
Ensure the reference number is clearly visible."
Insurance: Claim Evidence
"For each damage photo in the claim, maximize the image view and use
save_screenshot_as_run_attachment to save it as
'claim_{claim_number}_damage_{photo_number}.png'.
Capture all 5 required angles."
Naming Strategies
Dynamic Naming with Variables
"Use save_screenshot_as_run_attachment to save the test results as
'{patient_lastname}_{test_type}_{test_date}.png'"
Using Runtime Variables in Names
"First, use focused_action to read the order number from the confirmation screen
and save it as {{order_number}}. Then use save_screenshot_as_run_attachment
to capture the receipt as 'order_{{order_number}}_receipt.png'"
Sensitive Variables
If your prompt includes {$variable}, the value is handled securely and never logged or shown. Avoid including secrets in screenshot filenames or on-screen content. The agent will not repeat secrets in observations, but screenshots may still capture whatever is visible on screen; prefer verification that doesn’t display the secret.
Sequential Captures
"For each step of the procedure:
1. Screenshot the pre-procedure state as 'procedure_{case_id}_step1_before.png'
2. Perform the action
3. Screenshot the result as 'procedure_{case_id}_step1_after.png'
Use save_screenshot_as_run_attachment for each capture."
Timestamped Names
"Capture the system status dashboard every 5 minutes during the test.
Use save_screenshot_as_run_attachment with names like
'system_status_{test_id}_{capture_time}.png'"
Common Patterns
Wait Before Capture
"After clicking 'Generate Report', wait for the loading spinner to disappear
and the report to fully render (usually 3-5 seconds), then use
save_screenshot_as_run_attachment to save it as 'report_{report_id}.png'"
Conditional Screenshots
"Check if the prescription includes controlled substances. If yes,
use save_screenshot_as_run_attachment to capture the prescription
as 'controlled_rx_{patient_id}_{date}.png' for compliance records."
Multiple Page Documentation
"The report spans 3 pages. For each page:
1. Use save_screenshot_as_run_attachment to save as 'report_{report_id}_page{n}.png'
2. Click 'Next Page'
Repeat for all pages."
Quality Considerations
Tips for high-quality screenshots:
- Ensure the relevant content is fully visible (not cut off)
- Wait for all elements to load before capturing
- Maximize windows when capturing detailed information
- Consider zoom levels for readability
- For small UI elements, consider
zoom_bounding_box to improve clarity
Ensuring Content Visibility
"Scroll to ensure the entire form is visible on screen (all fields from
'Patient Name' to 'Signature' should be in view), then use
save_screenshot_as_run_attachment to capture as 'completed_form_{form_id}.png'"
Handling Pop-ups and Overlays
"If a confirmation dialog appears, use save_screenshot_as_run_attachment
to capture it as 'confirmation_dialog.png' before clicking OK.
Make sure the dialog is centered and fully visible."
With Focused Action
"Use focused_action to verify the chart has loaded completely with all data points
visible. Once confirmed, use save_screenshot_as_run_attachment to capture
the analytics chart as '{metric_name}_trend_{date_range}.png'"
With File Export
"Generate the PDF report and save to D:\Reports\{report_id}.pdf.
Use mark_file_for_export on the PDF file. Also use save_screenshot_as_run_attachment
to capture the report summary screen as '{report_id}_summary.png'
for quick reference."
Documentation Workflow
"For the audit trail:
1. Screenshot the initial state: 'audit_{audit_id}_initial.png'
2. Perform the changes as specified
3. Screenshot each change confirmation
4. Screenshot the final state: 'audit_{audit_id}_final.png'
Use save_screenshot_as_run_attachment for all captures."
Advanced Usage
Creating Visual Logs
"During the 10-minute system test, use save_screenshot_as_run_attachment
every minute to create a visual log. Name files as 'test_{test_id}_minute_{n}.png'
where n goes from 1 to 10."
Comparison Documentation
"Open the previous version in the left panel and current version in the right panel.
Use save_screenshot_as_run_attachment to capture the side-by-side comparison
as 'document_comparison_{doc_id}_v{old}_vs_v{new}.png'"
Error State Collection
"If the workflow encounters any unexpected screens or error messages:
1. Use save_screenshot_as_run_attachment to capture as 'unexpected_state_{timestamp}.png'
2. Include these screenshots in the error report
3. Continue with error recovery steps
This helps with debugging failed runs."
Best Practices Summary
- Always specify clear, descriptive filenames
- Ensure content is fully loaded before capturing
- Use input variables for dynamic naming
- Capture at moments that provide maximum value
- Consider the screenshot’s purpose when framing the capture
- Document both success and failure states when relevant
