# Using an agent (/docs/agents/using-an-agent) Once connected, just ask your agent in plain language. For example: "List SimpliGen's image presets, then generate a red fox in the snow and show me the file." ## What an agent can do [#what-an-agent-can-do] * **See what is available:** every preset it can generate with, image or video, and whether the models are installed locally. * **Generate:** start an image or video job from a prompt, with optional reference images or a start image. It can run locally, on SimpliGen Cloud, or pick automatically. * **Track jobs:** check status and wait for a result. * **Hand back results:** return the finished file path, or show the image right in the chat. * **Prepare presets:** start downloading a local preset's models so it becomes ready to use. * **Run the studios:** list the recipes installed in UGC Studio and Product Studio, fill their inputs (a character, a product, a few choices) and run them, exactly as a click on Generate would. See [UGC Studio and Product Studio](#ugc-studio-and-product-studio) below. ## Local vs cloud [#local-vs-cloud] Generations run locally by default and never cost credits. Cloud is offered only when you have SimpliGen Cloud connected, and a well-behaved agent asks before spending credits (or follows whatever auto-approve mode you run it in). ## Keeping an agent in bounds [#keeping-an-agent-in-bounds] * **Spend cap.** When you connect an agent you can set an optional cloud spend cap. The agent can never spend more than that on cloud credits, no matter what it is asked to do. Local generation is always allowed and never counts against it. Leave the cap empty for no limit, or set it to **0 to block cloud entirely** (local-only). * **Tokens are local and revocable.** A pairing token only works against SimpliGen on your own machine, and you can revoke it any time from **Connected agents**. Revoking is instant. * **The app stays in control.** The agent talks to SimpliGen; it cannot reach your cloud account or your key directly. Before handing an agent a big batch, try a couple of single local generations so you can see how it phrases requests and what it returns. If your agent runs on a different machine, see [Remote access](/docs/agents/remote-tunnel). ## UGC Studio and Product Studio [#ugc-studio-and-product-studio] Both studios are collections of recipes: multi-step pipelines (an edit, an upscale, a video) with a small form on the front. An agent can run the same recipes through `run_recipe`. 1. **Find a recipe.** `list_recipes` returns everything installed on this device, with a `category` (`ugc` or `product`) and the `inputs` each recipe asks for: the key, its kind, whether it is required, and the allowed options for choices. 2. **Bring the subjects.** A `subject` input takes a character id (from `list_characters`) or a product id. To add a product, upload its photo with `upload_file` and call `create_product` with a name and a short description; the description is woven into the recipe's prompts. 3. **Run it.** `run_recipe` with the recipe id and the filled inputs. It returns a run id right away. `engine` is `local` by default when every step's preset is installed, or `cloud` when connected; `get_recipe` shows per-step readiness so the agent can tell in advance. 4. **Wait.** `wait_for_recipe_run` blocks until the run finishes and returns each step's result plus the final file. `cancel_recipe_run` stops a run early. A run started by an agent lands in the Gallery grouped like a studio run and appears in the recipe's run history, so you can reopen, reuse, or redo it in the app afterwards. Cloud runs are priced before they start and count against the agent's spend cap. ## Character Studio [#character-studio] An agent can create reusable characters and generate scene images or animated videos from them. Before starting, call `get_status` and check `characters.enabled`: it is `true` when the engine is running and the required character presets are installed. `characters.basegenPresets` and `characters.editPresets` report how many presets of each type are ready. ### Creation path 1: describe [#creation-path-1-describe] The agent calls `list_character_features` to get available identity features (skin tone, hair colour, eye shape, and so on), picks values for each, then calls `create_character` with `mode: 'generate'` and an `identity` map of `{ featureId: optionId }`. The tool polls internally until the base portrait is ready, then returns the ready character object (with `characterId` and `base_image_url`). The agent does not need to poll a job id; the character is ready to use as soon as the tool returns. Each feature and option is keyed by its `id` (use this in API calls); the `label` on each option is a plain-English description so the agent can present choices to the user in a readable way. ``` create_character({ name: "Mara", gender: "woman", mode: "generate", identity: { skinTone: "tan", hairColor: "black", eyeShape: "almond" } }) ``` ### Creation path 2: upload as base [#creation-path-2-upload-as-base] If the user has an image they want to use directly, the agent calls `create_character` with `mode: 'upload'` and the absolute local path to the image in `baseFilePath`. The tool handles the upload internally. No generation step runs; the character is ready immediately. ``` create_character({ name: "Mara", gender: "woman", mode: "upload", baseFilePath: "/absolute/path/to/photo.jpg" }) ``` ### Creation path 3: vision-recreate [#creation-path-3-vision-recreate] The agent (with vision) looks at a user photo, reads the person's visible features, maps them to the options returned by `list_character_features`, and then follows path 1 (describe). The photo is not used as the base image. A fresh portrait is generated to recreate the look from the described features. This is useful when the user wants a stylised version of themselves or someone else rather than a photographic likeness. Example agent reasoning flow: 1. User shares a photo. 2. Agent calls `list_character_features` and reviews the option ids. 3. Agent inspects the photo and fills an `identity` map: `{ skinTone: "light", hairColor: "red", hair: "longWaves" }`. 4. Agent calls `create_character` with `mode: 'generate'` and the filled `identity`. 5. Tool returns the ready character object (no polling needed; it waits internally). Agent shows the base portrait to the user. ### Generating scenes and videos [#generating-scenes-and-videos] Once a character is ready (base accepted), pass its `characterId` to `generate_character_image` or `generate_character_video`: ``` generate_character_image({ characterId: "char-abc123", prompt: "standing on a beach at golden hour", aspect: "16:9" }) ``` ``` generate_character_video({ characterId: "char-abc123", prompt: "standing in a park", motion: "waving at the camera" }) ``` Both return job ids. Use `wait_for_result` to poll, then `get_result_image` (images) or the file path from `get_job` (videos) to retrieve the output. **Note:** Character generation is local-only in v1. The engine must be running (`characters.enabled: true` in `get_status`) and the required character presets must be installed. Cloud dispatch is not supported for character tools. ### Switching presets per call [#switching-presets-per-call] Call `list_character_presets` to see which presets are installed and their ids. Each call to `generate_character_image` and `generate_character_video` accepts an optional preset override: * `generate_character_image` accepts `presetId`, an identity-edit preset id from the `identityEdit` list. * `generate_character_video` accepts `framePresetId` (identity-edit preset for the frame step) and `videoPresetId` (i2v preset for the animate step). If you omit the override, the character's sticky default is used (or the system default if none is set). ### Setting a sticky per-character default [#setting-a-sticky-per-character-default] Use `set_character_preset` to record a default preset on a character so you do not need to pass `presetId` on every call: ``` set_character_preset({ characterId: "char-abc123", imagePresetId: "flux-character-edit", videoPresetId: "ltx-i2v-standard" }) ``` Pass `null` for either field to clear that default: ``` set_character_preset({ characterId: "char-abc123", imagePresetId: null }) ``` ### Enhancing an image or video [#enhancing-an-image-or-video] `enhance_character_media` runs an upscale preset on any character asset. Before calling it, check `characters.enhancePresets` in `get_status` (or inspect the `enhanceImage`/`enhanceVideo` arrays from `list_character_presets`) to confirm an upscale preset is installed. Each enhancement preset lists its available scale factors in `supportedScales`. Source options: * **A completed job:** pass the job id in `jobId`. The media type is inferred from the job. * **An uploaded file:** upload with `upload_file` first, then pass the handle in `filePath`. Include `mediaType: "image"` or `mediaType: "video"`. * **The character base portrait:** pass `target: "base"`. This always treats the source as an image. Additional parameters: * `scale`: upscale factor (e.g. `2` or `4`; must be in the preset's `supportedScales`). * `keepResolution`: if `true`, the result is upscaled then resized back to the original source dimensions, producing a sharper same-size image without changing the output pixel count. * `applyAsBase`: if `true`, the upscaled result replaces the character's base portrait automatically once the job completes. ``` enhance_character_media({ characterId: "char-abc123", jobId: "gen-xyz", scale: 2 }) ``` ``` enhance_character_media({ characterId: "char-abc123", target: "base", scale: 4, keepResolution: true, applyAsBase: true }) ``` ### Frame review flow: generate -> enhance -> animate [#frame-review-flow-generate---enhance---animate] You can review and enhance a still frame before committing to the video render: 1. Call `generate_character_frame` to produce a single still frame. This returns `{ jobIds: [...] }`; use `jobIds[0]` as the frame job id. 2. Poll `jobIds[0]` with `wait_for_result` and review the image with `get_result_image`. 3. Optionally call `enhance_character_media` with `jobId: jobIds[0]` to upscale the frame. This returns a new job id; poll it to completion. 4. Call `animate_character` with `jobId` set to the completed enhance job id (or `jobIds[0]` from the frame if you skipped enhancement). `animate_character` accepts any completed image job as its source. ``` // Step 1: generate frame generate_character_frame({ characterId: "char-abc123", prompt: "walking through a city street" }) // -> { jobIds: ["gen-frame-111"] } // Step 3: upscale the frame enhance_character_media({ characterId: "char-abc123", jobId: "gen-frame-111", scale: 2 }) // -> { jobId: "gen-enhance-222" } // Step 4: animate from the upscaled frame animate_character({ characterId: "char-abc123", jobId: "gen-enhance-222", motion: "walking confidently" }) ``` ### Regenerating a base in place [#regenerating-a-base-in-place] Use `regenerate_character_base` to queue a new base portrait generation for an existing character without creating a new character record. You can optionally switch to a different base preset or update the identity features at the same time: ``` regenerate_character_base({ characterId: "char-abc123", basePresetId: "flux-character-base-v2", identity: { skinTone: "light", hairColor: "blonde", hair: "bob" } }) ``` The tool polls internally, auto-accepts the new portrait once the job completes, and returns the ready character object. The agent does not need to poll a job id afterward.