agentagent.run()
Make the structure of an agent task explicit: what runs, what runs in parallel, and when to stop.
AgentRun is a workflow DSL for tools, code, agents, and Jev system one decisions—typed decisions with probabilities. Reuse a workflow inside another. Test one decision without running the whole system. Use agents where you need their tool loops; workflows can also run without them.
One example: research a decision
Should our team move its docs from a wiki into the code repository?
Plan the questions → Research each in parallel → Write the report
│
└─ Search → Jev selects evidence → Write a finding
│
No evidence? Stop.
Jev selects passages that answer each question—including evidence against the proposed change. Topic mentions and unsupported marketing claims are excluded. If no evidence survives, the workflow stops before writing a report.
The research component is a workflow itself. Use it alone, test its evidence selector, or run a copy for each question. Read the complete definition →
Run it
Requires Node 22.19+ and npm; the examples run TypeScript directly. This preview is private and unlicensed; npm packages are not published yet. Release status.
git clone --branch codex/open-source-beta --single-branch https://github.com/Parcha-ai/agentrun.git
cd agentrun
npm ci --ignore-scripts
npm run build
npm run demo
The demo runs the real interpreter with fictional sources and scripted model responses. After installation, it needs no keys or network. It prints the workflow, then:
Report: Pilot the repository workflow first. Reviews gain an explicit approval step, but editing and search still have gaps.
3 subquestions researched; 3 sources retained.
Calls: 3 tools, 3 system one decisions, 5 model steps.
Now make every source fail the evidence check:
npm run demo -- --no-evidence
It stops before writing findings or a report and exits with code 2. Only the planning model step runs. Same workflow; different decision results.
Test the parts
npm run test:typed-example
npm run eval:research
The tests exercise the evidence selector, one research component, and the complete workflow. The evaluation runs the actual evidence-selection step against six independently labeled cases, including contrary evidence and misleading topic overlap. Scripted results test the wiring; connect Jev to evaluate real decisions. Add Pi or your own agent for the complete report.
To change the workflow, edit typed-research.ts: the evidence rubric, selection threshold, parallelism, and writing instructions are all there. Scripted answers live separately; they will not adapt to a new prompt. The authoring walkthrough explains how to supply your own tools and models.
Why a DSL?
The workflow is a serializable graph with defined execution rules. Author it in TypeScript with Zod input/output contracts, or write JSON. The same document can be inspected, run, and tested in pieces.
- Reuse a workflow as a step. Give it its own input, output, and tests, then compose it inside maps, routes, and bounded loops.
- Keep decisions separate from execution. Jev returns typed decisions and probabilities; the workflow controls what happens next.
- Keep your harness. It supplies tools, model access, permissions, budgets, and storage. AgentRun supplies composition, validation, and execution events.
For a small fixed sequence, ordinary functions may be enough. AgentRun is useful when the workflow itself needs to be an inspectable, reusable document—especially one an agent can author and your application can validate before running.
Types are inferred at input/output boundaries; intermediate state paths are checked at runtime. Workflows can contain executable JavaScript and are not a sandbox. See contracts and limits and harness integration.