ikura/Documentation

ikura Documentation

AIと人が、安全で再現可能な自動化をつくるためのガイド。

ikuraは、AIが設計時にTypeScriptワークフローを書き、実行時は検証済みのIRを決定論的に動かす自動化基盤です。人は説明・承認・監査を担い、AIエージェントは構造化された契約とdiagnosticを使って作成と修復を支援します。

5分で始めるアカウントを作成

5分で始める

リポジトリを取得済みの状態から、サンプルワークフローを検証する最短手順です。

1
依存関係とパッケージを準備
monorepoの依存関係を導入し、CLIと実行パッケージをbuildします。
2
ワークフローを検証
invoice-dispatch例をbuildし、構造・契約・taint・golden testを確認します。
```
pnpm install
pnpm build

cd examples/invoice-dispatch
pnpm ikura validate
pnpm ikura test
```
3
人が読める投影を確認
同じIRから説明文、フローグラフ、シナリオ別timelineを生成します。
```
pnpm ikura explain
pnpm ikura graph --mermaid
pnpm ikura timeline --scenario scenarios/happy.json
```

3つの基本概念

ikuraの自動化は、次の3つの単位で追跡できます。

Module（モジュール）

APIのaction・trigger・schema・副作用・trusted inputを定義する再利用可能な処理単位です。実行時はversionとSHA-256 digestで固定されます。

Workflow（ワークフロー）

trigger、action、AI変換、承認、retryをTypeScriptで宣言し、決定論的なIRへcompileしたものです。真実のソースはIRです。

Run（実行）

1回のワークフロー実行です。status、trace、承認、idempotency、監査証跡を持ち、durable実行では完了済みactionを繰り返さずに再開できます。

ユーザーガイド

日々の操作

MarketplaceでModuleのpublisher、trust tier、scope、side effectを確認します。
ConnectionsでOAuthまたはAPI keyを接続します。credential値は画面やtraceへ返りません。
Workflowsで説明、ノード、parameterを確認して実行します。
Runsで進行と承認待ちを確認し、失敗時はIncidentsから原因を追います。

ロール

owner / admin: 接続、Module、招待、課金、承認を管理
member: ワークフローの実行と承認、閲覧
viewer: 実行結果と構成を読み取り

AIエージェントの作業ループ

AIは、契約を先に読み、検証とsimulationを通し、差分を人へ説明してから状態変更を提案します。

01
Discover
catalogとModule metadataからtrust、scope、quirks、side effectを確認する。
02
Author
生成型を使ってworkflow TSを作成し、module lockの変更を明示する。
03
Validate
diagnosticが0件になるまで修正し、fixtureとgolden testでsimulateする。
04
Explain
ナラティブ、graph、scope、side effect、lockの差分を人へ提示する。
05
Operate
policy gate経由でdeployし、runsとincidentsから修正案をレビューへ送る。

CLIクイックリファレンス

目的	コマンド	出力
検証	`ikura validate --json`	安定code付きdiagnostic
テスト	`ikura test`	golden test結果
説明	`ikura explain`	IR由来のナラティブ
可視化	`ikura graph --mermaid`	Mermaid flowchart
副作用なし実行	`ikura run --dry-run`	fixtureを使ったRunResult
履歴	`ikura runs list`	保存済みrun一覧
公開前検証	`ikura module validate`	Module package診断

MCP — エージェント向け制御プレーン

MCPサーバーはstdio上のJSON-RPC 2.0として動作し、正規形IR、契約、run、incidentを扱います。ユーザーのTypeScriptやcredentialを公開しません。

pnpm build
pnpm --filter @ikura/mcp exec ikura-mcp

catalog.search / catalog.describe

契約、schema、trusted inputs、quirksを調べる

workflow.validate

正規形Workflow IRを検証し、構造化diagnosticを返す

workflow.simulate

fixtureで副作用なしの実行を行い、traceとtimelineを返す

workflow.explain / workflow.graph

IRから説明文とMermaidグラフを生成する

workflow.deploy

policyを評価し、deployまたは承認キューへ送る

runs.list / runs.get

保存済みrunとPIIトークナイズ済みtraceを読む

incidents.get / workflow.propose_patch

失敗を調査し、検証済み修正案をレビューへ送る

MarketplaceからインストールしたModuleは、tenant API tokenで認証したMCPクライアントのtool listにも追加できます。

セキュリティと不変条件

実行時にユーザーコードを動かさない。TypeScriptはbuild時にIRを出力するためだけに実行されます。
副作用はaction境界に限定する。実API呼び出しはRuntimeHost / activityだけが担当します。
credentialをエージェントへ見せない。secretは暗号化され、画面・trace・MCP応答に値を返しません。
LLM出力をtrusted inputへ流さない。宛先や金額にtaint付き値が使われるとvalidateが停止します。
再実行しても副作用を重ねない。idempotency ledgerとdurable journalで完了済みactionを再利用します。
実行Moduleを固定する。run開始後の暗黙更新を避け、versionとdigestを監査可能にします。

公開APIリファレンス

外部連携で使う代表的なHTTP surfaceです。認証要否と副作用はrouteごとに確認してください。

GET/api/health

サービスのhealthを確認

GET/api/registry/modules

公開Moduleを検索

GET/api/registry/modules/:name/:version

version固定artifactを取得

GET/api/agent/whoami

tokenのtenantとroleを確認

GET/api/mcp/tools

インストール済みMCP tool metadataを取得

POST/api/mcp/tools/call

宣言型Module toolを実行

実行・trigger・OAuth・publisher APIの詳細は、認証済みcontrol planeと各routeのschemaを参照してください。

用語集

Behavioral Contract: connectorのaction、trigger、schema、副作用、trusted input、表示情報を定めるversion付き契約。
IR: workflow TypeScriptから生成される決定論的な中間表現。実行と投影の真実のソース。
Projection: IRやrun履歴から生成する説明文、graph、parameter画面、timeline。読み取り専用。
Taint: LLM出力などの由来を追跡し、trusted fieldへの危険な流入を止める印。
Durable run: journalとsignalを保存し、crash後も完了済みactionを繰り返さず再開できる実行。