DOCUMENTATION / EXAMPLES

Documentation for AgentRun 0.1.0-beta.27. Use the matching setup instructions → GitHub’s main branch may include unreleased changes.

Runnable examples

Start with the support quickstart. Every example below runs on scripted models by default, with no key: it exercises the workflow and its plumbing, not model quality. The workflow examples use fictional inputs; the vision examples use real public files (public-domain films and photographs, and pages of a public filing).

After npm ci --ignore-scripts and npm run build:

Example Run What to change
Support answers npm run demo:support Connect your search tool and agent; check an answer before returning it.
Typed research npm run demo Reuse one research component across questions and stop when evidence is missing.
Rank a list npm run demo:rank Score candidates against your brief, drop duplicates, cap each bucket, keep the top k; call it from another workflow.
Standalone TypeScript app Follow the app's install steps, then npm test and npm start Build outside this checkout with public package imports.
The reference host npm run demo:reference One durable pi run with the recovery driver, a browser and vision: replace the scripted model, tools, browser and eyes with yours.
An agent that learns npm run demo:learn An issue-triage agent learns a maintainer's correction in its own git repository and applies it in the next run, and a workflow it saved is promoted on clean uses: copy host.mjs and give it your model, judge and remote.
The hero job npm run demo:hero One agent reads nine grid operators' dashboard charts with vision, each in a browser session of its own, and, where the operator also publishes the mix as data, checks each reading against it.
The vision agent npm run demo:vision -- examples/document-check (free; needs ffmpeg, ffprobe, pdftoppm and pdftotext), and add --live with your keys Ask a question about your own files: write a folder with the question and the files' addresses; one agent answers it and ends with its own report.

The ranking example is a reusable workflow built from existing nodes, not a node of its own. A sift scores every candidate with a leveled question, and the continuous score in <as>.answers[i].answers.<question>.score orders them. Sorting, the minimum score, per-bucket quotas and the cut-off are a code step. A second sift over pairs finds near-duplicates among the best consider candidates, the only ones that can make the list. That costs consider × (consider − 1) / 2 questions, so the caller chooses it. A long list needs no batching in the workflow: a sift over the host's per-request limits splits itself. npm run demo:rank -- --live --input request.json ranks your own list with Jev.

Each example includes a failure or uncertainty path. npm run demo:support -- unresolved and npm run demo -- --no-evidence exit with code 2 after escalation.

To connect models, follow support integration or research integration. Your application supplies tool permissions, credentials and cancellation. Scripted answers remain fixed when you edit a prompt.

Vision examples

@parcha/pi-vision reads files for a model. One agent, examples/vision-agent, answers every question below; each folder holds only the question, the files' addresses and checks, and a README. All but the document check and Lake Mead fetch their files first: add --fetch-sources (the size is in each one's README).

  • Video chapters. A long film cut into chapters, each with a keyframe and the minutes it rests on.
  • Hear and find. When a phrase is said and when a thing is first seen in a long film: both seconds, the frame and a box around the thing.
  • Document check. Two certified copies of a certificate of incorporation: which marks each carries and where, with a box on each.
  • The Apollo 11 descent. NASA's transcript, photographs and film, read into the landing minute by minute.
  • A government film, in chapters. A 1930s film on the building of Boulder Dam, cut into chapters.
  • A robot in a long film. When a golden robot is first seen in a 1939 film of nearly an hour, and where it is in the frame.
  • Lake Mead from space. Thirteen Landsat images of one frame, 1984 to 2024, and the lake's elevation record: when the water fell the most and where, with a box on each place that went dry then.
  • A trip down Market Street, 1906. A single take from a cable car: every vehicle that crosses in front of the camera, to the second, boxed, then counted by kind.