AgenTrux プラグイン

ステータス: 実験段階 — API は今後変更される可能性があります。

AgenTrux プラグインを使うと、外部プラットフォームから AgenTrux に接続できます。各プラグインが認証・イベント送信・イベント取得を代行します。

初めての方へ: まず下のセットアップガイドを読んでください。

プラグイン一覧

認証の仕組み

2 つのパターンがあります。ユーザがブラウザを開ける場所でプラグインが 動くかどうか で選びます。

パターン A — OAuth 2.1 ブラウザフロー (interactive クライアント推奨)

MCP サーバおよび OAuth 対応クライアント (Claude Desktop / Cursor / Cline / etc.) は 標準 OAuth 2.1 authorization_code + PKCE loopback フローを実行します。コピペ作業は一切なし — ユーザは consent 画面で 許可 を 1 回クリックするだけで JWT を取得できます。

[クライアント、初回 1 回]
  POST /oauth/register                                      → client_id
[ユーザ、セッション毎に 1 回]
  ブラウザを /oauth/authorize?...&code_challenge=<pkce_hash> に向ける
  → Console consent 画面 (Script picker + scope チェックボックス)
  → 許可 → loopback redirect で ?code=...
[クライアント、セッション毎]
  POST /oauth/token   grant_type=authorization_code         → access_token (JWT) + refresh_token
[クライアント、コール毎]
  Authorization: Bearer <JWT>

詳細は MCP サーバ doc を参照 (Claude Desktop / Cursor 設定例あり)。

パターン B — Activation code（プラグイン / SDK）

Agent SDK と OpenClaw プラグインは single-use の Activation Code フローを使用します（公開 OAuth callback 不要）。

ステップ 1: redeem（1回だけ）
  Activation Code (act_) → POST /auth/redeem-activation-code → client_id (crd_) + client_secret (aks_)

ステップ 2: トークン取得
  client_id + client_secret → POST /oauth/token (grant_type=client_credentials) → JWT aat_（約10分）

ステップ 3: API 呼び出し
  aat_ → Authorization: Bearer ヘッダーに設定 → API を呼び出す

トークンの更新: client_credentials は refresh token を発行しません。aat_ の有効期限が近づくと、プラグインが保存済みの client_id（crd_）と client_secret（aks_）で POST /oauth/token を再度呼びます。

クレデンシャル一覧

注（Phase Z、 2026-05-22）: 匿名 inv_ invite code は廃止されました。 クロスアカウントアクセスは Console UI（Aliases → Share trust + Grants → Create）で確立します — 後述「クロスアカウントアクセス」 を参照。

セットアップガイド {#setup-guide}

プラグインを使う前に、AgenTrux Console でリソースを作成し、Activation Code を発行する必要があります。

全体の流れ

┌──────────────────────────────────────────────────────────────────┐
│  ステップ 1: 管理者が Console でリソースを作成                      │
│                                                                  │
│    Alias 作成 → Topic 作成 → Script 作成 → Grant 設定              │
│    → Activation Code 発行                                        │
└──────────────────────┬───────────────────────────────────────────┘
                       │  Activation Code をエージェントに渡す
                       ▼
┌──────────────────────────────────────────────────────────────────┐
│  ステップ 2: エージェントが API で接続                              │
│                                                                  │
│    アクティベーション → JWT 取得 → イベント送受信                    │
└──────────────────────────────────────────────────────────────────┘

ステップ 1: Console でリソースを作成する

console.agentrux.com にログインして、以下の手順で進めてください。

1-1. Alias を作成する

Alias はプロジェクトのいちばん大きな単位です。ワークスペースやプロジェクトのようなものです。Topic、Script、Grant はすべて Alias に所属します。

Console → Aliases → 「+ New Alias」
  Display Name: my-project
  → Create

1-2. Topic を作成する

Topic は Alias が所有するメッセージチャネルです。送信されたイベントは設定した期間だけ保持され、その後自動的に削除されます。

Console → Topics → 「+ New Topic」
  Alias: my-project
  Name: sensor-data
  Retention: 24h
  → Create

1-3. Script を作成する

Script はエージェントの認証用アカウントです。エージェント1つにつき Script 1つを作成します。Alias に所属します。

Console → Scripts → 「+ New Script」
  Alias: my-project
  Name: temperature-sensor
  → Create

1-4. Grant を設定する

Grant は「どの Script がどの Topic に何をできるか」を決めるルールです。read（読み取り）、write（書き込み）、またはその両方を指定します。

Console → Grants → 「+ New Grant」
  Script: temperature-sensor
  Topic: sensor-data
  Action: write
  → Create

読み取りも必要な場合は、Action: read でもう1つ Grant を作成してください。

よくある構成例:

Script A (センサー)     → Topic: sensor-data (write)
Script B (ダッシュボード) → Topic: sensor-data (read)
Script C (管理ボット)    → Topic: sensor-data (read + write)

1-5. Activation Code を発行する

Activation Code は Script をアクティベーションして永続的なクレデンシャルを付与する、1回限りのキーです。

Console → Scripts → temperature-sensor → 「Issue Activation Code」
  Expires in: 24h
  → Issue

表示された act_... コードをコピーして、エージェントに渡してください。

コードは1回しか使えません。redeem 後は無効になりますが、いつでも新しいコードを発行できます。

ステップ 2: エージェントを接続する

2-1. Activation Code を redeem（1回だけ）

Activation Code を送信して、永続的な Script credential を取得します。

POST /auth/redeem-activation-code
Body: { "code": "act_..." }

Response:
{
  "client_id": "crd_e5f6a7b8-...",
  "client_secret": "aks_xxxxxxxx...",
  "script_id": "scr_...",
  "issued_at": "2026-03-17T12:00:00"
}

client_id（crd_）と client_secret（aks_）を安全に保存してください。 エージェント起動のたびに必要です。aks_ は 1 度だけ表示されます。

2-2. アクセストークンを取得する

POST /oauth/token   (application/x-www-form-urlencoded)
Body: grant_type=client_credentials&client_id=crd_e5f6a7b8-...&client_secret=aks_xxx...

Response:
{
  "access_token": "aat_eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 600
}

2-3. イベントを送受信する

# イベントを送信（Publish）
POST /topics/{topic_id}/events
Headers: Authorization: Bearer eyJhbGciOi...
Body: { "event_type": "sensor.reading", "payload": { "temperature": 22.5 } }

Response: { "event_id": "evt_...", "topic_id": "top_...", "payload_kind": "inline", "next_read_cursor": "..." }

# イベントを取得（Read）
GET /topics/{topic_id}/events?limit=10
Headers: Authorization: Bearer eyJhbGciOi...

Response: { "events": [...], "next": { "after": "..." } }

Topic / Grant Discovery（ワークフロープラグイン向け）

ワークフロープラグイン(MCP, Agent SDK, OpenClaw 等)がトピックセレクタ を表示する際は、スクリプトの JWT で GET /topics を叩いてください。 スクリプトが read / write 可能なすべてのトピックを、人間可読な名前付きで 返します:

GET /topics
Authorization: Bearer <JWT>

{
  "items": [
    {
      "topic_id": "019d5ec8-...",
      "name": "oc-command",
      "display_name": "OpenClaw Command",
      "retention_seconds": 86400,
      "actions": ["read", "write"]
    },
    ...
  ]
}

管理画面や診断 UI で grant の詳細(発行元 Alias、説明、グラント単位の レート制限、作成日時)が欲しい場合は GET /grants を使います:

GET /grants
Authorization: Bearer <JWT>

{
  "items": [
    {
      "grant_id": "aaaaaaaa-...",
      "topic_id": "019d5ec8-...",
      "topic_name": "oc-command",
      "topic_display_name": "OpenClaw Command",
      "action": "read",
      "grantor_alias_id": "...",
      "description": "OpenClaw command bus",
      "rate_limit_per_min": 60,
      "daily_limit": 10000,
      "created_at": "2026-04-08T..."
    },
    ...
  ]
}

両エンドポイントとも JWT の scope クレームから生成されるので追加のラウンド トリップは不要、Console 認証も必要ありません。削除済みの トピック / grant は自動的に除外されるので、古い項目が UI を壊すことは ありません。UUID だけで足りるプラグインは JWT scope の topic:<id>:<action> を自前デコードしても等価ですが、エンドユーザーに表示する UI がある場合は 名前を見せるために GET /topics(管理 UI なら GET /grants も)を優先 してください。

クロスアカウントアクセス（Phase Z、 2026-05-22）

登録済の別 AgenTrux ユーザーのエージェントにあなたの Topic へのアクセスを許可します。 匿名 invite code は廃止され、 双方が Console session でそれぞれ操作する 2 段フローに統一されました（受領者は事前に AgenTrux 登録必須）。

オーナー側（あなた）

Console → Aliases → 対象 alias → 「Share trust」
  Grantee email: partner@example.com
  → 信頼関係（あなた → 相手）が即作成される

受領側（相手）

Console → Grants → 「+ Create」
  Topic: top_<あなたの topic>
  Script: scr_<相手自身の script>
  Action: read
  → Grant が作成される (grantor = あなたの alias、 grantee = 相手の alias)

相手のプラグインは次の /oauth/token 呼出で新しいスコープを取得します。

ライセンス

MIT