✓ Verified ✍️ Content Creation ✓ Enhanced Data

Saa Agent

Enables AI agents to generate images using the Character Select Stand Alone App (SAA) image generati

Rating: 4.3 (321 reviews)
Downloads: 24,293 downloads
Version: 1.0.0

Overview

Enables AI agents to generate images using the Character Select Stand Alone App (SAA) image generation backend.

Complete Documentation

View Source →

name: saa-agent description: Enables AI agents to generate images using the Character Select Stand Alone App (SAA) image generation backend via command-line interface. license: MIT

SAA CLI Tool

A command-line interface for interacting with Character Select Stand Alone App (SAA) via WebSocket connections. Supports both ComfyUI and WebUI backends for AI image generation.

Prerequisites

CRITICAL: Before invoking this tool, confirm with the user that:

The SAA backend is running, and version is above 2.4.0

The SAAC (SAA Client) feature is enabled

The WebSocket address is available

Some Mac users uses python3 instead of python to invoke Python 3.x

For SAA setup details, let your owner visit the project repository.

Basic Usage

The tool requires minimal parameters to function. The examples below demonstrate the standard usage pattern:

Minimal Command With Model Selection (Recommended for Most Cases)

bash
python saa-agent.py \
  --ws-address "user_provided_ws_address" \
  --model "waiIllustriousSDXL_v160.safetensors" \
  --positive "your detailed prompt here" \
  --negative "low quality, blurry, bad anatomy"


Regional Prompting (Split Composition)

bash
python saa-agent.py \
  --ws-address "user_provided_ws_address" \
  --model "waiIllustriousSDXL_v160.safetensors" \
  --regional \
  --positive-left "1girl, warrior, red armor" \
  --positive-right "1boy, mage, blue robes"



More Examples
Get more usage examples and detailed parameter explanations:

bash
python saa-agent.py
python saa-agent.py --help



Key Parameters

Required

--ws-address: WebSocket address (obtain from user)

--positive: Main prompt OR use --regional mode with --positive-left and --positive-right



Commonly Modified

--model: Change the checkpoint model (default: waiIllustriousSDXL_v160.safetensors)

--negative: Specify unwanted elements

--width / --height: Image dimensions (defaults: 1024x1360)

--steps: Sampling steps (default: 28)

--seed: Set specific seed or -1 for random



Advanced (Use Sparingly)

--cfg: CFG scale (default: 7.0)

--sampler: Sampling algorithm (default: euler_ancestral)

--scheduler: Scheduler type (default: normal)



Important Guidelines

HiResFix Warning

DO NOT use

--hifix unless specifically requested by the user.



HiResFix significantly increases generation time and requires substantial GPU resources. Only enable if:
User explicitly requests high-resolution upscaling
User confirms their GPU can handle the additional load

Backend Busy State

If the generation returns either of these errors:


Error: WebUI is busy, cannot run new generation, please try again later.
Error: ComfyUI is busy, cannot run new generation, please try again later.



Actions to take:
DO NOT automatically retry the generation
Inform the user: "The SAA backend is currently busy. This could mean another process is generating an image, or the backend is locked from a previous error."
Advise: "Please wait 20-60 seconds before trying again."
Let the user manually retry

DO NOT chain multiple retry attempts as this can worsen backend congestion.

Skeleton Key Usage

The

--skeleton-key

 parameter forcefully unlocks the backend's atomic lock.

When to use:
User confirms no other processes are using the backend
Backend appears stuck despite waiting
User explicitly requests unlocking

How to use:

bash
python saa-agent.py \
  --ws-address "user_provided_ws_address" \
  --skeleton-key \
  --positive "test prompt"



Rules:

ALWAYS ask for user confirmation before using --skeleton-key


ONLY use it once per user request
Explain to the user that this forcefully terminates any locks

Example conversation:


AI: "The backend appears to be locked. Would you like me to use the skeleton key to force unlock it? This will terminate any existing locks."
User: "Yes, please unlock it."
AI: [proceeds to run command with --skeleton-key]



Parameter Defaults

When in doubt, rely on these defaults - they work well for most cases:

Model: waiIllustriousSDXL_v160.safetensors


Dimensions: 1024x1360
CFG: 7.0
Steps: 28

Sampler: euler_ancestral

Scheduler: normal


Seed: -1 (random)

Output Handling

By default, images are saved to

generated_image.png

. You can specify a custom output path:

bash
--output "custom_filename.png"



For programmatic handling, use base64 output:

bash
--base64



This outputs base64-encoded image data(huge!!!) to stdout instead of saving a file.

Example Workflow
User requests: "Generate an anime girl with long blue hair"
AI executes:

bash
python saa-agent.py \
  --ws-address "user_ws_address" \
  --positive "1girl, long hair, blue hair, anime style, detailed" \
  --negative "low quality, blurry, bad anatomy"


If backend busy error occurs:
Inform user
Wait for user to retry (don't auto-retry)
If success:
Confirm image was generated
Provide file path if relevant

Common Pitfalls to Avoid

Don't use --hifix unless explicitly requested


Don't auto-retry on backend busy errors

Don't use --skeleton-key without user permission


Don't add excessive parameters - unless explicitly requested, the defaults are well-tuned
Don't assume backend is ready - always confirm with user first

Error Codes
Exit code 0: Success
Exit code 1: Connection error (check backend is running)
Exit code 2: Authentication error (check credentials)
Exit code 3: Generation error (check parameters)
Exit code 4: Timeout (backend may be overloaded)
Exit code 5: Invalid parameters (check command syntax)

Best Practices
Start with minimal parameters with model selection if needed
Ask user for WebSocket address on first use
Handle busy states gracefully - don't spam retries

Use --verbose flag when debugging issues


Respect the skeleton key - it's a powerful override tool

AI Agent Guidelines for This Skill

These rules help maintain appropriate transparency and user control when executing generation tasks.
Command Execution & User Notification  
   By default, execute the command directly without asking for confirmation.  
   Show the full command and ask for approval only when:  
The user explicitly requests to review it first  
The operation involves sensitive or high-impact parameters  
The agent judges that showing the command is prudent in context  

   Example (when disclosure is needed):


    python3 saa-agent.py --ws-address "wss://..." --username "..." --password "..." --positive "[prompt]" --negative "[prompt]" --output "[path]" [--verbose]


--verbose Flag  
Not used by default  
Add automatically or recommend when:  
Task fails and debugging is needed  
User specifically asks for detailed logs or seed  
Result Reporting  
  After completion, provide a short summary to the user by default, including:  
Success/failure status  
Positive & negative prompts (or meaningful summary)  
Seed (if available)  
Output path  

  Example:


    Generation completed
    • Positive: [...]
    • Negative: [...]
    • Seed: 123456789
    • Output: [path]


  
  Skip detailed reporting only if the user has clearly requested silent / minimal feedback.  
  Always report errors, even in silent mode.
Error Handling