Living-system image coverage

Living System Image Acquisition

agents.biomimicry.living_system_image_collector

Starts a checkpointed acquisition for a known LivingSystem. The stable run keeps prior searches, accepted images, rejection evidence, and the remaining gap across retries.

POST /v1/agents/agents.biomimicry.living_system_image_collector/invokeagents:invoke

When to use it

Good fit

  • Filling an empty or short LivingSystem gallery.
  • Resuming a run after source availability or rights evidence improves.
  • Obtaining publishable images with exact source and attribution details.

Use something else when

  • Selecting one image for a particular display. Use the image selector.
  • Searching without a living_system_id.
  • Overriding rights, species identity, or suitability review.

Request images after resolving a living-system record whose gallery needs coverage.

Required inputs

inputs.living_system_id
Identifier of the LivingSystem record.

Optional inputs

inputs.target_count
Desired total of publishable images, 1 to 20. Defaults to 5.
inputs.retry
Reopen a short terminal run using its saved evidence. Defaults to false.
inputs.refresh_evidence
With retry, recheck old rights, identity, and provider failures after a source or policy repair. Defaults to false.
inputs.max_cost_usd
Authorized spend for this invocation, up to $5. Defaults to $2. A retry authorizes a new attempt.
configuration.metadata
Your reference for the request, such as a lesson ID.
configuration.webhook_url
Optional HTTPS callback for terminal job events.
configuration.webhook_secret
Optional webhook signing secret.

What comes back

The completed job result is structured for integration. Preserve citations, warnings, confidence fields, and source context when the agent returns them.

Representative output fields

job_id
Job identifier for GET /v1/jobs/{job_id}.
status
Queued, running, completed, failed, or canceled job state.
poll_url
Polling URL returned when the job is accepted.
result.run_id
Stable target-bound acquisition run identity.
result.status
Acquisition state, including quota_met or an honest shortfall.
result.accepted_images
Published images with source and rights fields.
result.remaining_shortfall
Images still needed to meet target_count.
result.rejection_reasons
Reasons candidates did not pass the gates.
result.gap
Attempted terms, retry time, and advice when the gallery remains short.
result.next_agent_advice
Evidence-based next acquisition steps.
result.charge_usd
Final customer-visible charge for this invocation.

Accepted image fields

accepted_images[].id
Published image ID.
accepted_images[].url
Image URL.
accepted_images[].source_url
Source record or landing page.
accepted_images[].license_identifier
Exact normalized license identifier.
accepted_images[].license_url
License statement URL.
accepted_images[].creator
Creator supplied by the source.
accepted_images[].attribution
Attribution to display with the image.
accepted_images[].commercial_use_allowed
Commercial-use determination.
accepted_images[].modification_allowed
Modification determination.

How output is produced

  • Accepts the invocation as an asynchronous job.
  • Loads the LivingSystem and resolves the intended visual subject.
  • Searches approved sources and checkpoints provider and candidate evidence.
  • Publishes only images that pass rights, identity, suitability, and placement gates.
  • Returns accepted images and a specific gap when the target is still short.

Trust and caution

  • A short gallery is a completed acquisition result, not proof that any blocked image is usable.
  • The same run ID is reused for the LivingSystem. Retry reopens it with earlier evidence.
  • Ordinary retries explore new terms. Set refresh_evidence only after a provider, credential, or policy repair makes old evidence worth rechecking.
  • A source label such as No rights reserved is not sufficient publication evidence; keep the exact license, source, creator, and permitted-use fields.

Runtime

The invocation returns a job ID. Poll the job for its completed acquisition result.

Cost behavior

Use charge_usd from the completed job for customer accounting.

Billing notes

  • The queued estimate is provisional. The completed result reports charge_usd.
  • A repeated request without retry returns the terminal run without new acquisition work.
  • When retry is true, only new work from that invocation is charged.
Representative input
{
  "inputs": {
    "living_system_id": "6d9efd47-6726-4678-9c65-8467b116e1dd",
    "target_count": 3,
    "retry": false
  }
}
Queued response
{
  "job_id": "job_7f3a2b1c",
  "status": "queued",
  "agent_id": "agents.biomimicry.living_system_image_collector",
  "poll_url": "/v1/jobs/job_7f3a2b1c"
}
Representative completed result
{
  "job_id": "job_7f3a2b1c",
  "status": "completed",
  "result": {
    "success": true,
    "run_id": "image-first-layer-v1:living_system:6d9efd47-6726-4678-9c65-8467b116e1dd",
    "status": "exhausted",
    "target_count": 3,
    "accepted_images": [],
    "remaining_shortfall": 3,
    "rejection_reasons": ["natural_context:failed"],
    "gap": {
      "status": "exhausted",
      "next_agent_advice": ["Review the natural-context rejections before retrying."],
      "retry_after": "2026-09-26T03:00:00Z"
    },
    "charge_usd": 0.12
  }
}

Errors and retries

Common failures

  • Missing or unknown inputs.living_system_id.
  • inputs.target_count must be 1 to 20.
  • inputs.max_cost_usd must be between 0 and 5.
  • 401 or 403: the key is invalid or lacks agents:invoke.
  • 402: the organization cannot fund the requested job.
  • 429: honor Retry-After before submitting again.

Retry guidance

  • Poll GET /v1/jobs/{job_id} until the job is terminal.
  • Inspect result.gap and next_agent_advice before reopening with retry true.
  • Use refresh_evidence with retry only when a previously blocked source or policy has been repaired.
  • A fresh request without retry reads the same terminal acquisition run.

Composition ideas

Fill missing coverage

Request acquisition for the known LivingSystem, then inspect accepted_images.

Select for display

Run the image selector after acquisition completes.

Application fit

  • LivingSystem galleries.
  • Lesson images with retained attribution.
  • Coverage review for records with honest image gaps.