# 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](https://pi.dev/packages/@parcha/agentrun-pi) in your project:

```sh
pi install npm:@parcha/agentrun-pi@0.1.0-beta.2 -l
```

It uses your current Pi model and authentication. Configure your Jev key for decision steps, then follow the [Pi setup guide](/docs/pi#install). 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](https://console.typesafe.ai/keys).
- **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](https://github.com/Parcha-ai/agentrun/tree/v0.1.0-beta.2) uses Apache-2.0. The pi extension and SDK are published too; [pi setup](/docs/pi) 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:

```sh
npm install --save-exact @parcha/agentrun-dsl@0.1.0-beta.2 @parcha/agentrun-jev@0.1.0-beta.2
```

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

```sh
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](https://console.typesafe.ai/keys) and follow the [official Jev setup guide](https://docs.typesafe.ai/introduction/quickstart).

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:

```sh
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](/docs/host-integration) for the full adapter contract. The published [pi SDK](/docs/pi#sdk-embed-the-runner) 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:

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

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

```sh
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`:

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

Then run:

```sh
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:

```sh
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](https://github.com/Parcha-ai/agentrun/blob/v0.1.0-beta.2/docs/support-quickstart.md) · [Workflow source](/source/examples/support-answer.mjs) · [Jev reference](/docs/jev)