Run a workflow with Jev and your agent

Connect the homepage support workflow to real Jev decisions, your existing agent, and your support tools. It finds an answer, checks whether it resolves the request, and calls your agent once if investigation is needed. Jev checks that result before the workflow returns an answer or escalates for review.

This setup requires a Jev API key and an authenticated agent runtime. Your host keeps its model selection, tool permissions, account access, and budgets.

Using Pi?

Install the native AgentRun extension for Pi in your project:

pi install npm:@parcha/[email protected] -l

It uses your current Pi model and authentication. Configure your Jev key for decision steps, then follow the Pi setup guide. Standard Pi setup does not require cloning this repository or writing custom adapters. The steps below connect the standalone support example to another harness.

What you need

• Node 22.19+ and npm. TypeScript consumers need TypeScript 5.4+; the support example uses JavaScript.
• Jev access. Reuse a server-side TYPESAFE_API_KEY, or get a key from TypeSafe.
• Your configured agent and tools. Supply help.search and a read-only support.read tool with access to data this host is allowed to read.

AgentRun 0.1.0-beta.2 is published on npm under the @parcha scope. The release source uses Apache-2.0. The pi extension and SDK are published too; pi setup is available if that is your host.

Install

This quickstart pairs the published 0.1.0-beta.2 packages with source tag v0.1.0-beta.2. Use this pair throughout; the repository’s main branch may document unreleased APIs.

In the application you want to connect:

npm install --save-exact @parcha/[email protected] @parcha/[email protected]

The complete support example and its runner live in the repository. Clone the matching release into a separate directory, then build:

git clone --branch v0.1.0-beta.2 --single-branch https://github.com/Parcha-ai/agentrun.git
cd agentrun
# With nvm: nvm install && nvm use
npm ci --ignore-scripts
npm run build

Run the following commands from that release checkout. git describe --tags --exact-match should report v0.1.0-beta.2. The workflow is examples/support-answer.mjs; you do not need to download an overlay or replace repository files.

Connect Jev and your agent

Check whether TYPESAFE_API_KEY is already available to the workflow's server process without printing its value. Reuse an existing key. If it is missing, create one in the TypeSafe dashboard and follow the official Jev setup guide.

Store the key in your host's secret configuration or an ignored environment file. A saved .env file needs an explicit loader; it is not loaded automatically. A Claude Code, Codex, or pi login does not provide Jev access. Keep the key out of source control, browser code, and chat. An approved gateway can use TYPESAFE_BASE_URL.

Copy the trusted server-side config template:

cp examples/support-answer-config.example.mjs support.config.mjs

Replace both stubs with your existing host adapters:

Adapter	Required behavior
runEffect(params)	Dispatch help.search using params.input.request. Return { text, sources }. If nothing is found, return { text: "", sources: [] }.
runNode(params)	Forward the full request to your authenticated agent: system, user, schema, tools, signal, and review when present. Return the parsed { text, sources } value.

Register the read-only support.read tool in your host and scope it to the authenticated user. Preserve tool allowlists, model selection, turn limits, and budgets. Honor cancellation. If a review rejects a submission, continue the same agent session or explicitly reject unsupported review; do not discard it.

The runner supplies runJudge using the real createJevRunner() from @parcha/agentrun-jev. It does not accept a replacement judge or fake transport in the config. Optional jev settings are apiKey, baseURL, model, timeoutMs, and maxAttempts; the config's top-level timeoutMs defaults to a 60-second whole-run limit.

See host integration for the full adapter contract. The published pi SDK can supply an agent runner; other runtimes need an adapter to their existing interfaces. Installing the packages alone does not connect support tools or grant model access.

Run the live workflow

With the key loaded and both adapters implemented:

npm run demo:support -- payment --config ./support.config.mjs

If the key is stored in a local .env file, load it explicitly:

node --env-file=.env examples/run-support-answer.mjs payment --config ./support.config.mjs

Use a request your connected tools can investigate. Save this shape as request.json:

{ "request": "My payment failed. Can you investigate?" }

Then run:

npm run demo:support -- --config ./support.config.mjs --input ./request.json

Keep the same support-answer.mjs definition. An accepted help answer takes tool → judge; an investigation takes tool → judge → agent → judge. Empty search results enter the investigation path. At most one investigation is allowed. A nonempty answer with source references and a yes judgment at confidence 0.8 or higher passes; an insufficient or uncertain second judgment escalates.

The CLI identifies live Jev + configured host adapters and reports the workflow digest, observed calls, decision probabilities, and status. It omits customer request and answer text, source references, and raw provider errors. Model and usage fields stay null when not reported. Exit codes are 0 for completion, 2 for escalation, and 1 for failure.

Inspect the actual answer through your host. Live judgments may differ from fixture expectations; report what happened. A typed answer and a source reference do not prove factual correctness. Evaluate the criteria and threshold on independently labeled cases from your task. Missing access or failed provider calls leave live verification incomplete; there is no scripted fallback.

Let your agent call the workflow

Register a host tool that calls runLiveSupport(input, config, { signal }). It returns both result—the validated answer or escalation—and report, the redacted trace. Handle escalation explicitly. Your host decides whether to send a reply or change an account; this example does neither.

Optional: verify the scripted baseline

To check interpreter behavior separately from live integration:

npm run demo:support
npm run test:support

These commands use prewritten tool, Jev, and agent responses. They make no live calls and are not a working connection to your agent or a model-quality benchmark.

Scenario	Agent adapter calls	Jev adapter calls	Result
password	0	1	Complete
invoice	0	1	Complete
payment	1	2	Complete
unresolved	1	2	Escalated

The all-case demo exits 0 when every expected outcome matches. npm run demo:support -- unresolved exits 2. These counts describe adapter invocations, not the turns, tool calls, tokens, or spending inside an agent.

Repository integration guide · Workflow source · Jev reference