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.