imgagent: Rights-Checked Images for AI Agents (One JSON Contract, Verified Bytes)

Last updated: November 12, 2026 · 6-minute read

Five rights states, one hard rule: a high relevance score can never override the rights gate. imgagent is the image tool I built for my own agent workflows, after one too many pipelines grabbed a picture that was downloadable and completely unusable — wrong license, wrong file, or an HTML error page wearing a .jpg name.

Agents do not need more image search. They need image search that answers three questions before a file lands in a project: is it really an image, is it the image the metadata claims, and are you allowed to publish it. imgagent exists to make those answers part of the contract, not a hope.

The Failure It Was Built Against

Hand an agent a naive image search and three failures follow in order. First, the top result is chosen by text match alone, so a generic illustration outranks the authentic photograph the story actually needs. Second, the download is trusted because the URL ends in an image extension — and servers lie, returning HTML pages, corrupt files, and empty payloads with a straight face. Third, and worst, nobody records the license.

The image ships in a video or an article, and the rights question gets asked afterwards, by someone else, in public.

Each failure has the same root: the tool treats "found a URL" as the end of the job. In imgagent the job ends at verified local paths with a manifest — or it reports, in structured form, exactly where it fell short. Honest negatives are a feature of the contract, not an error message.

One Command, Nine Stages

imgagent run "Isdal Woman Norway 1970 historical photographs" \ --limit 20 --top 5 --out ./assets --json

The run command walks one fixed pipeline, and every stage is independently callable:

A broken provider never breaks the others: per-source failures come back as structured entries in errors[], and partial success is represented explicitly in the payload instead of rounded up to success.

The Rights Gate Is the Product

Technical downloadability and publication permission are separate questions, and imgagent records both. Every asset carries its source URL, provider, creator, license name and URL, attribution text, retrieval timestamps, file hash, and dimensions — plus a rights state drawn from five values:

• verifiedpublicdomain
• verifiedlicense
• permissionrequired
• unknown
• restricted

Pass --require-reuse-rights and only the verified states survive the filter. The ranking can argue all it wants; a relevant image with unknown rights does not pass a gate that was set to verified-only. Generic illustration and authentic evidence also stay distinguishable, through an authenticity field and a --prefer-authentic flag — because a film about a real case needs the real photograph, not a mood picture, and the tool should know the difference even when the search engine does not.

The provider choices follow the same doctrine. Wikimedia and Openverse are the tested defaults — official APIs, license metadata, no key required for Wikimedia and an optional one for Openverse. Google Images is deliberately not implemented as fragile HTML scraping; if you want it, you configure an official API as a custom source. There is no CAPTCHA, paywall, login, or access-control bypass anywhere in the codebase.

Built for Machines First

The machine contract is strict because agents are strict readers:

• --json emits exactly one JSON object on stdout; diagnostics go to stderr, always
• Exit codes carry meaning: zero for success including explicit partial success, one for no usable results, two for usage errors, three for config or dependency problems
• imgagent agent-instructions prints the complete contract an agent can follow without a human in the loop
• An optional MCP server (pip install 'imgagent[mcp]', then imgagent-mcp) wraps the same functions, and a Python API (from imgagent import api) exposes search, listing, download, and manifest calls directly

Security got the same treatment as rights. Downloads are hashed with SHA-256 and decoded in full before they count as images. SSRF protection blocks private, link-local, and loopback ranges, hard-blocks cloud metadata endpoints, validates redirect by redirect, and caps response sizes. TLS verification is never disabled as a fallback.

It runs on about two runtime dependencies — httpx and Pillow — on Python 3.10 or newer, CPU-only, no browser, across Linux, macOS, Windows, Termux, and containers.

Where It Falls Short

The honest answer: imgagent is young, small, and opinionated, and two of those three are visible from space.

• Zero stars and six commits. As of November 12, 2026 the repo sits at zero stars with a short history. It is live on PyPI and built for my own production workflows, but it has no community mileage, and you should read its guarantees as design commitments to verify, not a track record.
• The default sources bound the universe. Wikimedia and Openverse are strong on historical and openly licensed material and thin on current commercial imagery. If your project needs this week's press photos, the rights gate will mostly tell you no — correctly, but still no.
• DuckDuckGo is best-effort. The README labels it volatile and unofficial; its failures are graceful and explicit, but a default pipeline stage that can wobble is a wobble you inherit.
• Rights metadata is only as honest as the source. The gate enforces what providers record. A wrong license recorded upstream passes as verified downstream — the manifest preserves attribution and provenance so a human can audit, but the tool cannot litigate a bad record.
• Downloaded images carry their own licenses. The tool records them; respecting them at publication time remains the publisher's job. Mine included.

The Verdict

imgagent earns its place in my stack because it refuses the two shortcuts that make agent image pipelines dangerous: trusting the bytes and skipping the rights. One JSON contract, verified files, a rights gate that outranks relevance, and negatives it admits to — that is the whole design, and it is the design my film and article pipelines actually needed.

It is MIT-licensed and on PyPI. The wider agent toolkit it belongs to — video pipelines, subtitle gates, clipping tools — lives on the projects page, and the open-source video pipeline build shows the workflow imgagent feeds.

---

Not affiliated with Wikimedia or Openverse. Sources: imgagent GitHub repository, including its README, provider matrix, and rights documentation.