# Agent interaction patterns

Vloora's browser reference for reviewing an AI agent's recommendation, approving an exact request, and checking who reported the result. Version 0.1, October 19, 2026.

The example runs locally without a model account or service credentials. Provider acknowledgments and outcomes are simulated. Read the [public guide](https://vloora.com/guides/agent-interaction-patterns/) for the interaction rationale, or [PATTERNS.md](PATTERNS.md) for the underlying behavior rules.

## Run the example locally

From this directory:

```sh
python3 -m http.server 8080
```

Open `http://localhost:8080` and choose a streetlight report, subscription cancellation, or train booking. The browser loads ordinary JavaScript modules, with no build process. To run the automated tests in a second terminal:

```sh
npm test
```

The tests require Node.js 20 or newer. The static files can also be served together from a regular web host; keep the directory structure and relative file paths intact.

## Check the approval rules

The train example begins with a $120 request and a mandate allowing up to $150. These changes expose different boundaries.

1. Approve $120, then change it to $121. The result is `APPROVAL_MISMATCH` until the changed request is approved.
2. Approve $151. The result is `OVER_LIMIT` because approving an individual request cannot increase the mandate.
3. Change the receiving service to one outside the mandate. The result is `WRONG_RECIPIENT`.
4. Reset, approve, and simulate sending a request. Check the event record before and after the simulated service acknowledgment. Completion remains unconfirmed.
5. Simulate completion, dispute the report, and export the JSON. Both claims remain attributed in the record.

Use [AUDIT.md](AUDIT.md) to record observable results and failures, including keyboard and mobile behavior.

## Files in the kit

| File | Purpose |
| --- | --- |
| `lib/authority.mjs` | Check a request against a mandate and the person's exact approval |
| `lib/records.mjs` | Append simulated events, report outcome states, and export a record |
| `examples/*.json` | Source inputs for a streetlight report, subscription cancellation, and train booking |
| `index.html`, `app.mjs`, `styles.css` | Browser reference with responsive controls |
| `PATTERNS.md` | The behavior rules behind the interface |
| `AUDIT.md` | Evaluation tasks and observable acceptance conditions |
| `tests/*.test.mjs` | Native Node tests for permissions and records |

The permission functions have no browser dependency:

```js
import { makeDecision, checkPermission } from './lib/authority.mjs';

const decision = makeDecision(request, 'approved');
const result = checkPermission(request, mandate, decision);
if (!result.allowed) console.log(result.code);
```

## What a real integration requires

The example stores approval decisions in memory and uses deterministic JSON to detect changes. That representation is useful for testing an interface; it is not an authenticated signature. The local record cannot prove the identity of an external service, enforce an actual network request, or verify delivery. Exported provider events are explicitly labeled as simulated.

When adapting these modules, enforce permission at a trusted service or gateway before an external operation, authenticate receiving-service responses, and preserve durable event IDs through retries. A different assistant may read a historical export with the person's permission, but that export does not authorize new actions.

## References

- Microsoft, [HAX Toolkit](https://www.microsoft.com/en-us/haxtoolkit/), guidance for human-AI interaction
- Google and contributors, [A2UI](https://github.com/a2ui-project/a2ui), format for agent-generated interfaces
- CopilotKit and contributors, [AG-UI](https://docs.ag-ui.com/), communication between agents and user interfaces
- Model Context Protocol, [elicitation](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation), user input during tool interactions
- Internet Architecture Board, [RFC 8890: The Internet is for End Users](https://www.rfc-editor.org/rfc/rfc8890), August 2020
- World Wide Web Consortium, [Ethical Web Principles](https://www.w3.org/TR/ethical-web-principles/), December 2024

## Submit an evaluation

Record the scenario, expected behavior, observed behavior, and the effect on the person's decision. Include a redacted event export when it helps reproduce the problem. The [evaluation checklist](AUDIT.md) gives the full set of tasks.

The kit is MIT-licensed under [LICENSE](LICENSE). A separate public issue tracker for improvements is tracked in Vloora issue #85; the underlying Vloora repository is private.