設定 — ActQL Docs

Hostが読むすべてのファイルと環境変数を、フィールドごとに説明します。これはリファレンスで、組み合わせ方はローカルとリモートのHostで説明しています。設定が決めるのは、Hostが何をしてよく、何を記録するかです。プログラムの意味に入り込むことはありません。

`actql.config.json`

プロジェクトのファイルです。CLIは、現在のディレクトリから上に向かって actql.config.json を探し、その中のパスをすべてファイルからの相対パスとして解決します。SDKは connect() のオプションとして同じフィールドを受け付けます。CLIの --config <file> は別のファイルを明示的に選び、コマンドのフラグはファイルの値を上書きします。このファイルが供給するのは接続、model task、Store、フィクスチャです。権限を与えたり承認者を指定したりはできません。それらは下のHostの設定にあり、cloneしたリポジトリから変えることはできません。

{
  "version": "actql-config/0.1",
  "connectors": "./connectors.json",
  "model_tasks": "./model-tasks.json",
  "lock": "./actql.lock.json",
  "state_dir": "./.actql",
  "profile": "mock",
  "mock": {
    "data": "./mock/data.json",
    "answers": {"model-task:churn-risk.v1": "./mock/churn-risk.v1.answers.yaml"}
  }
}

フィールド	型	意味	既定
`version`	string	常に `actql-config/0.1`。	必須
`connectors`	path	Connectorファイル。	なし。読み書きをするプログラムには必要
`model_tasks`	path	model taskファイル。タスクとプロバイダーの登録ファイル。	なし。`INFER` には必要
`lock`	path	ConnectorとModel taskの契約を固定するロックファイル。	なし
`state_dir`	path	Store。Run、観測、Result、Checkpoint、鍵を置く。バージョン管理には入れない。	`./.actql`
`profile`	string	`mock` のような名前付きのプロファイル。`--profile` の指定がなければこれが使われる。	なし
`mock`	object	mockプロファイルのフィクスチャ。`data` は各mock Connectorが返すレコード（各読み取り元の `key` を含む）、`answers` はmodel taskごとの答えのファイル。ファイル名から自動で探すことはない。	なし。その場合、mockプロファイルにはレコードも答えもない

Hostの設定

actql init が作る ~/.config/actql/host.json、または --host-config で指定したファイルです。権限を与え、検証するものを置きます。アカウント設定、delegateされた操作に対するHostの判断、受け付ける承認者です。プロジェクトのファイルからここに足すことはできません。

{
  "version": "actql-host/0.1",
  "account_config": "./accounts.json",
  "run_policy": {
    "principal": "agent:churn-risk",
    "namespace": "acme",
    "policy_contract_cid": "sha256:…",
    "decision": "review",
    "expires_at": "2027-01-01T00:00:00.000Z"
  },
  "effect_policy": {
    "decision": "review",
    "policy_contract_cid": "sha256:…"
  },
  "signers": {
    "ops-approver": {
      "principal": "ops",
      "key_id": "ops-2026",
      "private_key": "./keys/ops.pem",
      "public_key": "./keys/ops.pub.pem",
      "checkpoint_kinds": ["effect_set"]
    }
  }
}

フィールド	型	意味	既定
`version`	string	常に `actql-host/0.1`。	必須
`account_config`	path	保護された操作ごとに allow、deny、delegate を振り分けるアカウント設定。	なし。Hostの標準のポリシーが適用される。純粋な計算、設定した接続からの読み取り、登録したタスクによる `INFER` は動き、すべてのEffectは `effect_policy` に委ねられる
`run_policy`	object	delegateされたRun全体の判断に対する、Hostの判断（後述）。	なし
`effect_policy`	object	delegateされたEffect Setの判断に対する、Hostの判断。	`{"decision": "review"}`
`signers`	object	Hostが受け付ける承認者。承認者のIDをキーにする。	なし。承認は `actql init` がStoreに生成したローカルの鍵で署名される。この鍵が示すのはマシンのユーザー

`run_policy` と `effect_policy`

アカウント設定の答えが delegate のとき、Hostはこれらのポリシーを参照します。それぞれが、その種類の境界に対するHostの判断です。

フィールド	型	意味
`decision`	`allow` \| `review` \| `deny`	`allow` はその場で許可する。`review` はCheckpointで止まり、承認者を待つ。`deny` は拒否する。これらの判断が使われるのはアカウント設定の答えが `delegate` のときだけで、アカウント設定の明示的な `deny` が覆されることはない。
`policy_contract_cid`	string	判断が記録されるポリシー契約の識別子。
`principal`	string	（`run_policy`）Runを実行するprincipal。
`namespace`	string	（`run_policy`）Runが属するnamespace。
`expires_at`	timestamp	（`run_policy`）このポリシーの有効期限。

Hostをアプリに組み込んでいる場合は、自分のコードの判断フック（Effectと承認の判断の委譲先）が review の代わりになります。

`signers`

フィールド	型	意味
`principal`	string	承認者が誰として振る舞うか。
`key_id`	string	すべての承認とともに記録される識別子。
`private_key`、`public_key`	path	PEMファイル。Hostは設定された承認者だけを受け付ける。承認が自前の鍵を持ち込むことはない。
`checkpoint_kinds`	array	この承認者が解決できるCheckpointの種類。たとえば `effect_set`。

Connectorファイル

Hostが提供する接続を列挙するJSON文書で、プログラムが使う名前（salesforce.accounts の salesforce）をキーにします。各エントリには、Connector、アカウントやエンドポイント、認証情報の出どころを書きます。認証情報は参照するだけで、ファイルには書き込みません。

{
  "version": "actql-connectors/0.1",
  "connections": {
    "salesforce": {
      "connector": "salesforce",
      "instance_url": "https://acme.my.salesforce.com",
      "credentials": {"access_token": {"env": "SALESFORCE_ACCESS_TOKEN"}}
    },
    "snowflake": {
      "connector": "snowflake",
      "account": "acme-prod",
      "database": "ANALYTICS",
      "user": "ACTQL",
      "credentials": {"private_key": {"path": "./keys/snowflake.p8"}}
    }
  }
}

フィールド	型	意味
`connector`	string	この接続を扱うConnector（Connectorを参照）。
接続のフィールド	さまざま	エンドポイント、アカウント、データベース、プロジェクトなど。各Connectorのページに記載。
`credentials`	object	Connectorが必要とする秘密情報ごとに1項目。環境変数（`{"env": "NAME"}`）かファイル（`{"path": "./file"}`）を参照する。秘密情報を直接書くことはない。フィールドは各Connectorのページに記載。

--profile mock オプションは、このファイルを編集することなく、すべての接続を mock.data のレコードを返すmock Connectorに、LLMを mock.answers の答えに置き換えます。

model taskファイル

INFER が名前で参照できるmodel taskを列挙し、それぞれの定義ファイルの場所と、LLMのプロバイダーを書くJSON文書です。

{
  "version": "actql-model-tasks/0.1",
  "tasks": {
    "model-task:churn-risk.v1": "./model-tasks/churn-risk.v1.yaml"
  },
  "providers": {
    "openai": {"type": "openai", "api_key_env": "OPENAI_API_KEY"}
  },
  "default_provider": "openai"
}

フィールド	型	意味
`tasks`	object	model taskのID → 定義ファイルのパス。
`providers`	object	名前付きのプロバイダー。`type` がAPIを選び、`api_key_env` がキーを持つ環境変数の名前。model taskは `model` セクションでプロバイダーを選べる。
`default_provider`	string	プロバイダーを指定していないタスクが使うプロバイダー。

定義ファイルの形式（task、input、instructions、output、model、limits）はLLMとINFERで説明しています。

アカウント設定

actql-execution-account-config/0.1 文書は、保護された操作のそれぞれについて、許可するか、拒否するか、Hostの判断に委ねるかを決めます。権限を与える場所はここだけで、プログラムから変えることはできません。

{
  "version": "actql-execution-account-config/0.1",
  "account_id": "acme-prod",
  "entries": [
    {
      "entry_id": "reads",
      "outcome": "allow",
      "principal": {"any_of": ["agent:churn-risk"]},
      "connection": {"all": true},
      "resource": {"all": true},
      "operation": {"any_of": ["read"]},
      "exclusions": []
    },
    {
      "entry_id": "salesforce-writes",
      "outcome": "delegate",
      "principal": {"any_of": ["agent:churn-risk"]},
      "connection": {"any_of": ["salesforce"]},
      "resource": {"all": true},
      "operation": {"any_of": ["effect"]},
      "exclusions": []
    }
  ]
}

フィールド	型	意味
`account_id`	string	この設定が記述する実行アカウント。
`entries[].entry_id`	string	一意。エントリは昇順に並べる。
`entries[].outcome`	`allow` \| `deny` \| `delegate`	エントリが一致したときにどうするか。
`entries[].principal`、`connection`、`resource`、`operation`	セレクター	`{"all": true}`（現在と将来のメンバー）または `{"any_of": [ids]}`（厳密な識別子）。
`entries[].exclusions`	array	このエントリの集合から取り除くタプル（次元ごとに1つのセレクター）。

操作は read（カタログやメタデータを含むあらゆる読み取り）、infer（LLMの呼び出し）、write（別のシステムやストアに出ていくデータ）、effect（Effectのコミット）です。識別子は厳密な一致で比べます。接頭辞、パターン、大文字小文字の畳み込みはありません。

結果の異なる2つのエントリが重なってはいけません。重なりがあれば、順序にかかわらずHostはその設定を拒否します。設定を書いた場合、どのエントリにも一致しない操作は拒否され、明示的な deny ではなく「一致なし」として報告されます。不正なファイルは拒否され、許可と読まれることはありません。ファイルがまったくない場合はHostの標準のポリシー（ローカルとリモートのHost）が適用されます。読み取り、INFER、Effectを承認待ちにすることに、設定は要りません。

ロックファイル

actql lock は actql.lock.json を書き出します。Hostが解決したConnectorの契約、カタログのスナップショット、model taskの定義を、それぞれの識別子とともに正確に記録したものです。actql verify lock は、それらが今も一致することを確かめます。Runは実行時のロックを記録するので、Connectorの契約が変わっていれば、黙って使われるのではなく検出されます。

環境変数

変数	意味
`ACTQL_CONFIG`	上に向かって探す代わりに使う、設定ファイルのパス。
`ACTQL_STATE_DIR`	`state_dir` を上書きする。
`ACTQL_PROFILE`	既定のプロファイル。たとえば `mock`。
認証情報の変数	Connectorファイルとmodel taskファイルが `credentials.env` で参照している名前。
`ACTQL_LOG`	Hostのログレベル（`error`、`warn`、`info`、`debug`）。

環境変数は設定を選ぶためのもので、プログラムから読まれることはありません。

設定

actql.config.jsonCopy Anchor Link

Hostの設定Copy Anchor Link

run_policy と effect_policyCopy Anchor Link

signersCopy Anchor Link

ConnectorファイルCopy Anchor Link

model taskファイルCopy Anchor Link

アカウント設定Copy Anchor Link

ロックファイルCopy Anchor Link

環境変数Copy Anchor Link