---
name: agents-and-humans
description: Add the Agents & Humans components (Plan Preview, Approval Gate, Progress Trace, Review Receipt) to a React or Next.js app and wire them on the Agents & Humans Interaction Contract. Use when someone asks to add plan review, approval before an agent acts, a live trace of an agent run, a run receipt, or "the agent-workflow bundle" to their app, or to install anything from the @agentsandhumans registry.
license: MIT
---

# Agents & Humans: install and wire the agent workflow

You are adding the person-in-the-loop parts of an agent run to someone else's app. The person accepts a plan, approves the action the server issued for it, watches the run, and reviews one receipt. The components come from the shadcn registry at `https://agentsandhumans.ai/api/registry/`, as source code the app owns.

Work in five steps, in order. Do not skip the first one.

## 1. Inspect the app first (read only)

Change nothing until you can answer each point below. `references/inspect.md` has the commands and a note template.

- **Framework.** Next.js App Router, Next.js Pages Router, Vite with React, or something else; the React version; whether the app sits under `src/`.
- **shadcn.** Is there a `components.json`? Read its `aliases` (where `components` and `lib` land) and the `@/*` path in `tsconfig.json`.
- **Design tokens.** The file that holds the CSS variables (`globals.css`, a Tailwind theme, a tokens file), and the dark mode switch: a `.dark` class, `[data-theme='dark']`, or the media query.
- **Existing components.** Search for approval dialogs, plan lists, step logs, tool-call views, and code that already calls an agent or the AI SDK. Reuse what is there. Do not add a second approval flow beside one that works.
- **Server and auth.** The folder for route handlers or API routes, and the code that tells the server who the signed-in person is.
- **Git.** Run `git status`. If the tree has changes you did not make, stop and ask before going on.

Write the answers in a short inspection note and show it to the person with the list of files you plan to add or change. Wait for a yes if the list touches any file that already exists.

## 2. Install from the registry

```bash
npx shadcn@latest add https://agentsandhumans.ai/api/registry/agent-workflow.json
```

This brings the Interaction Contract, Plan Preview, Approval Gate and Progress Trace, then the bundle: `components/agent-workflow.tsx`, `components/review-receipt-core.tsx`, `lib/agent-workflow-host.ts`, an example page at `app/agent-workflow/page.tsx` and its server at `app/api/agent-workflow/route.ts`. One component on its own works too: `.../api/registry/approval-gate.json`.

- With no `components.json`, do not run `shadcn init`: it rewrites the global stylesheet. Write the minimal `components.json` from `references/inspect.md` instead, and tell the person.
- With a `src/` app or Pages Router, move the example page and route to where the app keeps them, and fix the two import paths. Say that you did.
- Read `references/install.md` when `shadcn add` fails or asks a question.

## 3. Wire it on the contract

Read `references/contract.md` before you write wiring code. The rules:

- One `runId` per agent run, the same on each component.
- Pass the plan id to the Approval Gate as `correlationId`, so the approval points at the plan.
- Give each Progress Trace step the `planStepId` it carries out.
- Send each component's `onEvent` to one log the host keeps on the server. The Review Receipt reads that log.
- Build the `ActionRequest` on the server from the accepted plan, and store it. A changed plan is a new request version.

`references/wiring.md` has the recipe for Next.js and for a Vite app with its own API server. Start from the example page and route; replace the demo run with the app's agent, and the demo store with the app's database.

## 4. Keep the boundaries

These hold in each install. `references/boundaries.md` says how to check each one.

1. **The server verifies each approval.** A browser event records what the person clicked; it authorizes nothing. The server checks the decision against the request id and version it issued, names the person from the session, stores a receipt, and passes `serverReceiptId` back. Nothing runs before that, and the run checks the receipt again before it acts.
2. **The server redacts secrets in traces.** Run each trace frame through `redactTrace` (or the app's own redactor) on the server, before it reaches the browser, the event log or a log file. Keep secrets out of `ActionRequest.args`.
3. **Change only what the task needs.** Add the registry files and the wiring. Do not reformat, rename, upgrade dependencies, change lint or TypeScript settings, or edit files the task does not need. Theme through a new CSS file that sets the `--ah-*` and `--actor-*` variables from the app's tokens; leave `tokens.css` as installed.
4. **Leave the demo parts marked.** The example's in-memory store and `signedInPerson` stub are for the demo. Keep their comments, and list them for the person as work left to do.

## 5. Prove it, then report

- Run the app's own checks: typecheck, lint and build, with the scripts in `package.json`.
- Start the app and walk `/agent-workflow` (or the page you wired): accept the plan, approve, wait for the gate to read Verified, let the run finish, open Inspect and check no secret shows, accept the run on the receipt.
- Run `git status` and `git diff --stat`. Each changed file should be on the list you showed in step 1.

Report: what you installed, the files added and changed, the checks you ran and their results, and what the person still has to do (database for the approval store, real auth in place of the stub, their agent in place of the demo run).