ACR — Agent Composition Records

ACR — エージェント構成レコード

AI エージェントの行動レジストリです。 ACR は、エージェントが行うすべての外部ツール呼び出しを記録し、そのシグナルをインタラクションプロファイルにまとめて、時間の使い道を可視化します。まずは、各セッションの終了時に表示されるサマリーカードから始められます。

はじめ方（60 秒、Claude Code）

npm i -g @tethral/acr-hook && acr-hook init

設定はこれだけです。フックはエージェントの ID を発行し（アカウントも、管理が必要な API キーも不要です）、Claude Code のツールフックに組み込まれ、すべてのツール呼び出しを自動的に記録します。次のセッションが終了すると、カードがターミナルに表示されます。

── ACR session card ──
  142 tool calls | 4.1% of active time waiting
  Top sinks: platform:bash 38s · mcp:github 12s
  Full report: https://dashboard.acr.nfkey.ai/agents/…

acr-hook remove を実行すれば、いつでもアンインストールできます（設定のバックアップが復元されます）。

ACR について

ACR はインタラクションプロファイルのレジストリです。エージェントが行うこと（ツール呼び出し、API リクエスト、MCP インタラクション）を記録し、そうしたシグナルを行動プロファイルにまとめます。このプロファイルはレンズを通して照会できます。各レンズは、同じ基礎データを異なる方法で読み取ります。

最初に提供されるのは摩擦レンズです。対象ごとのレイテンシと失敗の内訳、時間のかかっている箇所、自身の履歴と比較した傾向を確認できます。カバレッジ、顕在化した選好（宣言された構成と実際に使用された構成の比較）、失敗、傾向、安定性を確認するレンズもあります。

ACR はセキュリティ製品ではありません。スキルを評価したり、侵害を検査したり、何かをブロックしたりすることはありません。イベントを記録し、通知を伝達します。ネットワークがエージェントの構成要素に関する異常シグナルを検知すると、エージェントに通知が届きます。それが重要かどうかは、ユーザーが判断します。

現時点でできることと、ネットワークの成長に伴って拡張される機能

ACR は自身の成熟度を正直に示します。各レンズは、3 つの状態のうちどれにあるかを示します。実データあり、データ不足（状態を変えるための操作も表示）、または機能低下（クエリに失敗。正常なゼロ値としてではなく、利用不可として表示）。

初日から、エージェント 1 体でも利用できる機能：

• フックによるすべてのツール呼び出しの自動記録（所要時間、ステータス、対象）
• 自身のデータに対する摩擦レンズ：時間のかかっている箇所、対象ごとのレイテンシと失敗、セッションカード
• 自身の履歴と比較した傾向（今週と先週）
• カバレッジ：どのシグナルが入力されているか、それによってどのレンズが利用可能になるか

ネットワークの成長に伴って利用可能になる機能（母集団に関する機能は、対象ごとに永続的なエージェントが最低 5 体いる場合に有効になります。それ未満の場合、比較を捏造するのではなく、「あなたが基準です」とレンズに表示されます）：

• 母集団のベースライン（「api:openai.com ではネットワークより 42% 遅い」）
• ネットワークのステータス：全エージェントのシステム健全性を、深刻度の高い順に表示
• 異常シグナルの通知：宣言された構成要素について、20 件以上のインタラクションで 3 体以上の異なるエージェントから異常が報告されると、通知が届きます

フックでは確認できない情報（ゼロ値を表示せず、その旨をレンズで示します）：

• 詳細な失敗情報 — フックが確認するのは表面上のエラーのみです。ツールの結果境界に到達しないネットワーク、タイムアウト、認証の失敗は表示されません。0 failures は「確認できる失敗が 0 件」という意味です。
• 再試行回数、キューの待ち時間、チェーン構造、トークン使用量 — これらのフィールドを使って log_interaction を呼び出すエージェントのみが情報を入力します。フックのみのプロファイルでは、該当セクションは正常なゼロ値ではなく n/a と表示されます。

MCP サーバーを追加する（任意。エージェント内部からレンズを照会する場合）

フックが記録を行い、MCP サーバーを使うと、エージェントは自身のプロファイルを読み取り、より詳細なシグナルを記録できます。Claude Code では、次のコマンドを 1 つ実行します。

claude mcp add acr -s user -- npx -y @tethral/acr-mcp@latest

または、任意の MCP クライアント（Cursor、Continue、Claude Desktop など）では、次のようにします。

{
  "mcpServers": {
    "acr": {
      "command": "npx",
      "args": ["-y", "@tethral/acr-mcp@latest"]
    }
  }
}

フックと MCP サーバーは同じ ID ファイルを共有しており、どちらかを使うと、もう一方も設定されます。何から始めればよいかわからない場合は、orient_me を呼び出してください。

コア MCP ツール

ツール	機能
orient_me	現在の状況と次にすべきことを把握します — 状態に応じたルーティング
log_interaction	詳細なフィールド（retry_count、chain_id、tokens_used など）とともにインタラクションを記録します
get_friction_report	摩擦の分析：時間とトークンがどこに費やされているかを確認します
summarize_my_agent	セッション終了時の要約
get_notifications	構成に関する未読の異常シグナル通知
get_my_agent	ID、ダッシュボードへのリンク、登録状態

この7つがデフォルトで利用できるすべての機能です。ホストエージェントのコンテキストウィンドウでは、ツールスキーマごとにコンテキストを消費するため、意図的に絞っています。MCP 設定で環境変数を1つ指定すると、29個のツールすべて（get_coverage／get_trend／get_revealed_preference／get_stable_corridors などの追加分析機能、構成管理、スキルレジストリ、監視機能、ネットワークビュー）が有効になります。

{ "command": "npx", "args": ["-y", "@tethral/acr-mcp@latest"], "env": { "ACR_ADVANCED": "1" } }

orient_me と get_my_agent は、拡張ツールセットがあることをモデルに伝えます。そのため、機能が隠されているわけではなく、デフォルトではコンテキストを消費しないようになっています。

あらゆるエージェントに追加する（SDK）

npm install @tethral/acr-sdk    # TypeScript/Node.js
pip install tethral-acr          # Python

import { ACRClient } from '@tethral/acr-sdk';

const acr = new ACRClient();

// Register your agent's composition
const reg = await acr.register({
  public_key: 'your-agent-key-here-min-32-chars',
  provider_class: 'anthropic',
  composition: { skill_hashes: ['hash1', 'hash2'] },
});

// Log an interaction (the foundation — every lens reads these)
await acr.logInteraction({
  target_system_id: 'mcp:github',
  category: 'tool_call',
  status: 'success',
  duration_ms: 340,
});

// Query the friction lens
const friction = await acr.getFrictionReport(reg.agent_id, { scope: 'day' });

// Check for anomaly signal notifications
const notifs = await acr.getNotifications(reg.agent_id);

異常シグナル通知

異常シグナルとは、互いに無関係な複数のエージェントにわたって観測された行動パターンであり、セキュリティアラートではありません。登録時（または構成の更新時）に、ACR は宣言されたコンポーネントを購読します。その後、ネットワーク上でいずれかのコンポーネントに関する異常シグナルの増加が観測された場合（20件以上のインタラクションにわたって、報告元が3つ以上の異なるエージェントであること）、エージェントに通知が届きます。

[HIGH] Component in your composition reported anomalies
   3 agents reported anomalies across 41 interactions.
   Anomaly rate: 34.1%. Review with your operator before continuing use.

この経路は CI でエンドツーエンドにテストされています（scripts/db-contract-test.mjs を参照）。購読中のスキルにシードされた異常レポートがある場合、通知が生成されなければビルドは失敗します。ACR はエージェントの背後にいる人間を追跡しないため、通知は所有者ではなくエージェントに届きます。

スキルレジストリ

ACR は公開レジストリ（npm、GitHub）にすでに存在するスキルを観測し、それらに関連する行動シグナル（採用数、異常シグナル、バージョン履歴）を追跡します。ここからインストールするカタログではなく、セキュリティチェックでもありません。ネットワークで観測された内容を記録します。検索ではシグナルのあるスキルが優先されます。有効な ID のないカタログ項目は、クロール時に除外されます。

アーキテクチャ

Agents (Claude, OpenClaw, custom)
  |
  +--> Capture hook (@tethral/acr-hook — primary capture path)
  |      PreToolUse/PostToolUse receipts, SessionEnd card
  |
  +--> MCP Server (@tethral/acr-mcp) or SDK (@tethral/acr-sdk / tethral-acr)
  |      Lens queries, log_interaction, notifications
  |
  +--> Resolver API (Cloudflare Workers, edge-cached)
  |      Lookups, composition checks, notification feed
  |
  +--> Ingestion API (Vercel serverless)
  |      Registration, interaction receipts, lens queries, notifications
  |
  +--> CockroachDB (distributed SQL)
  |      Interaction profiles, agent registry, skill observation data
  |
  +--> Scheduled jobs (GitHub Actions -> /api/cron/*)
         system-health aggregation + chain analysis (15 min)
         skill signal computation + watch evaluation + pattern detection (30 min)
         friction baselines + data archival + agent expiration (daily)
         Every run writes a heartbeat; /health reports pipeline liveness
         separately from network activity.

データ収集

ACR が収集するのはインタラクションのメタデータのみです。対象システム名、タイミング、ステータス、チェーンコンテキスト、プロバイダークラスが対象です。リクエスト／レスポンスの内容、API キー、プロンプト、PII は収集しません。あなたのインタラクションプロファイルを閲覧できるのはあなただけです。全体のベースラインには、継続しているエージェントの集計統計を使用します。

収集するデータ： 対象システム名（mcp:github、api:stripe.com）、インタラクションのタイミング（所要時間、タイムスタンプ、キューの待ち時間、再試行回数）、インタラクションのステータス、エージェントのプロバイダークラス、構成ハッシュ（SKILL.md の内容の SHA-256）、チェーンコンテキスト、エージェントが報告した異常フラグ（カテゴリのみ）。

収集しないデータ： リクエスト／レスポンスのペイロード、認証情報、プロンプトや生成結果、PII、ファイルの内容、エージェントの背後にいる人間の ID。

保持期間（定期実行される data-archival および agent-expiration ジョブによって適用）：インタラクションレシートは90日間保持した後、日次サマリーにアーカイブされます。通知は90日間保持されます。エージェント登録は90日間活動がない場合、ソフト期限切れになります。スキルの観測データは、スキルが観測されている間保持されます。

第三者との共有： なし。連絡先： [email protected] · 利用規約全文

テストハーネス

node scripts/test-agent-lifecycle.mjs   # full agent lifecycle against the live API
node scripts/e2e-smoke.mjs              # do -> read-back loop through the default lens (runs in CI on schedule)
node scripts/db-contract-test.mjs       # every migration, cron, and lens against a real CockroachDB (runs in PR CI)

db-contract ハーネスが用意されているのは、ユニットテストではデータベースをモックする一方、本番環境では CockroachDB を実行しており、方言の違いによって同じ分析クエリが導入前に3回も壊れたためです。すべての分析ルートが200を返し、縮退しておらず、件数がシードデータと一致する必要があります。通知に関する保証もエンドツーエンドで検証されます。

開発

pnpm install                    # Install dependencies
pnpm build                      # Build all packages
pnpm test:unit                  # Run unit tests
node scripts/run-migration.mjs up      # Run DB migrations

リリースルール： packages/mcp-server、packages/acr-hook、または SDK を変更する場合は、バージョンを上げる必要があります（PR の CI でチェックされます）。また、master へのマージ時に、バージョンを上げたパッケージは自動的に公開されます。npm に公開されないままマージされた修正は、修正されなかったのと同じです。

任意：このリポジトリの作業中に ACR をドッグフーディングする。 .mcp.json.example を .mcp.json にコピーすると、このディレクトリを開く MCP 対応クライアントで、公開済みの @tethral/acr-mcp が読み込まれます。オプトイン方式を採用しています。.mcp.json は gitignore 対象のため、コントリビューターが暗黙のうちに登録されることはありません。ローカルの MCP 変更をテストするには、pnpm build の実行後、command を node に、args を ./packages/mcp-server/dist/cli/stdio.js に設定してください。

ライセンス

MIT

リンク

• API: https://acr.nfkey.ai
• npm（フック）: @tethral/acr-hook
• npm（MCP）: @tethral/acr-mcp
• npm（SDK）: @tethral/acr-sdk
• PyPI: tethral-acr