# openadapt-agent

> Your AI agent decides what to enter. OpenAdapt enters it in the app and checks that it saved.

Use this when an AI agent has decided what to enter in an app with no usable API, such as an EMR, a payer portal, or a desktop or Citrix app. OpenAdapt enters the values in the same screens staff use, on a computer the customer controls, then reads the saved record back. When something doesn't match, it stops and a person decides. A normal run makes no AI model calls.

## The contract: three tools

- `list_workflows`: each workflow's `name`, `purpose`, `done_means`, and typed `inputs` (types, enums, formats).
- `run_workflow(workflow, inputs, request_id, wait_seconds?)`: one piece of work. `request_id` is the caller's own id and is required. The same `request_id` returns the latest result and never writes twice.
- `get_run(run_id, wait_seconds?)`: the result of a run that returned `outcome: running`.

Every result has `outcome`, `safe_to_retry`, `what_happened` (one plain sentence), `next_action`, `proof`, `run_id`, and `request_id`. Tools publish an MCP `outputSchema` and return `structuredContent`.

## Outcomes (the honesty rules)

- `done`: saved and checked by reading the record back. `proof` is `local` (checked on the customer's computer), `sealed` (signed receipt), or `simulated` (sandbox, no app opened). A verified local run is done; it is never reported as an error.
- `needs_review`: stopped before a save; a person decides. Nothing was written, unless `record_changed` is `unknown` (a run waiting for a person to approve a save may have made an earlier one). Don't start the same work again.
- `not_sure_if_saved`: a save may have gone through. Never retry. A person checks the record. Never tell the user nothing changed.
- `did_not_run`: this call wrote nothing. Fix the cause and retry with the same `request_id` when `safe_to_retry` is true. After `request_id_conflict`, an earlier request with the same `request_id` may have saved; call `get_run` with `first_run_id` to see it.

Only `done` is a success. Results come from openadapt-flow's `transaction_outcome`, never from the coarse halt label alone.

## Try it

`openadapt-agent serve` with no flags is a sandbox: one workflow, `add_triage_note`, on MockMed, a synthetic clinic app. The `sandbox_case` input picks the outcome: `normal` (done), `duplicate_record` (needs_review), `false_saved_banner` and `timeout_after_save` (not_sure_if_saved), `app_offline` (did_not_run). Install the `tutorial` extra to drive the synthetic app with the real engine; otherwise results are simulated and say so.

- From GitHub (before 2.1.0 is on PyPI): `claude mcp add openadapt -- uvx --python 3.12 --from git+https://github.com/OpenAdaptAI/openadapt-agent openadapt-agent serve`
- From PyPI 2.0.2 on: `claude mcp add openadapt -- uvx --python 3.12 openadapt-agent serve`

## Modes and older surfaces

- `openadapt-agent serve --mode production --bundles <dir>`: run an operator's compiled workflows through the governed `openadapt-flow run` CLI. `--bundles <dir>` alone stays read-only. `--mode attended` adds decisions on paused runs by a person at that computer. `--mode sandbox` is the default without `--bundles`.
- Older flags still work: `--allow-run` (same as `--mode production` with `--bundles`, or the sandbox without), `--tutorial` (the sandbox), `--allow-attended-actions` (part of `--mode attended`).
- Older tools stay registered with `--bundles`: `get_workflow`, `get_run_report`, `list_needs_attention`, `get_attention_item`, and deprecated per-workflow `run_workflow_<opaque-id>` tools (no request id; they now also return `outcome` and `safe_to_retry`).
- Attended actions: `continue_attention` (after a person completes the paused task; Flow rechecks and resumes without repeating it), `skip_attention` (declared skip only), `reject_attention` (ends the run; earlier steps may still have effects), `teach_attention`, `escalate_attention`. Each needs an exact capability digest, a stable idempotency key, a confirmation, and MCP form elicitation; otherwise use Flow's attended console.
- `openadapt-agent serve --authoring`: local first-demo tools `observe`, `start_record`, `click`, `halt`, and more over stdio. It doesn't enable runs and opens no HTTP listener. `openadapt-agent authoring connect <openadapt://runner or pack URL>`: outbound mailbox client for hosted ChatGPT.com and Claude.ai. Hosted chats can't click the user's GUI; send them to https://openadapt.ai/start. Hosted MCP is `https://openadapt.ai/mcp`.
- `openadapt-agent emit-skill <bundle> --out <dir>`: a PHI-safe Agent Skill per workflow (no recorded values, step text, or secrets; one description per workflow).

## Workflow cards

An operator can add `openadapt-card.json` next to a bundle's `workflow.json` with `name`, `purpose`, `done_means`, and input descriptions. Card text reaches the calling agent; it must not contain patient details.

## Product state

Standard and Regulated runs need a workflow admission; Demo and the synthetic sandbox may run without one. Target admissions: https://openadapt.ai/production-lifecycle.json (seven, remote-safe-synthetic). Workflow admissions: https://openadapt.ai/production-workflow-admissions.json (seven, 0.0.0-synthetic, not a customer job). A missing or expired admission means not actively admitted.

## Public capability vs private artifact

- The package and MCP server are the public OpenAdapt capability. Install from PyPI as `openadapt-agent`.
- A customer's compiled workflow bundle is their private artifact, supplied at server start with `--bundles`. It is never embedded in the package, `server.json`, or any registry listing. The sandbox generates its synthetic workflow on the fly.

## Key documents

- [README](https://github.com/OpenAdaptAI/openadapt-agent/blob/main/README.md): what it does, the contract, the sandbox, developer setup.
- [docs/DESIGN.md](https://github.com/OpenAdaptAI/openadapt-agent/blob/main/docs/DESIGN.md): architecture, the result contract, security model.
- [docs/DISTRIBUTION.md](https://github.com/OpenAdaptAI/openadapt-agent/blob/main/docs/DISTRIBUTION.md): registry artifacts and the public-vs-private distinction.
- [server.json](https://github.com/OpenAdaptAI/openadapt-agent/blob/main/server.json): official MCP registry manifest.
- [manifest.json](https://github.com/OpenAdaptAI/openadapt-agent/blob/main/manifest.json): portable MCPB launch config.

## Related

- [openadapt-flow](https://github.com/OpenAdaptAI/openadapt-flow): the demonstration compiler and runtime this package connects to.
- [OpenAdapt](https://github.com/OpenAdaptAI/OpenAdapt): the umbrella project.
- [docs.openadapt.ai](https://docs.openadapt.ai): OpenAdapt documentation.
