# Add Jev-powered AgentRun workflows to an existing agent

Build and run a workflow with the actual AgentRun DSL: **Jev routes a request → the selected host-owned agent does the work → uncertain cases stop for review.** AgentRun is a workflow layer; the host retains its agent loop, credentials, tool permissions, budgets, activation, and storage.

This quickstart requires both live Jev decisions and live agent calls. Jev is optional in the general-purpose DSL, but an agent-only workflow does not complete this quickstart.

## Source and release status

Repository: https://github.com/Parcha-ai/agentrun

This guide was checked against source revision ae1ab62074359e16d5cec6efed77dae0552e1829. The reviewed repository describes a private, unpublished release candidate; source access is required while it remains private. npm publication and licensing remain pending. Do not assume packages or the planned native pi extension are already released. Requires Node 22.19+; TypeScript consumers need TypeScript 5.4+.

## 1. Inspect the host and connect Jev

Identify the existing agent loop, model configuration, tool registry, permission checks, and test commands. Preserve those boundaries. Read the repository README, `docs/live-research.md`, `docs/authoring.md`, `docs/host-integration.md`, and `packages/jev/README.md` before writing adapters.

### Set up the user’s Jev API key

Check whether the workflow process already has a nonempty `TYPESAFE_API_KEY`, or an approved server-side secret binding passed as `apiKey`. Check presence only; never print the value. Reuse existing configuration without asking the user to create another key.

If no key is configured, guide the user through these steps before attempting live execution:

1. Open the [Jev / TypeSafe API keys dashboard](https://console.typesafe.ai/keys), sign in or create an account, and create an API key. The [official Jev quickstart](https://docs.typesafe.ai/introduction/quickstart) explains API access.
2. Add the key as `TYPESAFE_API_KEY` in the host’s server environment or secret manager. For local development, use the project’s ignored environment file and ensure the workflow process actually loads it. Keep the value out of source control, browser code, logs, and chat. Use the approved `TYPESAFE_BASE_URL` if the host requires a gateway.
3. Ask the user to confirm that configuration is ready, then recheck presence and make the live connection check below. Do not treat a placeholder or a saved-but-unloaded environment file as configured access.

A Claude Code, Codex, or pi login does not supply Jev credentials. Continue preparing code and offline tests while key setup is pending, but keep live verification pending until access works.

### Build the source and verify access

Follow the current repository README for checkout instructions. At the reviewed revision:

```sh
git clone --branch codex/open-source-beta --single-branch https://github.com/Parcha-ai/agentrun.git
cd agentrun
git checkout ae1ab62074359e16d5cec6efed77dae0552e1829
npm ci --ignore-scripts
npm run build
npm run demo
npm run test:typed-example
```

The demo runs the actual interpreter with fictional sources and scripted responses. It needs no model keys after installation. Check the stop path too:

```sh
npm run demo -- --no-evidence
```

That case should stop before writing findings or a report and exit with code 2. Capture the command's own exit status. These scripted checks verify mechanics; they are not live-provider evidence.

With `TYPESAFE_API_KEY` loaded into the command’s environment, verify Jev access using the repository’s real adapter:

```sh
node examples/jev.mjs billing
```

If the host uses an explicit secret binding instead of an environment variable, run the equivalent `runTriageDemo('billing', createJevRunner({ apiKey: … }))` through the host’s existing secret loader; do not put a literal key in the command.

This makes a live Jev request through `createJevRunner`. Check for a successful structured decision before wiring the full workflow. Missing or rejected credentials must send the user back to key setup; a service or network error must be reported as such. Do not silently substitute fixtures.

For the live workflow, use that same `createJevRunner` from the built `@agentrun/jev` package alongside the host’s configured agent model and authenticated runtime. Do not silently choose a fallback model or provider.

If provider access or authorization is missing, prepare the integration and run its offline tests, then report exactly which live prerequisite is blocked. Do not replace Jev with an agent, a keyword router, or scripted answers and call the live quickstart complete.

## 2. Define the DSL workflow and adapters

Use `defineWorkflow` from `@agentrun/dsl` with `runTypedWorkflow`, or a Workflow v2 document with `runWorkflow`. Import and execute the real built package; do not write a look-alike interpreter or move the routing into application conditionals.

Choose a repeatable procedure with at least two meaningful agent branches. A minimal support example is enough:

1. Validate a ticket input with a declared schema.
2. Use an actual `route` node with clear `billing`, `technical`, and `needs_review` criteria. Set an explicit confidence threshold, for example `unsure: { branch: 'needs_review', gte: 0.7 }`.
3. Put distinct `agent` nodes inside the billing and technical branches, with their own instructions and schema-checked outputs. Both may use the same existing host runtime.
4. Put an `escalate` node in `needs_review`. Unclear requests and confidence below the threshold must reach this branch without calling a specialist agent or producing a draft.
5. Return a declared, validated output on successful branches. Keep drafts separate from external actions; do not claim a refund, message, or other effect happened without a real receipt.

The distinction matters: **`agent`, `decide`, and `extract` use `runNode`; `route`, `judge`, `pick`, and `sift` use `runJudge`.** A `decide` node is not a Jev call. Jev supplies typed answers and probabilities; the DSL applies the route's threshold and executes its chosen branch. Confidence is a model output, not an accuracy guarantee.

Wire the adapters as follows:

- `runJudge`: use the real `createJevRunner(...)` for the workflow's route. Live mode must reach the approved Jev service, without an injected fake client or response. Retain returned model, usage, and request hash when available.
- `runNode`: pass the provided `system` sections, JSON-encoded `user` input, `schema`, and `signal` to the existing agent runtime. Return the schema value directly; the `{ value: ... }` envelope belongs to pi's submission tool. Preserve host tool allowlists and budgets. If a request includes `review`, rejected candidates require feedback in the same agent session. If the adapter cannot continue that session, reject the unsupported request explicitly; do not silently ignore review or restart a new session and claim verification support.
- `runEffect`, if needed: call only the host's approved tools and honor `signal` and `idempotencyKey`. The runtime orchestrates declared deadlines and retries; the host owns effect receipts and reconciliation.
- `onEvent`: record workflow events, especially `route.chosen` and the selected agent's start/completion. Events alone do not provide durable recovery.

For pi, read `packages/pi/README.md`: `createPiRunner` and `authorWorkflow` exist; the native extension remains a design preview. The scripted `node examples/pi.mjs --run` is an optional adapter check, not a substitute for this live Jev-to-agent workflow.

## 3. Verify the path, then expose it as a tool

Keep expected results outside the workflow and model prompts. Write deterministic tests for both normal branches, a low-confidence fallback, an explicit unclear case, malformed input, and adapter failure. Assert that escalation makes zero specialist calls and that a completed run calls only its selected specialist. If using a workflow slice to isolate a node, set both its start and end bounds.

Then run the same workflow with live `createJevRunner` and the configured live agent adapter. Test at least one billing request, one technical request, and one unclear request. Keep the same criteria and threshold throughout. Record actual results, including unexpected routing; do not alter Jev responses or invent confidence to force a passing live test. Test the low-confidence gate deterministically even if the live unclear request confidently selects `needs_review`.

For each live case, retain a redacted report with:

- Workflow revision/digest, input, criteria, and threshold.
- Observed Jev adapter invocation and its returned answer/probabilities; model, usage, and request hash when reported. Mark unavailable metadata as absent.
- The actual `route.chosen` event: proposed branch, branch taken, and whether the uncertainty fallback was used.
- Selected host agent label, actual provider invocation, validated output, or escalation with zero agent calls.
- Test assertions and pass/fail results. Separate scripted tests from live runs; a schema pass alone does not prove the draft is factually correct.

Register a callable workflow tool in the existing host, or invoke it directly from application code. Tool registration alone is not proof that the model can discover and call it: wire it into the host's actual tool exposure and test that separately if claiming agent-initiated use. Return validated output or explicit escalation to the caller.

Inspect workflows before execution. Workflow JavaScript is trusted code, not a sandbox; validation may execute probes. Preserve host permissions and avoid retrying external effects with an unknown outcome. Existing interpreters may support only a subset of the vocabulary: matching JSON versions do not establish capability or recovery compatibility.

Deliver the workflow definition, adapter wiring, tests, observed Jev-to-agent evidence, and any blocked prerequisites. Do not activate or publish the integration without the user's authorization.

## Documentation

- Authoring: https://github.com/Parcha-ai/agentrun/blob/ae1ab62074359e16d5cec6efed77dae0552e1829/docs/authoring.md
- Harness integration: https://github.com/Parcha-ai/agentrun/blob/ae1ab62074359e16d5cec6efed77dae0552e1829/docs/host-integration.md
- Core API: https://github.com/Parcha-ai/agentrun/blob/ae1ab62074359e16d5cec6efed77dae0552e1829/packages/dsl/README.md
- Jev adapter: https://github.com/Parcha-ai/agentrun/blob/ae1ab62074359e16d5cec6efed77dae0552e1829/packages/jev/README.md
- pi SDK: https://github.com/Parcha-ai/agentrun/blob/ae1ab62074359e16d5cec6efed77dae0552e1829/packages/pi/README.md
- Live research: https://github.com/Parcha-ai/agentrun/blob/ae1ab62074359e16d5cec6efed77dae0552e1829/docs/live-research.md
- Release status: https://github.com/Parcha-ai/agentrun/blob/ae1ab62074359e16d5cec6efed77dae0552e1829/docs/releasing.md