OpenAdapt: your agent decides, OpenAdapt enters it and checks it saved

OpenAdapt Agent

このリポジトリは OpenAdapt モノレポ（packages/agent）に移行しました。アーカイブ済みで読み取り専用のため、課題や PR はそちらに投稿してください。PyPI パッケージ名 openadapt-agent に変更はありません。

何を入力するかは AI エージェントが決めます。OpenAdapt はアプリに入力し、保存されたことを確認します。

エージェントが紹介状、受付フォーム、承認書を読み、記録に何を入力するか判断する一方で、使える API のないアプリへの入力は人が行っている場合にご利用ください。電子カルテ（EMR）や保険者のポータルがその例です。このパッケージは、その入力を行うためにエージェントが呼び出すツールです。

• 人またはエージェントが、実際のアプリでタスクを OpenAdapt に示します。OpenAdapt はその手順を再生します。デフォルトでは、実行時に AI モデルの呼び出しは発生しません。
• 入力する前に、OpenAdapt は正しい記録が開いていることを確認します。保存後には、記録を読み戻します。
• エージェントには、完了して確認済み、保存前に停止、記録の確認が必要、未実行の4つのいずれかの結果が返されます。OpenAdapt が保存を確認できない場合はその旨を伝え、人が記録を確認します。
• アプリをすでに開ける、お客様のコンピューター上で動作します。OpenAdapt を起動して直接やり取りするため、エージェント、またはエージェントに代わって動作する小さなプログラムも、そのコンピューター上で実行される必要があります。エージェントが自社のクラウドで動作している場合は、ホスト型の方法についてお問い合わせください。

エージェントが現在スタッフに任せているタスクを1つ選び、連携方法についてご相談ください。エンジニアは、まずサンドボックスを試すことができます。

エージェントにはマウスではなくプログラムを渡す

エージェントはスクリーンショットをモデルに送ってクリックするのではありません。学習済みのワークフローを1つの型付きツールとして呼び出し、OpenAdapt が毎回同じ手順を実行します。デフォルトでは、エージェントに返されるのは結果と件数であり、画面や記録された値ではありません。

openadapt-agent serve --mode production --bundles <bundle or directory of bundles>
openadapt-agent emit-skill <bundle> --out ~/.claude/skills

3つのステップで試すでは、アカウント不要でサンドボックスを実行できます。独自のワークフローを提供するとエージェントスキルを作成するでは、2種類のコマンドを説明しています。

お客様のチームに起きる変化

ステップ	現在	OpenAdapt 導入後
文書を読み、入力内容を決める	エージェント	エージェント
アプリを開き、正しい記録を探す	スタッフ	OpenAdapt（入力前に正しい記録か確認）
値を入力して保存する	スタッフ（エージェントの出力を再入力）	OpenAdapt（スタッフと同じ画面を使用）
保存を確認する	スタッフ（再度確認する場合）	OpenAdapt（完了を報告する前に記録を読み戻す）
内容が一致しない場合	入力中にスタッフが気づくか、後で誰かが見つける	OpenAdapt が保存前に停止し、実行結果は人の確認を待つ
スタッフが対応するもの	すべての文書	停止した実行と確認が必要な記録。通知は送られないため、誰かが停止した実行の一覧を確認します。

規模の参考として、病院で行われた2件の時間調査では、ファックスで届いた紹介状1件を電子記録に入力するのに約10〜12分かかるとされています（UCSF、JAMIA Open 2020；Calderdale and Huddersfield NHS Foundation Trust、HFMA 2024）。導入環境で測定するまでは、削減時間の数値を公表しません。

誰が何を構築するのか

flowchart LR
    A["Your agent reads the document<br/>and picks the values"]
    B["OpenAdapt enters them in the app<br/>on your customer's computer<br/>and reads the record back"]
    C["Your agent acts<br/>on the outcome"]
    D["A person at that computer<br/>decides or checks the record"]
    A -->|"workflow, inputs, request_id"| B
    B -->|"one outcome per request"| C
    B -.->|"needs_review or not_sure_if_saved"| D

お客様が構築するもの	OpenAdapt が提供するもの
ドキュメントを読み、何を入力するか判断するエージェント	実際のアプリで人またはエージェントがタスクを実演して学習したワークフロー
独自の request_id を指定して run_workflow を呼び出す処理	お客様のコンピューター上での実行。入力前にレコードを確認し、保存後にもレコードを確認します
各結果に対して製品が行う処理	リクエストごとに1つの結果を返し、エージェントが同じ request_id を再送しても二重入力しません
4つの結果に対するテスト	それぞれの結果を要求に応じて返すサンドボックス

お客様は、実行を停止する際に使うコンピューターと担当者を用意します。人またはエージェントが、Web アプリ、ネイティブの Windows アプリ、Citrix またはリモートデスクトップ上でタスクを実演します。実行前に担当者が結果を承認します。最初のワークフローを記録するをご覧いただくか、設定についてお問い合わせください。

3ステップで試す

サンドボックスは、アカウント不要の練習用サーバーです。テスト用の診療所アプリ MockMed で、最初の紹介患者にメモを追加する add_triage_note というワークフローが1つあります。患者データは架空のものです。

Claude Code（サインイン済み）と uv が必要です。別のクライアントや独自のコードを使う場合は、独自のエージェントを接続するをご覧ください。

1. サンドボックスサーバーを追加します。Claude Code は現在のフォルダーにのみ設定を保存します。

   claude mcp add openadapt -- uvx --python 3.12 openadapt-agent serve
   

2. 同じフォルダーで claude を実行して Claude Code を起動します。Claude Code がサーバーを起動します。

3. 「OpenAdapt を使って、リクエスト ID demo-0001 でトリアージメモ『Synthetic: recheck blood pressure in 2 weeks』を追加して」と依頼します。

エージェントは list_workflows を呼び出し、続いて次の引数で run_workflow を呼び出します。

{"workflow": "add_triage_note", "inputs": {"note": "Synthetic: recheck blood pressure in 2 weeks"}, "request_id": "demo-0001"}

結果は次のようになります（一部のフィールドは省略しています）。

{
  "outcome": "done",
  "label": "Done and checked",
  "safe_to_retry": false,
  "what_happened": "Simulated sandbox result (no app was opened): Saved the change and read the record back to confirm it.",
  "next_step": "none",
  "proof": "simulated",
  "run_id": "run-31ecb9d66db84f1aba8cb5f6",
  "model_calls": 0
}

このインストールでは MockMed を開かずに各実行をシミュレートし、すべての結果にその旨が示されます。実際のエンジンが処理を行う様子を見るには、実際のエンジンで MockMed を操作するをご覧ください。

openadapt-agent は PyPI からインストールされ、openadapt-flow 2.1.0 以降が必要です。openadapt-flow も PyPI で公開されており、openadapt-agent と一緒にインストールされます。未リリースの変更を試すには、パッケージ名の代わりに --from git+https://github.com/OpenAdaptAI/openadapt-agent を使用してください。

すべての結果を確認する

入力に sandbox_case を追加し、毎回新しい request_id を指定すると、各ケースを試せます。たとえば、「次はリクエスト ID demo-0002 で false_saved_banner ケースを試して」と依頼します。

sandbox_case	outcome	MockMed の動作
normal（デフォルト）	done	メモを保存し、レコード確認でそのメモが見つかります。
duplicate_record	needs_review	同じ紹介患者を2回表示するため、OpenAdapt はどのレコードを開くべきか判断できません。保存前に停止します。
false_saved_banner	not_sure_if_saved	保存済みのメッセージを表示しますが、メモは保存されていません。
timeout_after_save	not_sure_if_saved	メモを保存した後、エラーでタイムアウトします。
app_offline	did_not_run	応答がないため、何も開始されません。

サンドボックスはセッションをまたいで各 request_id を記憶します。使用済みの request_id を同じ入力とともに送信すると、以前の結果が返されます。新しい sandbox_case など、異なる入力とともに送信すると、理由 request_id_conflict を伴う did_not_run が返されます。最初からやり直すには、~/.openadapt/agent-sandbox を削除するか、OPENADAPT_AGENT_SANDBOX_DIR に空のフォルダーを指定してください。

実際のエンジンで MockMed を操作する

tutorial エクストラを使うと、OpenAdapt の背後にあるエンジンである openadapt-flow（Flow）が、非表示のブラウザーで MockMed を操作します。サンドボックスサーバーを次のサーバーに置き換えてください。

claude mcp remove openadapt
claude mcp add openadapt -- uvx --python 3.12 --from 'openadapt-agent[tutorial]' openadapt-agent serve

サーバーが起動すると、Flow はワークフローを一度記録し、必要に応じてブラウザーをダウンロードします（約 300 MB）。最初のリクエストはその間待機します。Mac でのテストでは、最初のリクエストに約 80 秒かかりました。呼び出しは 60 秒後に running を返し、エージェントは結果を取得するために get_run を呼び出しました。セットアップに 15 分以上かかると、リクエストは did_not_run で終了します。Flow では、done の結果の proof は "simulated" ではなく "local" になります。

シミュレーション用サンドボックスでは、list_workflows の結果に同じコマンドが表示されます。

エージェントが受け取る内容

outcome は 4 つの最終値のいずれかです。実行中は running になります。

outcome（ラベル）	発生したこと	エージェントが次に行うこと
done（完了し、確認済み）	OpenAdapt が値を保存し、レコードを読み戻しました。	リクエストを完了としてマークし、run_id を保持します。再送信しないでください。
needs_review（保存前に停止）	保存前に停止し、顧客のコンピューターで誰かが判断するまで実行が待機します。record_changed が unknown の場合を除き、何も書き込まれていません。実行が保存の承認を待機している間（ラベルは「承認待ち」）、その実行内で先に行われた保存が完了している可能性があります。	同じ作業を再度開始しないでください。後で get_run を呼び出して、判断内容を確認してください。
not_sure_if_saved（レコードを確認）	保存が完了した可能性がありますが、OpenAdapt は確認できませんでした。	絶対に再試行しないでください。アプリでレコードを人に確認してもらってください。
did_not_run（未実行）	この呼び出しでは何も書き込まれていません。request_id_conflict の場合、同じ request_id を使った以前のリクエストで保存が完了している可能性があります。	safe_to_retry が true の場合は、原因を修正して同じリクエストを再送信してください。それ以外の場合は next_action に従ってください。
running（実行中）	実行は wait_seconds（デフォルトは 60）以内に完了しませんでした。	outcome が変わるまで、run_id を指定して get_run を呼び出してください。

outcome と safe_to_retry に基づいて処理を分岐します。next_step には次のアクションを固定コードで示すため、コードで next_action を解析する必要はありません。値は none、call_get_run、wait_for_person、check_record、fix_inputs、fix_setup、retry のいずれかです。

リクエストを再送信する

request_id は、紹介 ID など、リクエストに付ける独自の ID です。患者の詳細情報を含めないでください。1 つのリクエストは、1 つの request_id、1 つのワークフロー、1 組の入力で構成されます。

• 同じリクエストを再送信しても、値が 2 回入力されることはありません。最新の結果が replayed: true として返されます。
• その結果が safe_to_retry: true の did_not_run だった場合、request_id ごとに最大 5 回まで、新しい試行が開始されます。
• invalid_input の後は、入力を修正して同じ request_id で再送信できます。それ以外の再試行可能な結果の後は、同じ入力を送信してください。
• 使用済みの request_id で異なるワークフローまたは異なる入力を送信すると、request_id_conflict を伴う did_not_run が返されます。新たな処理は実行されず、以前のリクエストで保存が完了している可能性があります。結果の first_run_id を指定して get_run を呼び出し、そのリクエストの状況を確認してください。
• not_sure_if_saved を解除するツールはありません。確認した人が作業の続行が必要だと判断した場合は、新しい request_id を使って新しいリクエストとして送信してください。

二重入力を防ぐチェックの対象は、1 つの実行フォルダーです。サーバーオプションの設定にある --runs-dir を参照してください。

ほかのフィールドを確認する

• label： 「完了し、確認済み」など、表示できる短いステータスです。
• reason： 原因を示す固定リスト内のコードです。たとえば、invalid_input や request_id_conflict などがあります。すべてのコードは contract.py の REASONS に記載されており、docs/DESIGN.md では各コードの選び方を説明しています。
• what_happened と next_action：人に表示できる定型文です。入力値や画面上のテキストが含まれることはありません。
• proof：顧客のコンピューターで確認済みの done には local、アプリを開かなかったサンドボックス実行には simulated、それ以外のすべての結果には none が設定されます。
• model_calls：Flow に到達した実行で、実行中に行われた AI モデル呼び出しの回数です。モデルグラウンディング（クリックする場所を AI モデルに尋ねるフォールバック）が有効でない限り、0 です（セキュリティを参照）。
• record_changed：yes、no、または unknown です。OpenAdapt が何も書き込まれていないことを確認できる場合に限り、no になります。request_id_conflict の場合、先行するリクエストによって保存された可能性があるため、unknown になります。
• needs_repair：実行があるステップで停止した needs_review または did_not_run の結果に含まれます。ステップ ID、理由、および一度限りの repair_token が示され、画面は含まれません。修復用の画面アクセスを人が有効にしている場合、エージェントは get_repair_screen と teach_repair を呼び出して修正案を提示できます。修正は人が承認する必要があります。docs/REPAIR.mdを参照してください。

3 つのツール

ツール	引数	戻り値
list_workflows	なし	各ワークフローの name、purpose、done_means（完了とみなす条件）、および JSON Schema 形式の inputs。
run_workflow	workflow、inputs、request_id、および省略可能な wait_seconds（0～600、既定値は 60）	1 件の結果。
get_run	run_id、および省略可能な wait_seconds（0～600、既定値は 60）	実行が停止した場合は人の判断も含む、その実行の最新の結果。

request_id は 4～128 文字です。先頭は英字または数字で、その後には英字、数字、.、_、:、- を使用できます。

request_id がないなど、引数が不正な呼び出しは、結果ではなくツールエラーを返します。run_workflow の場合、エラーの末尾には「何も実行されませんでした。」と表示されます。get_run で取得できるのは、同じ実行フォルダー内の実行だけです。

サンドボックスでは 3 つのツールをすべて使用できます。独自のワークフローでは、サーバーを --mode production または --mode attended で起動した場合に限り、run_workflow が表示されます（独自のワークフローを提供するを参照）。

開発者向けセットアップ

このパッケージは、stdio 経由で通信するローカルの Model Context Protocol（MCP）サーバーと、openadapt-agent コマンドで構成されています。Python 3.10～3.12 が必要です。入力を検証し、重複するエントリーを停止して、Flow のレポートを 4 つの結果のいずれかに変換します。openadapt-flow は、ワークフローを記録、再生、検証します。

Flow を単独で試すには、pip install openadapt で OpenAdapt ランチャーをインストールし、openadapt flow tutorial または openadapt quickstart --break-it を実行してください。

独自のエージェントを接続する

任意の MCP クライアントで、uvx コマンドを使ってサーバーを起動できます。Claude Desktop や Cursor など、mcpServers JSON ファイルを読み込むクライアントでは、次を追加します。

{
  "mcpServers": {
    "openadapt": {
      "command": "uvx",
      "args": ["--python", "3.12", "openadapt-agent", "serve"]
    }
  }
}

独自の Python コードからは、MCP Python SDK（pip install mcp）を使用します。

import asyncio
import json

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

SERVER = StdioServerParameters(
    command="uvx",
    args=["--python", "3.12", "openadapt-agent", "serve"],
)


async def main():
    async with stdio_client(SERVER) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            call = await session.call_tool("run_workflow", {
                "workflow": "add_triage_note",
                "inputs": {"note": "Synthetic: recheck blood pressure in 2 weeks"},
                "request_id": "demo-py-0001",
            })
            result = json.loads(call.content[0].text)
            print(result["outcome"], result["next_step"])


asyncio.run(main())

SDK は、いくつかの環境変数だけでサーバーを起動します。OPENADAPT_BUNDLE_KEY などのほかの変数を渡すには、StdioServerParameters に env= を追加します。

scripts/smoke_client.py は、すべてのサンドボックスケースを実行する、より詳細な例です。このリポジトリをクローンしたディレクトリから pip install -e . を実行してから、次を実行します。

python scripts/smoke_client.py -- uvx --python 3.12 openadapt-agent serve

エージェントを独自のクラウドで実行している場合、ネットワークリスナーを持たないこのサーバーには接続できません。サーバーを起動するプログラムは、顧客のコンピューター上で実行する必要があります。その方法の一つは、そこで小規模なワーカーを動かすことです。ワーカーは、ワーカー自身が開いた接続を通じてサービスからリクエストを受け取り、このサーバーを起動し、run_workflow を呼び出して、各結果を返します。ワーカーはエージェントとして動作するため、患者データへのほかのアクセス経路と同様に、その接続を保護してください。ホスト型の経路をご希望の場合は、お問い合わせください。

独自のワークフローを提供する

バンドルとは、workflow.json、または OPENADAPT_BUNDLE_KEY にキーを指定した workflow.json.enc を含む、コンパイル済みのワークフローフォルダーです。--bundles には、バンドルを一つ指定するか、バンドルのフォルダーを指定します。

コマンド	エージェントが利用できるもの
openadapt-agent serve	サンドボックス。
openadapt-agent serve --bundles DIR	ワークフロー（一覧表示のみで実行不可（run_tools_enabled: false））と、過去の実行および停止した実行の読み取り専用ツール。
openadapt-agent serve --mode production --bundles DIR --runs-dir /var/lib/openadapt/runs	ワークフローの実行。
openadapt-agent serve --mode attended --bundles DIR --runs-dir /var/lib/openadapt/runs	実行と、停止した実行に関する判断。

openadapt-agent serve --allow-run は、従来の --mode production の形式です。また、--bundles を指定しない場合は、サンドボックスの従来の形式です。

各実行では openadapt-flow run が呼び出されます。Flow は Chromium で Web アプリを操作し、アドレスは --url で指定します。また、デスクトップアプリや RDP、Citrix のセッションも操作します。その際は、Flow 独自のターゲットフラグを --extra-run-arg で渡す必要がある場合があります。openadapt-flow README では、アプリの種類ごとに説明しています。

ワークフローを実行できる状態にする

Flow は、必須のチェックに合格していないバンドルを拒否します。その場合、エージェントには not_ready_to_run を伴う did_not_run が返され、failed_checks には not_certified や no_readiness_test など、満たされていないチェックが列挙されます。新しい記録を初めて提供するときは、この結果になることを想定してください。

Flow の必須要件は、デプロイ設定（--config）で指定されたプロファイルによって異なります。主な違いは次のとおりです。

• プロファイルなし：ポリシーに対して openadapt-flow certify を実行し、バンドルを認定する必要があります。
• standard または regulated：認定、対象のバンドルバージョンに対する有効なアドミッション（署名付きの準備状況テスト）、および保存された記録を別の経路（アプリの API、データベース、または別のセッションなど）から読み取る記録チェックが必要です。standard では、記録を別の方法で読み取れない Citrix セッションは done で終了できません。
• demo：認定は不要ですが、Flow は保存を確認しないため、実行が完了しても not_sure_if_saved になります。

Flow の実行プロファイルのページでは、各プロファイルについて説明しています。

サーバーのオプションを設定する

フラグ	内容
--runs-dir DIR	実行記録と Flow のエビデンスの保存先です。デフォルトは ~/.openadapt/runs（または設定されている場合は OPENADAPT_AGENT_RUNS_DIR）です。クライアントがサーバーを起動したフォルダーは使用しません。サンドボックスでは ~/.openadapt/agent-sandbox を使用します。サーバーは起動時に使用するフォルダーを表示します。2つ目のエントリーを停止するチェックは1つの runs フォルダーを対象とするため、同じ作業に使うすべてのサーバーに同じフォルダーを指定してください。以前のバージョンでは ./runs を使用していました。そのフォルダーに以前のバージョンの記録があり、--runs-dir を指定しない場合、サーバーは起動しません。どちらのフォルダーを残すか選択してください。
--url URL	アプリのアドレスです。すべての Flow 実行に渡されます。
--config YAML	Flow のデプロイ設定です（例）。プロファイルと、モデルによるグラウンディングを許可するかどうかを設定します。
--policy NAME-OR-PATH	Flow が準拠を認定するポリシーです。clinical-write や permissive などを指定します。
--timeout SECONDS	1回の実行が処理できる時間です（デフォルトは600）。保存を承認するために人が費やす時間は含まれません。制限時間に達して停止した実行の状態は not_sure_if_saved になります。
--approval-mode MODE	保存のたびに人が承認するかどうかを指定します。指定しない場合は Flow が判断します。standard と regulated では、人が承認するまで保存のたびに実行が停止します（each_item）。not_gated を指定すると、このサーバーが開始するすべての実行で承認が不要になります。各結果には technical.approval_mode として記録されます。
--headed	ブラウザーを表示します。ウェブアプリで停止中の実行を続行またはスキップするには、人が操作する必要があります。
--extra-run-arg ARG、--flow-cli CMD	Flow の呼び出し方法を変更します。どちらを指定しても、たとえば --extra-run-arg=--allow-unencrypted のように Flow のチェックを緩和できます。
--allow-protected-export、--allow-synthetic-recorded-defaults、--allow-model-grounding	デフォルトでは無効です。セキュリティを参照してください。

呼び出し側から --url、--config、--policy、--timeout、--approval-mode を変更することはできません。唯一の例外は、サーバーで --allow-url-override が指定されている場合の、非推奨ツールにおける url です。ワークフローに url という独自の入力がある場合、その引数はワークフローの入力として扱われ、オーバーライドには target_url_override を使用します。すべてのフラグは openadapt-agent serve --help に記載されています。

人の承認を待つ実行

standard と regulated では、Flow は保存のたびに停止し、人による承認を待ちます（デフォルトでは最大15分）。待機中は、run_workflow と get_run は理由が waiting_for_approval の needs_review と record_changed: "unknown" を返します。同じ実行内で、それ以前の保存が完了している可能性があるためです。承認待ちの保存は、openadapt-flow item-approval show RUN_DIR で確認できます。ここで RUN_DIR は runs フォルダー内の run_id フォルダーです。回答するには item-approval approve または decline を実行します。制限時間内に回答がない場合、保存前に実行が停止し、理由が approval_needed の needs_review を返します。このサーバーには保存を承認するツールはありません。人が承認します。

ほかのツールを使用する

--bundles を指定すると、サーバーにはワークフローと実行に関する読み取り専用ツール get_workflow、get_run_report、list_needs_attention、get_attention_item も登録されます。--mode production または --mode attended を指定すると、各ワークフローに対して非推奨の run_workflow_<id> も登録されます。これらのツールは request_id を受け取らないため、再試行すると値が二重に入力される可能性があります。代わりに run_workflow を使用してください。

list_workflows、run_workflow、get_run は、contract.py で定義されている outputSchema に一致する structuredContent と、同じ内容の JSON テキストを返します。

停止した実行を判断する

人の対応が必要になって停止した実行は、そのコンピューター上の Flow の「対応が必要」リストで待機します。誰にも通知されません。list_needs_attention でリストを確認できます。

--mode attended を指定すると、エージェントは continue_attention、skip_attention、reject_attention、teach_attention、または escalate_attention で判断を送信できます。コンピューターを操作する人は、各判断をフォームで確認します。続行とスキップには --config も必要です。クライアントがフォームを表示できない場合、サーバーは判断を拒否するため、操作する人は代わりに Flow のコンソールを使用します。

openadapt-flow console --attend --allow-actions --bundles DIR --runs RUNS_DIR

各判断については、docs/DESIGN.md を参照してください。人が判断した後、get_run に新しい結果が表示されます。

カードでワークフローを説明する

カードには、list_workflows がエージェントに表示するワークフローの name、purpose、done_means、および入力の説明を記載します。カードがない場合、ワークフローには意味の分からない名前が付けられます。workflow.json と同じ場所に openadapt-card.json を置きます。

{
  "name": "enter_referral",
  "purpose": "Create an outgoing referral for an existing patient in the clinic EMR.",
  "done_means": "The referral appears in the EMR's referral report for that patient.",
  "inputs": {
    "patient_mrn": {"description": "Clinic MRN of the patient.", "pattern": "^[0-9]{6,10}$"},
    "referral_date": {"description": "Date of the referral.", "format": "date"}
  }
}

カードのテキストはエージェントのモデルに渡されるため、患者の詳細情報は記載しないでください。カードの形式が不正な場合、purpose または done_means が300文字を超える場合、説明が200文字を超える場合、または識別情報が含まれているように見えるテキスト（5桁以上の連続した数字、メールアドレス、電話番号）がある場合、サーバーはカード全体を無視し、警告を記録します。

Agent Skill を作成する

openadapt-agent emit-skill BUNDLE --out ~/.claude/skills は、1つのワークフロー用の SKILL.md を書き出します。内容は、ワークフローの機能、入力、run_workflow の呼び出し方法、各結果の後に行うことです。スキルには記録された値やシークレットは含まれませんが、サーバーは別途追加する必要があります。--include-bundle を指定すると、バンドルもスキルと同じ場所にコピーされます。そのコピーには記録の値が含まれる場合があるため、記録と同じように非公開にしてください。

各スキルの名前はワークフロー名に基づきます。そのため、enter_referral は enter-referral になります。予約済みの名前が2つあります。

• computer-use は、画面を操作するすべてのリクエストでアシスタントが読み込むスキルになるためです。
• openadapt-gui-write は、このリポジトリで提供されるあらゆるワークフローに対応する汎用スキルで、skills/openadapt-gui-write/SKILL.md にあります。

ワークフロー名がどちらかの名前になる場合、emit-skill は openadapt- にワークフローの ID を付けた名前をスキルに付けます。例：openadapt-workflow-1a2b3c4d5e6f7a8b9c0d1e2f。書き出されたスキルが同じフォルダー内の汎用スキルを置き換えることはありません。

最初のワークフローを記録する

serve --authoring は、observe、start_record、click、pause_for_input、stop_record、compile、admit などの記録用ツールを追加します。docs/DESIGN.md に14個すべてが記載されています。人またはエージェントが、ウェブアプリ、Windows ネイティブアプリ、RDP セッション、または Citrix セッションでこれらのツールを使ってタスクを実演します。サインインと結果の承認は、コンピューターの前にいる人が行います。タスクは1回以上の実演から学習できます。記録サーバーは実行を有効にしません。

1. 記録サーバーを追加します。--url を指定すると、サインイン情報が保存されていない新しい Chromium ウィンドウでアプリが開きます。--headed を指定すると、そのウィンドウが表示されたままになり、人がサインインできます。

   claude mcp add openadapt-authoring -- uvx --python 3.12 --from 'openadapt-agent[tutorial]' openadapt-agent serve --authoring --url https://app.example.com --headed
   

2. 人と一緒にタスクを記録するよう、エージェントに依頼します。エージェントがサインインのために一時停止したら、人はそのウィンドウでアプリにサインインします。

3. タスクが完了したら、エージェントが compile を呼び出します。バンドルは <runs-dir>/authoring/bundle に書き込まれます。デフォルトでは ~/.openadapt/runs/authoring/bundle です。

4. エージェントが admit を呼び出します。すると MCP クライアントに確認フォームが表示され、そこで人が回答した場合にのみバンドルが承認されます。クライアントがフォーム（MCP form elicitation）を表示できない場合、admit は拒否され、何も承認されません。

5. バンドルを実行できる状態にします（ワークフローを実行できる状態にするを参照）。その後、--mode production --bundles <runs-dir>/authoring/bundle を指定してサービスを起動します。 すべてのプラットフォームで、ウェブアプリには --url URL --headed を使用してください。--url を指定しない場合、Linux ではサーバーが終了します。macOS では、クライアントがサーバーを起動したときに手前にあるウィンドウが使用されるか、サーバーが終了します。

ネイティブの Windows アプリの場合は、Windows コンピューターのサインイン済みデスクトップセッションで Flow の Windows エージェントサーバーを起動し（python -m openadapt_flow.backends.win_agent.server --port 5001）、--windows-agent-url http://localhost:5001 を指定してください。エージェントはそのコンピューターでも、Mac など別のコンピューターでも実行できます。サーバーはデフォルトでは Windows コンピューター上でのみ接続を待ち受けるため、別のコンピューターから利用するには、SSH 経由でポートを転送するか、HTTPS 経由で公開してください。エージェントのクリックとキー入力は、リプレイで使用されるものと同じ合成入力経路を通ります。また、Windows が報告する場合は、記録にクリックされた各コントロールの UI Automation ID が保持されます。サーバーとエージェントの両方で、OAFLOW_AGENT_TOKEN に同じ値を設定してください。

RDP または Citrix セッションの場合は、--remote-window APP（クライアントアプリ。例："Microsoft Remote Desktop"）または --citrix を指定してください。アプリに複数のウィンドウがある場合は、--remote-window-title も指定します。リモートセッションでは画面のみを使用します。DOM も UI Automation ツリーもないため、observe はノードを返しません。エージェントは、人が操作するのと同じように、クライアントウィンドウ内の x,y 座標をクリックしてキーを押します。エージェントがそのウィンドウを見られるようにするには、--authoring-screens scrubbed を追加してください。これにより、識別子をスクラブしたフレームを返す screen ツールが有効になり、スクラブに失敗した場合は何も共有されません。--authoring-screens unscrubbed を指定すると、スクラブが省略されます。画面機能はデフォルトで無効です。

Windows、RDP、Citrix での記録では、Windows エージェントサーバーの説明、エージェントが別のコンピューターで実行されるときに必要な理由、起動方法、トークン、RDP および Citrix でのピクセル操作経路について解説しています。

記録では、各ステップがエージェントによるものか、人によるものかが示されます（events.jsonl の actor、meta.json の demonstrated_by）。結果は引き続き人が承認します。Windows でこれらのフラグを指定しない場合、ツールは人にクリックする場所を伝えることしかできません。

ウェブブラウザー内の ChatGPT と Claude から、コンピューター上のサーバーを起動することはできません。どちらかから記録するには、https://openadapt.ai/start から開始してください。openadapt.ai から記録ジョブ用のランナーリンク（bind=oab_ を含む）が提供されたら、アプリがあるコンピューターで次を実行してください。

openadapt-agent authoring connect '<runner link>'

ジョブを取得し、送信 HTTPS 経由で openadapt.ai に定期的に問い合わせます。また、チャットアカウントが操作を実行する前に、ターミナルで確認を求めます。これを、コンピューターを OpenAdapt Cloud とペアリングするランチャーの openadapt connect と混同しないでください。詳細については、docs/MAILBOX_CLI.md を参照してください。

セキュリティ

• サーバーは stdio 経由でのみ通信し、サインイン機能はありません。入力に書き込めるものはすべて、サーバーを起動した OS アカウントとして動作するため、ネットワークやトンネル経由で公開しないでください。
• デフォルトでは、エージェントに表示されるのはカード、固定文、判読できない ID、件数のみです。記録された値、パス、レポート、画面上のテキストは、お客様のコンピューター内に保持されます。ただし、記録ツールからのエラーには Flow のエラーメッセージが含まれる場合があります。
• --allow-protected-export を指定すると、記録された値、パス、レポート、Flow の出力がエージェントに送信されます。エージェントのモデルがお客様のアプリのデータを参照してもよい場合にのみ使用してください。
• 入力は、一時ファイルを介して Flow に渡されます。このファイルは所有者だけが読み取ることができ、コマンドラインには渡されません。このパッケージの実行記録に保存されるのは入力のフィンガープリントであり、入力そのものではありません。
• Flow は、各実行の証跡を --runs-dir 配下のフォルダーに保存します。サンドボックスでのテストでは、このフォルダーには入力した値が含まれるレポートと、各ステップの実行前後のスクリーンショットが保存されており、コンピューター上の他のアカウントからもスクリーンショットを読み取ることができました。実行フォルダーは患者データとして扱い、読み取り可能なユーザーを制限してください。
• モデルグラウンディングは、記録されたコントロールが見つからない場合に、クリック位置を特定するためのスクリーンショットを AI モデルに送信します。デフォルトではオフです。デプロイ設定で有効にでき、--allow-model-grounding を指定すると停止中の実行に対する判断で有効になります。有効にすると、スクリーンショットがコンピューターの外部に送信されることがあります。
• --allow-synthetic-recorded-defaults を指定すると、不足している入力に記録の値が使用されます。ワークフローが合成データを使ったデモであることを確認する仕組みはないため、合成デモでのみ使用してください。

脆弱性は SECURITY.md の説明に従って報告してください。

シール

Seal は、Execute のレシートに対する OpenAdapt Cloud の Ed25519 署名です。エージェントが sealed: true と報告するのは、以下のすべてを満たす場合のみです。

1. 実行が Cloud Execute の実行に接続されていること。これは FlowRunner.run(..., cloud_execution_id=...) または OPENADAPT_EXECUTE_API_KEY を設定した状態での openadapt-flow run --cloud-execution-id ID です。結果が VERIFIED になった後、Flow は Cloud からレシートを取得し、execute_receipt として report.json に書き込みます。後から同じ処理を行うには、openadapt-flow attach-seal RUN_DIR --execution-id ID を実行します。
2. レシートの署名が、このコンピューター上で人がピン留めしたキーに対して検証できること。エージェントは実行を確認する際にキーを取得しません。

キーは一度だけピン留めしてください。キー ID を入力する前に、表示されたフィンガープリントを OpenAdapt が公開しているものと照合してください。

openadapt-agent seal keys pin          # fetches https://app.openadapt.ai/api/public/seal-keys
openadapt-agent seal keys show

OpenAdapt がキーをローテーションしたら、再度 pin を実行してください。新しいキーも同じ確認が必要です。Cloud が失効させたキーは、確認を求めずに失効済みとしてマークされます。Cloud の一覧から削除されたキーは、ピン留めされた状態のままになります。

レシート、実行レポート、Webhook の本文があれば、誰でも Seal をオフラインで検証できます。

openadapt-agent seal verify runs/<run_id>/report.json
openadapt-agent seal verify https://example.com/receipt.json --json

制限事項

• エージェント、またはエージェントの代理として動作するプログラムは、お客様のコンピューター上で実行する必要があります。
• 実行が停止しても、誰にも通知されません。誰かが list_needs_attention または Flow のコンソールを確認する必要があります。
• 2 回目の入力を停止するチェックは、1 つの実行フォルダーにのみ適用されます。毎回同じ絶対パスの --runs-dir を渡してください。
• 実行中にサーバーが終了した場合、実行結果は not_sure_if_saved と表示されますが、Flow は処理を完了することがあります。
• このサーバー自体は署名付きレシートを発行しません。実行が OpenAdapt Cloud Execute に接続され、Cloud がそのレシートに署名し、その署名がピン留めしたキーに対して検証できる場合にのみ、proof は sealed になります（シール を参照）。
• openadapt-flow 2 では、オペレーターが別のモード（serve --approval-mode problems_only または not_gated）を指定しない限り、保存のたびに人の承認を待ちます。エージェントには理由が waiting_for_approval の needs_review が通知され、人が OpenAdapt を実行しているコンピューター上で承認します。その回答がない限り、何も保存されません。
• 各呼び出しで処理できるのは 1 つのリクエストです。一括呼び出しには対応していません。
• アカウント、顧客間の分離、フリートポリシー、ホストされた実行は OpenAdapt Cloud が担います。

リリース状況

実際の患者データでリリースを使用する前に、署名済みの本番運用記録を確認してください。承認の有効期間は最長30日で、取り消される場合があります。

Flow の standard プロファイルと regulated プロファイルでは、ワークフローの各バージョンにも個別の承認が必要です（実行可能なワークフローを準備するを参照）。2026-10-14 時点で、ワークフロー承認の公開リストにあるすべての項目は、合成テスト（remote-safe-synthetic）に基づくものです。

パッケージの履歴

バージョン2より前は、このパッケージは画面を操作するAI エージェントを実行していました。現在の名前は、このパッケージを呼び出すエージェントを指します。お客様のワークフローは --bundles で提供され、このパッケージやレジストリの掲載内容には含まれません。また、レジストリからインストールすると、読み取り専用で起動します。MCP レジストリは server.json を読み込み、Smithery は manifest.json からパッケージを作成します。また、llms.txt にはAI アシスタント向けにパッケージの説明が記載されています。docs/DISTRIBUTION.mdを参照してください。

開発

pip install -e ".[dev]"
ruff check src tests scripts
pytest -q
OPENADAPT_AGENT_E2E=1 pytest -q tests/test_sandbox_flow.py   # needs .[tutorial] and Chromium
python scripts/smoke_client.py                                  # the sandbox over real stdio
python -m build
python scripts/check_release_artifacts.py dist
python scripts/check_dist.py dist/*
npx -y @anthropic-ai/[email protected] validate manifest.json
npx -y @anthropic-ai/[email protected] pack . openadapt-agent.mcpb

ライセンス

MIT。LICENSEを参照してください。設計の全容はdocs/DESIGN.mdに、製品ドキュメントはdocs.openadapt.aiにあります。