asset-resolution git:20260817.1203700A

Immutable. This exact content is served forever at /api/v1/blob/87d353306471046b.

---
name: asset-resolution
description: Resolve stable reusable visual assets for a Work, Script, Episode, Scene, or Shot. Use when an agent must discover visual objects, decide whether they merit long-term Asset identity, reuse an existing Asset, or create a new standard reference.
---

# Asset Resolution

Analyze only the current creative context and identify visual objects that may deserve reuse across Scenes, Shots, or Agent runs. Use `asset.get_asset` for a known `assetId`. Use `asset.list_assets` for a structured type scope; use `asset.search_assets` when only a natural-language identity or description is known. Judge candidates before creating anything. `FOUND` and `NOT_FOUND`, suitability, classification, and reuse decisions belong to the Agent.

Use `media.get_media` when an existing reference Media ID must be inspected. When no suitable Asset exists and a standard image is necessary, use `production.generate_image`; use its returned stable Media directly. Use `media.create_media` only when the generation capability returned an unregistered physical result, and never register an already stable `mediaId` again. Use `asset.create_asset` only after producing the complete initial formal state needed to register a genuinely new stable Asset. A successful create is the normal first write and returns the stable ID; do not call `asset.save_asset` immediately afterward unless a concrete revision has actually occurred. Use `asset.save_asset` only to revise an already persisted Asset because of a specific user request, discovered error, upstream change, or necessary addition to its formal state.

When standard-image production uses an external visual provider, load the shared [Visual Provider Capability and Technical Retry Policy](../shot-production/references/visual-provider.md). Apply its retry classification, bounded per-operation budget, submission-uncertainty protection, same-job recovery, and separate technical retry versus Visual Review revision counters. Do not duplicate or weaken that policy here.

Organize persistence as **Stable Envelope + Domain Content**. For a new Asset, keep its Work and optional narrower scope IDs, asset type, name, optional description, and reference Media IDs in the Stable Envelope; place type-specific approved visual identity and reusable creative facts in the `content` JSON object. For an Asset revision, preserve its scope and type, and submit the stable Asset ID with its complete revised mutable formal state. When `media.create_media` is genuinely needed, pass the stable scope, media type, purpose, and opaque `source_ref` as envelope data; never interpret that reference as a URL, bucket, path, filename, workflow node, or Provider response. Put only confirmed semantic Media facts in Domain Content. Do not hide, duplicate, or rename envelope fields inside `content`. Treat the Tool catalog as the sole machine-schema source. Use each save operation as a full replacement, never as a patch, stringified JSON, scratchpad, or routine follow-up to create.

Use `context.build_context` only when required creative context was not supplied, and use `context.refresh_context` only after a relevant state change. Keep chosen IDs in Agent Run Context. Do not create hierarchy, binding, or variant domains, and do not expose storage or implementation details.