Hedera Policy Creation

Hedera Agent Kit ポリシーの作成

ポリシーは、BaseTool ライフサイクルに重ねられるブロッキング検証ルールです。ポリシーは 1 つ以上のステージで呼び出しをチェックし、実行を中止するために throw します — エラーは LLM エージェントに伝播します。しきい値、許可リスト/ブロックリスト、レート制限、営業時間、コンプライアンスルールなどを強制するために使用します。

ポリシーは BaseTool を継承したツールに対して のみ 発火します。BaseTool を継承せずに Tool インターフェースを直接実装したツールは、ポリシーを完全にバイパスします。

ポリシー vs. フック

目的	使用するもの
条件が成立したときに呼び出しを停止する	ポリシー（このスキル）
特定のツールメソッドを拒否する	ポリシー
しきい値 / レート制限 / 許可リスト / ブロックリスト	ポリシー
ログ、監査、コンテキストの拡充	フック（agent-kit-hook スキルを参照）

AbstractPolicy は AbstractHook を継承しているため、ポリシーは同じ Context.hooks 配列に存在し、同じライフサイクルを通って実行されます。

組み込みポリシーは @hashgraph/hedera-agent-kit/policies にあります：

• RejectToolPolicy(relevantTools: string[]) — リストされたツールメソッドを無条件にブロックします
• MaxRecipientsPolicy(maxRecipients, additionalTools?, customStrategies?) — 送金/エアドロップツールの受取人数を上限設定します

ブロッキングの実際の仕組み

ポリシーで preToolExecutionHook やその他の *Hook メソッドを 決して オーバーライドしないでください — これらは基底クラスによって配線され、あなたの shouldBlock... メソッドを呼び出し、true を返した場合に throw します。

代わりに、次のいずれか 1 つ以上をオーバーライドします：

abstract class AbstractPolicy extends AbstractHook {
  abstract name: string;
  abstract description?: string;
  abstract relevantTools: string[];

  protected shouldBlockPreToolExecution(params, method): boolean | Promise<boolean>;
  protected shouldBlockPostParamsNormalization(params, method): boolean | Promise<boolean>;
  protected shouldBlockPostCoreAction(params, method): boolean | Promise<boolean>;
  protected shouldBlockPostSecondaryAction(params, method): boolean | Promise<boolean>;
}

デフォルトはすべて false（許可）を返します。true を返すと、基底クラスが汎用のブロックエラーを throw します。shouldBlock... から独自のエラーを throw すると、メッセージを制御できます。

preToolExecutionHook などをオーバーライドしないでください — これらは AbstractPolicy では @internal です。これらがブロックフローを駆動します。これらをオーバーライドすると、ポリシーは決してブロックしなくなります。

ステージの選択

ステージ	利用可能なもの	適している用途
shouldBlockPreToolExecution	rawParams のみ	ツールメソッドによる許可リスト/ブロックリスト、時間ベース、レート制限
shouldBlockPostParamsNormalization	+ normalisedParams	解決された値に対するしきい値、受取人数
shouldBlockPostCoreAction	+ coreActionResult	送信前に構築された Transaction を検査する
shouldBlockPostSecondaryAction	+ toolResult	ごく稀 — 呼び出しはすでに実行済みで、通常は「ブロック」するには遅すぎます

ほとんどのポリシーはステージ 1（最も低コスト）またはステージ 3（デフォルトが埋められた後）に置かれます。

スケルトン

import {
  AbstractPolicy,
  PreToolExecutionParams,
  PostParamsNormalizationParams,
} from '@hashgraph/hedera-agent-kit';

export class MyPolicy extends AbstractPolicy {
  name = 'My Policy';
  description = 'What this policy blocks, in one sentence';
  relevantTools = ['transfer_hbar', 'transfer_fungible_token'];

  // Stage 1 — block by raw input or method
  protected shouldBlockPreToolExecution(
    params: PreToolExecutionParams,
    method: string,
  ): boolean {
    if (!this.relevantTools.includes(method)) return false;
    // throw new Error('<custom message>') for tailored errors
    return /* condition */ false;
  }

  // Stage 3 — block on resolved/normalised values
  protected shouldBlockPostParamsNormalization(
    params: PostParamsNormalizationParams,
    method: string,
  ): boolean {
    if (!this.relevantTools.includes(method)) return false;
    return /* condition */ false;
  }
}

relevantTools は、あなたがチェックしない限り情報提供用です — キットはすべてのツール呼び出しに対してあなたのポリシーをディスパッチします。メソッド内で最初に必ず method でフィルタリングしてください。

ポリシーの登録

ポリシーは AbstractHook のインスタンスです。これらは観察フックと同じ Context.hooks 配列に入ります：

import { AgentMode } from '@hashgraph/hedera-agent-kit';
import { allCorePlugins } from '@hashgraph/hedera-agent-kit/plugins';
import { RejectToolPolicy, MaxRecipientsPolicy } from '@hashgraph/hedera-agent-kit/policies';
import { HederaLangchainToolkit } from '@hashgraph/hedera-agent-kit-langchain';
import { MyPolicy } from './my-policy';

const toolkit = new HederaLangchainToolkit({
  client,
  configuration: {
    plugins: allCorePlugins,
    context: {
      mode: AgentMode.AUTONOMOUS,
      hooks: [
        new RejectToolPolicy(['delete_account', 'freeze_token']),
        new MaxRecipientsPolicy(5),
        new MyPolicy(),
      ],
    },
  },
});

ポリシーは各ステージで配列の順序で実行されます — 最初に true を返した（または throw した）ものが優先されます。

一般的なパターン

しきい値

protected shouldBlockPostParamsNormalization(
  params: PostParamsNormalizationParams,
  method: string,
): boolean {
  if (!this.relevantTools.includes(method)) return false;
  const p = params.normalisedParams as { amount?: number };
  return (p.amount ?? 0) > this.maxAmount;
}

許可リスト / ブロックリスト

protected shouldBlockPreToolExecution(
  params: PreToolExecutionParams,
  method: string,
): boolean {
  if (!this.relevantTools.includes(method)) return false;
  const accountId = (params.rawParams as { accountId?: string }).accountId;
  return accountId !== undefined && this.blockedAccounts.has(accountId);
}

時間ベース

protected shouldBlockPreToolExecution(
  _params: PreToolExecutionParams,
  method: string,
): boolean {
  if (!this.relevantTools.includes(method)) return false;
  const hour = new Date().getUTCHours();
  return hour < 9 || hour > 17;  // outside business hours
}

レート制限（Context をスクラッチパッドとして使用）

protected shouldBlockPreToolExecution(
  params: PreToolExecutionParams,
  method: string,
): boolean {
  if (!this.relevantTools.includes(method)) return false;
  const counters = ((params.context as any).__rateCounts ??= {} as Record<string, number>);
  counters[method] = (counters[method] ?? 0) + 1;
  return counters[method] > this.maxCallsPerSession;
}

ストラテジーマップ（カスタムツール用にプラグイン可能）

単一のポリシーがキットの知らないツールをサポートする必要がある場合、Record<string, (params) => SomeMetric> を受け入れ、additionalTools を介して追加されたすべてのツールにストラテジーがあることを検証します。これが MaxRecipientsPolicy のパターンです：

constructor(
  private maxRecipients: number,
  additionalTools: string[] = [],
  private customStrategies: Record<string, (p: any) => number> = {},
) {
  super();
  this.relevantTools = [...DEFAULT_TOOLS, ...additionalTools];
  for (const tool of additionalTools) {
    if (!this.customStrategies[tool]) {
      throw new Error(`Custom tool "${tool}" requires a strategy function`);
    }
  }
}

カスタムエラーメッセージ

デフォルトのブロックエラーは汎用的です。メッセージを制御するには、true を返す代わりに shouldBlock... メソッドから throw します：

protected shouldBlockPostParamsNormalization(
  params: PostParamsNormalizationParams,
  method: string,
): boolean {
  if (!this.relevantTools.includes(method)) return false;
  const p = params.normalisedParams as { amount?: number };
  if ((p.amount ?? 0) > this.maxAmount) {
    throw new Error(
      `[max-amount-policy] Refusing ${method}: amount ${p.amount} exceeds limit ${this.maxAmount}`,
    );
  }
  return false;
}

エージェントは throw されたメッセージをそのまま受け取ります — 有益な内容にしてください。

ベストプラクティス

1. すべての shouldBlock... メソッドの先頭で relevantTools によるフィルタリング を行います
2. 必要なデータがある最も早い段階を選びます — ステージ 1 が最も低コストです
3. ブロックする際は 明確なメッセージを付けてスローします。LLM はこれを見ます
4. *Hook メソッドをオーバーライドしないでください — shouldBlock... のみです
5. どうしても必要でない限り、ホットパスで I/O を行わないでください — ポリシーはライフサイクル内で同期的に実行されます
6. relevantTools のデフォルト値を文書化 し、利用者がポリシーの保護対象を理解できるようにします
7. ログの関連付けを容易にするため、エラーメッセージに [<policy-name>] のタグを付けます

リソース

• references/policy-interface.md — AbstractPolicy の完全な契約、各 shouldBlock がいつ発火するか
• examples/max-amount-policy/ — 上限を超える送金をブロックするしきい値ポリシー

よく使うインポート

import {
  AbstractPolicy,
  Context,
  PreToolExecutionParams,
  PostParamsNormalizationParams,
  PostCoreActionParams,
  PostSecondaryActionParams,
} from '@hashgraph/hedera-agent-kit';

// Built-in implementations live in the /policies subpath
import { RejectToolPolicy, MaxRecipientsPolicy } from '@hashgraph/hedera-agent-kit/policies';