Formbridge

FormBridge

エージェントと人間が混在してフォームを送信するためのインフラです。AI エージェントが把握している項目を入力し、人間が残りを補完します。すべてのフィールドで入力者を記録し、承認ワークフローと Webhook 配信にも対応します。

課題

AI エージェントはフォーム入力に必要なデータの 大部分 を収集できますが、署名、ファイルのアップロード、本人確認、主観的な好みなど、人間による入力が必要な項目もあります。既存のフォームツールでは、完全自動化か完全手動かのどちらかを選ばなければなりません。その引き継ぎに対応するものはありません。

FormBridge の仕組み

Agent                          FormBridge                        Human
  │                               │                                │
  ├─ POST /submissions ──────────►│  Creates draft, returns         │
  │  (fills known fields)         │  resumeToken + handoff URL      │
  │                               │                                │
  │                               │◄──── Opens link ────────────────┤
  │                               │  Pre-filled form with           │
  │                               │  attribution badges             │
  │                               │                                │
  │                               │◄──── Fills remaining fields ────┤
  │                               │◄──── Submits ──────────────────┤
  │                               │                                │
  │  ◄── Webhook delivery ───────┤  Validated, approved,           │
  │      (HMAC-signed)            │  delivered to destination       │

1. エージェントが作成：送信内容を作成し、把握しているフィールドに入力します
2. FormBridge が生成：ローテーションするトークン付きの安全な再開 URL を生成します
3. 人間がリンクを開く：入力済みのフィールドに「エージェントが入力」のバッジが付いた状態で表示されます
4. 人間が残りを入力：未入力のフィールドを入力し、ファイルをアップロードして送信します
5. 送信内容が処理される：検証 → 必要に応じた承認ゲート → Webhook 配信の順に進みます
6. すべてのフィールドで：誰（エージェント、人間、システム）がいつ入力したかを記録します

パッケージ

パッケージ	npm	説明
@agentkitai/formbridge-mcp-server	—	コアサーバー — HTTP API、MCP ツール、送信ライフサイクル、ストレージバックエンド（メインパッケージ）
@agentkitai/formbridge-create		CLI スキャフォールディングツール（npx @agentkitai/formbridge-create）
@agentkitai/formbridge-form-renderer		フォームのレンダリングと、エージェントが開始した送信の再開に使用する React コンポーネントおよびフック
@agentkitai/formbridge-schema-normalizer		Zod、JSON Schema、OpenAPI 仕様を統一された IntakeSchema IR に変換
@agentkitai/formbridge-shared		パッケージ間で共有するユーティリティ
@agentkitai/formbridge-templates		すぐに使える受付テンプレート（ベンダーのオンボーディング、IT アクセス、顧客受付、経費報告書、バグ報告）
@agentkitai/formbridge-admin-dashboard	—	受付の管理、送信内容の確認、承認の設定を行う React SPA

クイックスタート

インストール

コアサーバーパッケージ（@agentkitai/formbridge-mcp-server）は、まだ npm に公開されていません。ソースからインストールしてください。

git clone https://github.com/agentkitai/formbridge.git
cd formbridge
npm install
npm run build

関連パッケージ（@agentkitai/formbridge-create、@agentkitai/formbridge-form-renderer、@agentkitai/formbridge-schema-normalizer、@agentkitai/formbridge-shared、@agentkitai/formbridge-templates）は公開済みのため、npm から直接インストールできます。

オプション 1：HTTP API サーバー

import { createFormBridgeApp } from '@agentkitai/formbridge-mcp-server';
import { serve } from '@hono/node-server';

const app = createFormBridgeApp({
  intakes: [{
    id: 'contact-form',
    version: '1.0.0',
    name: 'Contact Form',
    schema: {
      type: 'object',
      properties: {
        name:    { type: 'string', title: 'Full Name' },
        email:   { type: 'string', format: 'email', title: 'Email' },
        message: { type: 'string', title: 'Message' },
      },
      required: ['name', 'email', 'message'],
    },
    destination: {
      type: 'webhook',
      name: 'Contact API',
      config: { url: 'https://api.example.com/contacts', method: 'POST' },
    },
  }],
});

serve({ fetch: app.fetch, port: 3000 });
console.log('FormBridge running on http://localhost:3000');

送信ライフサイクル全体：

# 1. Agent creates a submission with known fields
curl -X POST http://localhost:3000/intake/contact-form/submissions \
  -H 'Content-Type: application/json' \
  -d '{
    "actor": { "kind": "agent", "id": "gpt-4" },
    "idempotencyKey": "req_abc123",
    "initialFields": { "name": "John Doe", "email": "[email protected]" }
  }'
# → { ok: true, submissionId: "sub_...", resumeToken: "rtok_...", state: "draft" }

# 2. Human completes remaining fields via resume token
curl -X PATCH http://localhost:3000/intake/contact-form/submissions/sub_.../fields \
  -H 'Content-Type: application/json' \
  -d '{
    "resumeToken": "rtok_...",
    "actor": { "kind": "human", "id": "user-1" },
    "fields": { "message": "I'd like to learn more about your product." }
  }'

# 3. Submit the completed form
curl -X POST http://localhost:3000/intake/contact-form/submissions/sub_.../submit \
  -H 'Content-Type: application/json' \
  -d '{
    "resumeToken": "rtok_...",
    "actor": { "kind": "human", "id": "user-1" }
  }'
# → Triggers validation, approval (if configured), and webhook delivery

オプション 2：MCP サーバー（AI エージェント向け）

import { FormBridgeMCPServer } from '@agentkitai/formbridge-mcp-server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new FormBridgeMCPServer({
  name: 'my-formbridge',
  version: '1.0.0',
});

server.registerIntake({
  id: 'vendor_onboarding',
  version: '1.0.0',
  name: 'Vendor Onboarding',
  description: 'Register new vendors',
  schema: z.object({
    companyName: z.string().describe('Legal company name'),
    taxId:       z.string().describe('Tax identification number'),
    contact:     z.string().email().describe('Primary contact email'),
    w9Upload:    z.string().optional().describe('W-9 form upload (human-only)'),
  }),
  destination: {
    type: 'webhook',
    name: 'Vendor System',
    config: { url: 'https://api.example.com/vendors', method: 'POST' },
  },
});

// Each intake auto-generates 4 MCP tools:
//   vendor_onboarding__create   — Start a new submission
//   vendor_onboarding__set      — Update fields
//   vendor_onboarding__validate — Check completeness
//   vendor_onboarding__submit   — Submit for processing

const transport = new StdioServerTransport();
await server.getServer().connect(transport);

オプション 3：React フォームレンダラー

import { FormBridgeForm, ResumeFormPage } from '@agentkitai/formbridge-form-renderer';

// Standalone form
function ContactPage() {
  return (
    <FormBridgeForm
      schema={contactSchema}
      endpoint="http://localhost:3000"
      actor={{ kind: 'human', id: 'user-1' }}
      onSuccess={(data, submissionId) => {
        console.log('Submitted:', submissionId);
      }}
    />
  );
}

// Resume an agent-started form (pre-filled fields + attribution badges)
function ResumePage() {
  const token = new URLSearchParams(location.search).get('token');
  return (
    <ResumeFormPage
      resumeToken={token}
      endpoint="http://localhost:3000"
    />
  );
}

オプション 4：CLI スキャフォールディング

# Interactive — walks you through setup
npx @agentkitai/formbridge-create

# Non-interactive
npx @agentkitai/formbridge-create --name my-intake --schema zod --interface http,mcp

機能

コア

• 送信ステートマシン — 設定可能な遷移による draft → in_progress → submitted → finalized
• フィールドの帰属情報 — 各フィールドには、値を設定したアクター（エージェント、人間、システム）とその日時が記録されます
• 再開トークン — 引き継ぎ URL 用の安全なローテーション式トークン（状態が変わるたびにローテーション）
• 冪等な送信 — 同じキーを使った重複リクエストには、既存の送信内容を返します
• スキーマの正規化 — Zod スキーマ、JSON Schema、OpenAPI 仕様を入力として受け付けます

コラボレーション

• 混合モードフォーム — エージェントが入力できる項目を埋め、残りを人間が入力します
• 条件付きフィールド — 他のフィールド値に応じてフィールドを表示または非表示にします（動的スキーマ）
• 複数ステップのウィザード — ステップインジケーターとナビゲーションを備えた段階的な情報開示
• ファイルアップロードプロトコル — 安全なファイル処理のための署名付き URL ネゴシエーション（S3 互換）

本番環境

• 承認ゲート — 承認または却下されるまで送信を一時停止する、設定可能なレビューワークフロー
• Webhook 配信 — 指数バックオフと配信追跡を備えた HMAC 署名付きペイロード
• イベントストリーム — すべての状態変更、フィールド更新、アクションを記録する追記専用の監査証跡
• 認証と RBAC — API キー認証、OAuth プロバイダー、ロールベースのアクセス制御、レート制限
• マルチテナンシー — 設定可能なストレージとアクセス境界によるテナント分離
• プラガブルストレージ — インメモリ（開発用）、SQLite（単一サーバー）、PostgreSQL（複数レプリカの HA）、S3（ファイルアップロード）

開発者エクスペリエンス

• MCP サーバー — 入力定義から MCP ツールを自動生成し、AI エージェントと連携します
• 管理ダッシュボード — 入力フォームの管理、送信内容の確認、分析を行う React SPA
• CLI スキャフォールディング — npx @agentkitai/formbridge-create で、すぐに実行できるプロジェクトを生成します
• 5 つのスターターテンプレート — ベンダー登録、IT アクセス申請、顧客情報入力、経費報告、バグ報告
• VitePress ドキュメント — API リファレンス、ガイド、チュートリアル、コンセプトドキュメント
• CI/CD — Node 18/20/22 での lint、型チェック、テストを実行する GitHub Actions

API リファレンス

エンドポイント

メソッド	パス	説明
GET	/health	ヘルスチェック
GET	/intake/:id/schema	入力フォームのスキーマを取得
POST	/intake/:id/submissions	送信内容を作成
GET	/intake/:id/submissions/:subId	送信内容を取得
PATCH	/intake/:id/submissions/:subId	フィールドを更新
POST	/intake/:id/submissions/:subId/submit	送信
GET	/submissions/:subId/events	イベントストリームを取得
POST	/submissions/:subId/approve	送信内容を承認
POST	/submissions/:subId/reject	送信内容を却下
POST	/intake/:id/submissions/:subId/uploads	ファイルアップロード URL をリクエスト
POST	/intake/:id/submissions/:subId/uploads/:uploadId/confirm	ファイルアップロードを確定
GET	/submissions/:subId/deliveries	送信内容の Webhook 配信一覧を取得
GET	/webhooks/deliveries/:deliveryId	個別の Webhook 配信を取得
GET	/analytics/summary	送信内容の分析サマリー
GET	/analytics/volume	時系列での送信件数
GET	/analytics/funnel	状態別の送信ファネル
GET	/analytics/intakes	入力フォームごとの指標

送信状態

draft → in_progress → submitted → finalized
          │  ↘ awaiting_upload
          ↘ needs_review → approved → submitted/finalized
                        ↘ rejected

• draft — 新規作成され、エージェントや人間が入力中
• in_progress — フィールドが設定中
• awaiting_upload — ファイルのアップロード完了待ち
• submitted — 必須フィールドがすべて入力済みで、レビュー待ち（または自動承認済み）
• needs_review — 承認ゲートで一時停止し、レビュアーの判断を待機中
• approved — 承認ゲートを通過済み
• rejected — レビュアーによって却下済み（終了状態）
• finalized — 完了し、送信先に配信済み（終了状態）
• cancelled / expired — キャンセルされた送信内容、または TTL の期限切れによる送信内容の終了状態

ストレージバックエンド

FormBridge は複数のストレージバックエンドに対応しており、環境変数 FORMBRIDGE_STORAGE で選択します。

バックエンド	値	用途	依存関係
インメモリ	memory（デフォルト）	開発、テスト	なし
SQLite	sqlite	単一サーバーの本番環境	better-sqlite3
PostgreSQL	postgres	複数レプリカの HA デプロイ	pg

PostgreSQL の設定

# Required
export FORMBRIDGE_STORAGE=postgres
export DATABASE_URL=postgresql://user:password@host:5432/formbridge

# Optional: install pg driver
npm install pg

import { PostgresStorage } from '@agentkitai/formbridge-mcp-server';

const storage = new PostgresStorage({
  connectionString: process.env.DATABASE_URL!,
  maxConnections: 20,        // default: 10
  idleTimeoutMillis: 30000,  // default: 30000
});
await storage.initialize(); // runs migrations automatically

// Or use the factory:
import { createStorageFromEnv } from '@agentkitai/formbridge-mcp-server';
const storage = await createStorageFromEnv(); // reads FORMBRIDGE_STORAGE + DATABASE_URL

PostgreSQL スキーマでは、ID に UUID、構造化データに JSONB、タイムスタンプに TIMESTAMPTZ を使用するなど、適切な Postgres 型を使用します。マイグレーションファイルは migrations/001_init.sql にあります。

アーキテクチャ

┌──────────────────────────────────────────────────────────┐
│                     FormBridge Core                       │
│                                                          │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │   Intake     │  │  Submission  │  │   Approval     │  │
│  │  Registry    │  │   Manager    │  │   Manager      │  │
│  └─────────────┘  └──────────────┘  └────────────────┘  │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │   Event      │  │   Webhook    │  │   Condition    │  │
│  │   Store      │  │   Manager    │  │   Evaluator    │  │
│  └─────────────┘  └──────────────┘  └────────────────┘  │
│                                                          │
│  ┌─────────────────────────────────────────────────────┐ │
│  │              Storage Layer                           │ │
│  │  Memory (dev) │ SQLite (prod) │ S3 (file uploads)   │ │
│  └─────────────────────────────────────────────────────┘ │
│                                                          │
│  ┌──────────────────┐  ┌──────────────────────────────┐  │
│  │   HTTP API        │  │   MCP Server                 │  │
│  │   (Hono)          │  │   (Stdio + SSE transports)   │  │
│  └──────────────────┘  └──────────────────────────────┘  │
│                                                          │
│  ┌──────────────────┐  ┌──────────────────────────────┐  │
│  │   Auth / RBAC     │  │   Rate Limiting              │  │
│  │   Multi-tenancy   │  │   CORS                       │  │
│  └──────────────────┘  └──────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

┌────────────────────┐  ┌────────────────────────────────┐
│  React Form        │  │  Admin Dashboard               │
│  Renderer          │  │  (React SPA)                   │
└────────────────────┘  └────────────────────────────────┘

┌────────────────────┐  ┌────────────────────────────────┐
│  CLI Scaffolding   │  │  Schema Normalizer             │
│  (create-formbridge)│  │  (Zod/JSONSchema/OpenAPI → IR) │
└────────────────────┘  └────────────────────────────────┘

プロジェクト構成

src/
  auth/           # API key auth, OAuth, RBAC, rate limiting, tenant isolation
  core/           # Business logic — submission manager, approval gates, events,
                  #   state machine, condition evaluator, webhook delivery
  mcp/            # MCP server, tool generator, stdio + SSE transports
  middleware/     # Hono middleware (CORS, error handling)
  routes/         # HTTP route handlers (submissions, approvals, uploads, events,
                  #   webhooks, analytics, health)
  storage/        # Storage backends (memory, SQLite, S3) + migration utility
  types/          # TypeScript types and intake contract spec

packages/
  admin-dashboard/    # React SPA — intake management, submission review, analytics
  create-formbridge/  # CLI tool — interactive + non-interactive project scaffolding
  form-renderer/      # React components — FormBridgeForm, ResumeFormPage, WizardForm
  schema-normalizer/  # Converts Zod, JSON Schema, OpenAPI → unified IntakeSchema IR
  shared/             # Shared utilities across packages
  templates/          # 5 starter templates with full schema definitions
  demo/               # Demo app with sample intakes and pre-configured workflows

docs/               # VitePress documentation site
tests/              # 1,427 tests across 59 files
.github/workflows/  # CI (lint + typecheck + tests on Node 18/20/22) + release

開発

# Install dependencies
npm install

# Run all 1,427 tests
npm run test:run

# Watch mode
npm test

# Type checking (zero errors)
npm run typecheck

# Lint (ESLint flat config v9)
npm run lint

# Build
npm run build

# Run the demo app
cd packages/demo && npm run dev

テスト

テストスイートでは、以下をカバーしています。

• コアロジック — 送信内容のライフサイクル、状態マシンの遷移、承認ワークフロー、フィールドの帰属
• API エンドポイント — すべてのルートに対する HTTP リクエスト／レスポンスの完全なテスト
• MCP サーバー — ツール生成、サーバー初期化、トランスポート処理
• ストレージバックエンド — エッジケースを含む、メモリ、SQLite、S3 ストレージ
• CLI スキャフォールディング — CLI のエンドツーエンドテスト（対話型＋非対話型）
• スキーマの正規化 — Zod、JSON Schema、OpenAPI の変換
• 条件評価 — 動的なフィールド表示ルール
• Webhook 配信 — HMAC 署名、再試行ロジック、配信追跡

1,427 tests passing across 59 test files

（アップロードパスに関する 2 つのテストでは POSIX の / 区切り文字を検証するため、Windows では失敗します。CI が実行される Linux/macOS では成功します。）

ロードマップ

• npm パッケージの公開（npm で 5 つのパッケージを公開中）
• PostgreSQL ストレージバックエンド
• リアルタイムコラボレーション（WebSocket によるフィールドロック）
• 承認待ちのメール通知
• グラフ付きフォーム分析ダッシュボード
• ホステッドクラウド版

コントリビューション

コントリビューションを歓迎します！変更したい内容について話し合うため、まず issue を作成してください。

git clone https://github.com/agentkitai/formbridge.git
cd formbridge
npm install
npm run test:run   # All tests pass
npm run typecheck  # Zero errors
npm run lint       # Clean

🧰 AgentKit エコシステム

プロジェクト	説明
AgentLens	AI エージェント向けのオブザーバビリティと監査証跡
Lore	エージェント間でのメモリーと教訓の共有
AgentGate	Human-in-the-loop 承認ゲートウェイ
FormBridge	エージェントと人間が混在するモードのフォーム	⬅️ ここにいます
AgentEval	テストおよび評価フレームワーク
agentkit-cli	統合 CLI オーケストレーター

ライセンス

MIT © 2026 Amit Paz