# Agent V2 image replacement integration

The frontend keeps the original Agent V2 composer and sends image actions through the existing `generate` WebSocket message. Choosing, replacing, and requesting different options are ordinary user turns; no new endpoint or socket frame is required.

## Paired API contract

`search_web_images` accepts:

- required `query`
- optional `intent`: `photo | logo | product image | icon | background`
- optional `exclude_urls`: up to 20 exact prior source-page or image URLs

The result starts with `Search intent` followed by `Search provider`. A replacement search also returns `Replacement exclusions` and one `Excluded URL` line per excluded URL. Candidate blocks are separated by `---` and use these fields:

- `Result`, `Title`, `URL`, `Image URL`, optional `Thumbnail URL`, and `Dimensions`
- optional `Creator`, `Creator URL`, `Attribution`, `Source`, and `Provider`
- `License`, optional `License URL`, `License risk`, and `License warning`

Provider order is Brave when configured, then keyless Openverse, then Wikimedia Commons. Actual thumbnail bytes are attached privately to the model tool result for visual inspection; the browser continues to render the public thumbnail URL and does not need a separate model-vision field or endpoint.

`download_web_image` output continues to provide `Selected result`, `Source page`, `Source URL`, `Project path`, and `Use in the site as`. It may also repeat `Search intent` and the attribution/license fields. The frontend reads the persisted output to restore the currently selected result after a reload.

## Mixed-deployment behavior

The additions are backwards-compatible. Against the original API branch, the frontend infers intent from the search query and sends prior URLs in the ordinary replacement prompt. Against the paired API branch, the agent maps those same values to `intent` and `exclude_urls` and returns the explicit metadata above. The one-click “Show different options” prompt requires `search_web_images` to reuse the exact original `query` and exact `intent`; only `exclude_urls` may change, and excluded URLs must not influence or rewrite the subject. If the original query is unavailable, the agent asks for it instead of inventing one. `download_web_image` repeats `Search intent` so the selected role is restored without inference.

Field names are deliberately line-oriented and additive so the existing parser and stored tool output remain readable on both mixed and fully integrated PR deployments.