DOCUMENTATION / START HERE

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

New here? Connect Jev and your agent → The examples below cover other uses of the same language.

AgentRun

Open-source packages for your pi agent. Install the ones you need.

This repository holds the AgentRun harness: the workflow DSL and the pi extensions around it.

pi-vision lets a pi agent answer questions about documents, images and video, and show the page, second or region each answer rests on. Try it free, with no key (the models are scripted), in a checkout built as under Run the support example: npm run demo:vision -- examples/document-check. It needs ffmpeg, ffprobe, pdftoppm and pdftotext (brew install ffmpeg poppler, or sudo apt-get install ffmpeg poppler-utils). See pi-vision.

Quickstart · Packages · Documentation · Examples · Pi extension · Agent instructions

Support workflow: search for an answer, check it with Jev, and return it or ask an agent to investigate. Check the investigation before returning it or escalating for review.

View the static diagram · Run this example

The support example below follows this workflow with scripted tools and model responses.

Quickstart

The DSL defines repeatable steps, uses Jev for focused decisions, and calls an agent when the work needs investigation. Your application keeps its tools, model access, permissions and budgets.

Requires Node 22.19+ and npm. In your project:

npm install @parcha/agentrun-dsl@0.1.0-beta.27
npx @parcha/agentrun-dsl@0.1.0-beta.27 demo

This ticket-routing demo uses scripted decisions and needs no API key. Next, run and change a workflow in your own app. To run the support workflow shown above, use the checkout below. To build workflows with your agent, install the Pi extension.

Run the support example

To run the workflow in the animation, clone the examples and build:

git clone --branch main --single-branch https://github.com/Parcha-ai/agentrun.git
cd agentrun
# With nvm: nvm install && nvm use
npm ci --ignore-scripts
npm run build
npm run demo:support

This runs the interpreter with scripted tools, Jev answers, and agent responses. It needs no API key and sends no customer replies.

The command prints a report for each case:

Request Agent calls Decision calls Result
Reset a password 0 1 Return the help answer
Find an invoice 0 1 Return the help answer
Investigate a failed payment 1 2 Return the investigation answer
Payment still unresolved 1 2 Escalate for review
npm run demo:support -- payment
npm run test:support

Try npm run demo:support -- unresolved to see an escalation. It exits with code 2. The responses are scripted; changing a prompt does not change them.

Connect live Jev and your agent, or give these instructions to your coding agent.

Use one piece, or all of it

Use one piece

Each package works on its own. Pi is an open-source coding agent; pi-durable is Pi's runtime that commits each turn and tool call to storage; chord is the plugin and service runtime pi-durable is built on; Archil is a network disk you mount on any Linux host.

Package What it does What it needs First command with no key Status
@parcha/agentrun-dsl Define, validate, inspect and run workflows Node 22.19+ npx @parcha/agentrun-dsl@0.1.0-beta.27 demo published (@beta)
@parcha/agentrun-jev Jev typed decisions as a workflow's runJudge the DSL; TYPESAFE_API_KEY for live calls its README's offline test published (@beta)
@parcha/agentrun-pi The /agentrun Pi extension and a Pi-backed node runner Pi 1.0.4 to below 1.4 (CI tests 1.0.4, 1.1.0, 1.2.0 and 1.3.0); a model for live runs; pi-durable for its ./durable entry /agentrun demo in Pi (scripted, no model calls) published (@beta)
@parcha/pi-durable-disk Run a pi-durable agent on a network disk: one owner per run, a fence, a supervisor pi-durable and chord; an Archil account, a disk and an API key none yet published (@beta)
@parcha/pi-browser Your agent gets its own browser, and you can take over and hand it back. Pages it reads are filed as evidence, and failures have typed codes Pi; a provider (a local Chrome needs no key; Browserbase and Kernel need their keys); pi-durable and chord for its ./durable entry its README's no-key command published (@beta)
@parcha/pi-vision Lets a pi agent read documents, images, scans and video within the model's limits, and keeps a priced record of every look nothing for a document's text; Photon or sharp for images; a pi-durable host (pi-durable, chord and pi-ai); a model that looks, for questions about a file examples/vision-agent (one agent that answers questions about files: npm run demo:vision -- examples/document-check runs on fakes, no key; it needs ffmpeg and poppler), then its README's first read published (@beta)
@parcha/pi-transport A pi agent's tools on the machine each step needs: this machine, Docker, or a Daytona or Modal sandbox, behind one Box interface; Jev places each step pi-durable and chord; Docker for the Docker provider; a Daytona key or a Modal client for those; a TypeSafe key for Jev's placement the "A box" example in its README (a local box, no key; a second one needs Docker) published (@beta)
@parcha/pi-git-remote A git repository a host keeps for its agent: commits through git's plumbing, no hook or filter of either repository runs, no push is forced git 2.40+; pi's coding agent only for its ./coding-agent extension its README's quickstart published (@beta)
@parcha/pi-agent-learn An agent that learns in its own git repository: a learn tool, notes curated into commits, saved workflows promoted on receipts pi-durable and chord; git 2.40+; a judge (Jev or a general model) for curation its README's quickstart published (@beta)
@parcha/pi-durable-agent An agent home for pi agents: its definition, skills, saved sign-ins and runs in one directory that also moves as one file, a pack. An agent's sign-ins are saved in its home, so its next run starts signed in pi-durable and chord; nothing else for its quickstart (a browser provider such as pi-browser makes the sign-ins) its README's quickstart published (@beta)
@parcha/agentrun-harness A reference harness: the host we use to run AgentRun demos and tests, meant to be read and forked pi-durable, chord, pi-ai, pi-codemode and typebox; pi-transport only for a demo with boxes its README's first demo held, not published

A held package is built, tested and verified with the others, and its manifest says "private": true; it installs from a packed tarball, not from npm.

Use all of it

One program puts the packages together and runs a job end to end on pi-durable: a durable run, the recovery driver, the node runner, the browser and vision. It uses a scripted model and a fake browser, needs no key, and prints the record and the receipts it cites.

npm ci --ignore-scripts
npm run build
npm run demo:reference

examples/reference/ has the job; the host is the package @parcha/agentrun-harness. What a host supplies lists the seven functions the packages ask a host for, the install order and why, and what the example does not do yet.

What a workflow looks like

The support workflow requires answer text and a source reference. Jev must also answer yes with confidence of at least 0.8. Otherwise, the workflow allows one agent attempt and checks again. If the answer still fails those checks, it escalates for review. You choose the criteria and thresholds for your task.

These are the search and decision nodes from that workflow:

{
  node: 'call', label: 'find-answer', via: 'tool',
  tool: 'help.search', args: { request: '{request}' },
  out: 'Candidate', as: 'answer', deadline_s: 10,
},
{
  node: 'judge', label: 'check-existing-answer',
  state: { request: '{request}', answer: '{answer}' },
  out: 'Fit', as: 'fit',
}

Candidate and Fit refer to schemas in the workflow. Fit defines the question and its yes, no, and uncertain criteria. Code reads the decision and its confidence to choose the next step. Read the complete definition, including the agent and review path.

Write workflows as JSON or use the TypeScript builder and Zod contracts. The builder infers input and output types. The interpreter checks intermediate state paths at runtime. Workflows can call other workflows, map work in parallel, and run bounded loops.

Connect your application

Install the core and Jev adapter in your application with npm install @parcha/agentrun-dsl@0.1.0-beta.27 @parcha/agentrun-jev@0.1.0-beta.27. Then:

  1. Supply adapters. Connect tools through runEffect, your existing agent through runNode, and Jev decisions through createJevRunner() as runJudge.
  2. Define and test the workflow. Write its schemas, steps, thresholds, and review path. Start with fixtures, then evaluate real decisions on labeled cases from your task.
  3. Give your agent a workflow tool. Register a function that calls runWorkflow as one of your agent's tools. Handle the workflow's output, escalation, and errors.

The support integration guide has a config template and live command. Live Jev calls need TYPESAFE_API_KEY from the TypeSafe dashboard, separate from your coding-agent login. Workflows without Jev decisions do not need that key. See host integration for permissions, cancellation, and recovery.

Use it in Pi

With Pi installed (1.0.4 to below 1.4; CI tests 1.0.4, 1.1.0, 1.2.0 and 1.3.0), run these commands in your project:

pi install npm:@parcha/agentrun-pi@0.1.0-beta.27 -l
pi --offline

-l installs in this project; --offline skips startup downloads. Pi asks whether you trust the project before loading its extension. No AgentRun checkout is needed.

  • /agentrun demo loads the scripted research example; /agentrun run repeats it without model calls.
  • /agentrun demo live uses your configured Pi model and Jev.
  • /agentrun status checks setup; /agentrun shows the graph; /agentrun stop requests cancellation.

Once Pi has model access, ask it to build a workflow:

/agentrun Research how this repository handles cancellation. Investigate the runtime and tests separately, then report gaps with file references.

Pi uses the packaged skill to build, inspect, and run the workflow. Run /reload if you install into an open Pi session. Use /agentrun save <name> and /agentrun load <name> for project-local definition revisions. Saves contain neither run input nor execution permission. Pi setup and limits.

More examples

Example What it demonstrates
Support answers Search, Jev checks, optional investigation, review fallback
Research a decision Nested workflows, parallel research, evidence selection, report writing
Rank a list A reusable workflow: Jev scores, code sorts and applies quotas, duplicates are dropped, long lists split themselves
Standalone TypeScript starter Install the packages in your own app; search and screen evidence

Research demo

From the built checkout, run a scripted research workflow: "Should our team move its docs from a wiki into the code repository?"

npm run demo
npm run eval:research

It plans subquestions, researches them in parallel, screens evidence, and writes a report. The evaluation checks six labeled cases with scripted responses. Connect real Jev and Pi models.

Packages, status, and contributing

Package Responsibility
@parcha/agentrun-dsl Define, validate, inspect, and execute workflows
@parcha/agentrun-jev Connect Jev typed decisions
@parcha/agentrun-pi Pi extension and agent runner
@parcha/pi-durable-disk Run pi-durable agents on a network disk (Archil): one owner per run, a fence, and a supervisor
@parcha/pi-browser Your agent gets its own browser (a local Chrome, Browserbase or Kernel), and you can take over and hand it back. Pages it reads are filed as evidence, and failures have typed codes
@parcha/pi-vision Lets a pi agent read documents, images, scans and video within the model's limits; it says when it cannot read something, and keeps a priced record of every look; start at examples/vision-agent (npm run demo:vision -- examples/document-check, free, no key)
@parcha/pi-transport A pi agent's tools on the machine each step needs: this machine, Docker, or a Daytona or Modal sandbox, behind one Box interface; Jev places each step; a strict config, and a conformance suite a vendor can run
@parcha/pi-git-remote A git repository a host keeps for its agent: commits through git's plumbing, a remote on this machine, any https host or code.storage, and a pi coding-agent extension that commits a session's changes
@parcha/pi-agent-learn An agent that learns in its own git repository: notes curated into commits on main, a <learned> section read at a fixed commit, saved workflows promoted and demoted on receipts; start at examples/agent-learn (npm run demo:learn, no key)
@parcha/pi-durable-agent An agent home for pi agents: its definition, skills, saved sign-ins and runs in one directory that also moves as one pack. An agent's sign-ins are saved in its home, so its next run starts signed in
@parcha/agentrun-harness A reference harness: the host we use to run AgentRun demos and tests, meant to be read and forked

Every published package is at one version under npm's beta dist-tag; npm view @parcha/agentrun-dsl dist-tags prints it. The status column of Use one piece says which packages are published. See the changelog and contracts and limits.

Ordinary functions may be enough for a fixed sequence. AgentRun stores the steps in a workflow document that you can inspect, rerun, or call from an agent. Code nodes execute JavaScript with process privileges; untrusted workflow authors require a host-controlled sandbox. Typed decisions and validated output shapes do not prove that an answer is factually correct.

For development setup and checks, see Contributing. Open an issue for bugs or proposals.

Code and documentation use Apache-2.0. Copyright 2026 Parcha Labs, Inc. Dependencies retain their own licenses. Built by Grep.ai.