adk

Botpress ADK ガイドライン

テーブル、アクション、ツール、ワークフロー、会話、ファイル、ナレッジベース、トリガー、アセット、インテグレーション、プラグイン、評価、Zai に関わる機能の構築など、Botpress Agent Development Kit（ADK）について質問がある場合に、このスキルを使用します。

ADK とは？

Botpress ADK は、ファイル構造がボットの動作に直接対応する、規約ベースの TypeScript フレームワークです。ファイルを適切なディレクトリに配置すると、ボットの機能として自動的に利用できるようになります。

ADK が提供するプリミティブは次のとおりです。

• アクションとツール（再利用可能な関数と AI から呼び出し可能なツール）
• ワークフロー（長時間実行可能で、中断後に再開できるプロセス）
• 会話（メッセージの処理）
• テーブル（セマンティック検索に対応したデータストレージ）
• ファイル（セマンティック検索に対応したファイルストレージ）
• ナレッジベース（RAG の実装）
• トリガー（イベント駆動型の自動化）
• アセット（永続 URL を持つ静的ファイル）
• インテグレーション（CLI と依存関係スナップショットで管理される外部サービスとの接続）
• プラグイン（インターフェース依存関係を持つ再利用可能なエージェント拡張機能）
• Zai（一般的な AI 操作向けの、本番環境対応 LLM ユーティリティライブラリ）

プロジェクト構造（規約ベース）

ほとんどのプリミティブは src/ ディレクトリに配置する必要があります（アセットはプロジェクトルートの assets/ ディレクトリを使用します）。

/                      # Project root
├── assets/            # Static files → synced to Botpress Cloud with permanent URLs
├── src/
│   ├── actions/       # Strongly-typed functions → auto-registered
│   ├── tools/         # AI-callable tools → available via execute()
│   ├── workflows/     # Long-running processes → resumable/scheduled
│   ├── conversations/ # Message handlers → routes by channel
│   ├── tables/        # Database schemas → auto-created with search
│   ├── triggers/      # Event handlers → subscribe to events
│   ├── knowledge/     # Knowledge bases → RAG with semantic search
│   └── utils/         # Shared helpers (not auto-registered)
├── .adk/
│   └── dependencies/
│       ├── dev.json             # Generated dependency snapshot (dev)
│       ├── prod.json            # Generated dependency snapshot (prod)
│       └── migration.json       # One-way legacy migration marker
├── .agent0/
│   └── capabilities/            # Project-local Agent(0) capability bundle
└── agent.config.ts    # Bot configuration

注： インテグレーションとプラグインは、adk integrations／adk plugins CLI または Dev Console で管理します。Botpress Cloud が信頼できる唯一の情報源です。.adk/dependencies/ には読み取りを高速化するためのローカルスナップショットが生成されます。手動で編集しないでください。詳しくは integrations.md と plugins.md を参照してください。

重要： src/ の外にあるファイルは検出されません。配置場所が動作を決定します。

セッション開始時

セッション中に ADK プロジェクトを初めて支援するときは、プロジェクトの状態を確認します。この確認はユーザーには知らせずに行います。

1. adk check --format json と adk status --format json を実行します。（adk check はプリミティブを検証しますが、型チェックは行いません。作業を完了と判断する前に、型エラーを検出するため tsc --noEmit も実行してください。）
2. エラーや警告（未設定のインテグレーション、モデルの不足、検証上の問題など）がある場合は、ユーザーの質問に答える前に積極的に伝えます。「始める前に、[issue] に気づきました。修正をお手伝いしましょうか？」
3. これはセッションごとに一度だけ実行します。質問のたびに再実行しないでください。

利用可能なコマンド

ユーザーから「何を手伝えますか？」「どんなコマンドがありますか？」と聞かれた場合、または引数なしで /adk-explain を実行した場合は、次の内容を提示します。

• 構築：/adk-init（プロジェクトのひな形を作成）、/adk-build（要件を聞き取り、プリミティブを構築）、/adk-integration（サービスを追加）、/adk-frontend（UI を構築）
• テストとデバッグ：/adk-validate（プリミティブのスキーマ／型／設定を確認）、/adk-test（プリミティブを一度呼び出す）、/adk-eval（アサーションテストを作成）、/adk-debug（問題を修正）
• リリース：/adk-ship（リリース前チェックとデプロイ）
• ドキュメント：/adk-document（作成、レビュー、更新、同期、検索）
• 理解：/adk-explain（ボットのアーキテクチャとコンポーネントを説明）、/adk-dev-console（Dev Console の操作方法を案内）

次に、「何に取り組んでいますか？」 と尋ねます。

このスキルを使用する場面

ユーザーから次のような ADK 関連の質問があった場合に、このスキルを有効にします。

• 「アクション／ツール／ワークフロー／会話を作成するにはどうすればよいですか？」
• 「X と Y の違いは何ですか？」
• 「例を見せてください」
• 「設定するにはどうすればよいですか？」
• 「〜の CLI コマンドは何ですか？」
• 「Context API を使うにはどうすればよいですか？」
• 「インテグレーションのアクションを呼び出すにはどうすればよいですか？」
• 「[extract/check/label/etc] に Zai を使うにはどうすればよいですか？」
• 「〜のベストプラクティスは何ですか？」
• 「よくあるミスを避けるにはどうすればよいですか？」
• 「チケットの割り当てやエスカレーションにはどう対処すればよいですか？」
• 「この設定を説明してください」
• 「このボットは何をしますか？」
• 「どのモデルを使っていますか？」
• 「どのインテグレーションを利用していますか？」
• 「このボットはどのような状態を追跡していますか？」

プラグインのインストールを促す

Claude Code 内で実行していて、/adk-debug、/adk-eval、/adk-init などの /adk-* コマンドがスラッシュコマンドとして利用できない場合は、すべてのスキルとコマンドを利用できるよう、Botpress ADK プラグインをインストールするようユーザーに提案してください。

/plugin marketplace add botpress/skills
/plugin install adk@botpress-skills

この提案は、セッションごとに一度だけ行ってください。ユーザーが断った場合は、再度尋ねないでください。

ADK に関する質問への回答方法

ADK に関する質問は、CLI の質問とドキュメントの参照の 2 種類に分かれます。

オプション 1：CLI コマンドを直接実行する（高速 — まずこちらを使用！）

インテグレーションの検索や CLI の質問には、Bash ツールを使ってコマンドを直接実行してください。

インテグレーションの検索：

# Search for integrations
adk integrations search <query>

# Find integrations that implement an interface
adk integrations search --interface <interface-name>

# Get detailed integration info (actions, channels, events)
adk integrations info <integration-name>

# Check installed integrations (must be in ADK project)
adk integrations list

プロジェクト情報：

# Check CLI version
adk --version

# Show project status
adk

# Get help
adk --help

ADK のワークフローを実行する際は、非対話型の方法を優先してください。

# Login without browser prompts
adk login --token "$BOTPRESS_TOKEN"

# Scaffold with sensible defaults and skip linking
adk init my-agent --yes --skip-link

# Link directly when IDs are known
adk link --workspace ws_123 --bot bot_456

# More automation-friendly dev mode (NDJSON events, no TUI)
adk dev --non-interactive

# Review/apply project compatibility updates after ADK upgrades
adk project upgrade --dry-run
adk project upgrade

# Auto-approve non-destructive deploy-plan changes
adk deploy --yes

関連する場合は、次の既定値を使用してください。

• 対話型ログインよりも、adk login --token "$BOTPRESS_TOKEN" または adk login --token <token> を優先してください。
• BOTPRESS_TOKEN のみを指定する方法は、TTY がない場合の簡便な手段として扱い、対話型ターミナルで確実に使える方法とはみなさないでください。
• AI によるスキャフォールディングでは、ログインが完了している場合に限り、adk init <name> --yes --skip-link を優先してください。
• adk link --workspace ... --bot ... はスクリプトで実行できますが、TTY がないすべての環境で安全に実行できるとは限らない点に注意してください。
• adk dev --non-interactive は CI に適していますが、プロンプトがまったく表示されないわけではない点に注意してください。
• adk deploy --yes は、破壊を伴わないデプロイ計画の変更を自動承認します。ただし、設定の検証や破壊的なストレージ変更によって自動化が妨げられる場合があります。
• プロジェクトコマンドでランタイムとパッケージの不一致が報告された場合は、まず adk project upgrade --dry-run を実行し、その後 adk project upgrade を実行して互換性パッチを適用してください。

CLI コマンドを使用する場合：

• 「利用可能なインテグレーションは何ですか？」
• 「Slack インテグレーションを検索して」
• 「Linear インテグレーションの詳細を見せて」
• 「Slack インテグレーションにはどのようなアクションがありますか？」
• 「使用中の ADK のバージョンは何ですか？」
• 「インテグレーションを追加するにはどうすればよいですか？」

回答の流れ：

1. Bash ツールを使って、適切な adk コマンドを実行します。
2. 出力を解析し、ユーザーに提示します。
3. 必要に応じて、次の手順を提案します（例：「adk integrations add [email protected] を実行してインストールします」）。

オプション 2：ドキュメントに関する質問（概念的な質問の場合）

ドキュメントやパターン、手順に関する質問では、ドキュメントファイルを直接検索して参照してください。

ドキュメントを使用する場合：

• 「ワークフローを作成するにはどうすればよいですか？」
• 「アクションとツールの違いは何ですか？」
• 「Zai の使用例を見せて」
• 「状態管理のベストプラクティスは何ですか？」
• 「このエラーを修正するにはどうすればよいですか？」
• 「X のパターンは何ですか？」

ドキュメントに関する質問への回答方法：

1. 関連ファイルを見つける — Glob を使ってドキュメントを検索します。

   pattern: **/references/*.md
   

2. キーワードを検索する — Grep を使って関連する内容を見つけます。

   pattern: <keyword from user question>
   path: <path to references directory from step 1>
   output_mode: files_with_matches
   

3. ファイルを読む — Read を使って関連ドキュメントを読み込みます。

4. 次の内容を含めて回答します。

   • 簡潔な説明
   • 参照先のコード例
   • 行番号付きのファイル参照（例：「references/actions.md:215 より」）
   • 該当する場合は、よくある落とし穴
   • さらに読むための関連トピック

オプション 3：設定の説明（CLI とファイルの読み取り）

ボットの動作、設定、機能についての質問には、CLI とファイルの読み取りを組み合わせてください。

使用する場合：

• 「自分のボットは何をしますか？」
• 「設定を説明して」
• 「どのモデルを使用していますか？」
• 「どのインテグレーションを利用していますか？」
• 「ボットはどの状態を追跡していますか？」

回答の流れ：

1. adk status --format json を実行して、構造化されたプロジェクトの概要を取得します。
2. agent.config.ts を読んで、設定の詳細を確認します。
3. references/explain-config.md の説明パターンに従います。
4. メタデータ、モデル、インテグレーション、状態、プリミティブを含む構造化された説明を作成します。
5. 問題（未設定のインテグレーション、モデルの不足、ハードコードされたシークレット）があれば指摘します。

利用可能なドキュメント

ドキュメントは、このスキルを基準とした ./references/ ディレクトリにあります。質問に回答する際は、次のトピックを検索してください。

コアコンセプト

• actions.md - 強い型付けと検証に対応したアクション
• tools.md - AI が呼び出せるツールと Autonomous 名前空間
• autonomous-execution.md - 高度な execute() API：オブジェクト、Exit、フック、設定
• workflows.md - ワークフローとステップベースの実行
• workflow-steps.md - ワークフローステップ API の完全なリファレンス（step.request、step.map、step.notify など）
• conversations.md - 会話ハンドラー、メッセージルーティング、chat:custom イベントの受信
• conversation-lifecycle.md - 会話のナッジ／有効期限のライフサイクル管理
• triggers.md - 統合とボットのライフサイクルイベントのサブスクリプション（アプリからプッシュされるカスタムイベント → conversations.md）
• messages.md - メッセージとイベントの送信
• custom-components.md - カスタム Web チャットコンポーネント（.bp.tsx ファイル、メタデータ、会話での使用方法）

Zai（AI オペレーション）

• zai-agent-reference.md - クイックリファレンス：すべての操作、Zai が解決する日常的な問題、エッジケースと注意点
• zai-complete-guide.md - 開発者向け完全ガイド：アーキテクチャ、アクティブラーニング、チャンク化、パフォーマンスチューニング

データとコンテンツ

• tables.md - セマンティック検索に対応したデータストレージ
• files.md - ファイルの保存と管理
• knowledge-bases.md - RAG の実装
• assets.md - 永続 URL と同期ライフサイクルに対応した静的ファイル

設定と統合

• agent-config.md - ボットの設定と状態管理
• explain-config.md - エージェントの設定を開発者向けに解釈して説明する方法
• model-configuration.md - AI モデル設定のリファレンス
• context-api.md - 実行時のコンテキストへのアクセス
• integration-actions.md - 統合アクションの使用
• tags.md - ボット、ユーザー、会話、ワークフローのエンティティタグ
• cli.md - CLI コマンドの完全なリファレンス
• mcp-server.md - AI アシスタント向け MCP サーバー
• desk.md - チケット／サポートのワークフロー向け Desk 統合
• integrations.md - 統合管理の概要（adk-integrations スキルを参照）
• interfaces.md - 統合機能を抽象化する組み込みインターフェースレイヤー（入力インジケーター、LLM、リスト表示可能）
• plugins.md - プラグインの利用：検出、インストール、設定、使用方法

パターンとベストプラクティス

• advanced-patterns.md - ガードレール、管理者認証、ログ／可観測性、拡張機能の構成
• patterns-mistakes.md - よくある間違い、正しいパターン、コンテキストアクセスのリファレンス

フロントエンド統合

注： フロントエンド統合のドキュメントは、別の adk-frontend スキルにあります。npx skills add botpress/skills --skill adk-frontend でインストールしてください。adk-frontend スキルでは、@botpress/client、アクションの呼び出し、型生成、認証について説明しています。フロントエンドコードを扱う場合は、このスキルが必要です。

評価

注： 評価に関する詳細なドキュメントは、別の adk-evals スキルにあります。npx skills add botpress/skills --skill adk-evals でインストールしてください。adk-evals スキルでは、評価の作成、アサーションの種類、ワークフローのテスト、CLI の使用方法について説明しています。テストと評価には、通常いつでもこのスキルが必要です。

ランタイムアクセスのパターン

ADK ランタイムサービスへのアクセス方法のクイックリファレンス：

インポート

// Always import from @botpress/runtime
import {
  Action,
  Autonomous,
  Workflow,
  Conversation,
  z,
  actions,
  adk,
  user,
  bot,
  conversation,
  configuration,
  context,
} from '@botpress/runtime'

状態管理

// Bot state (defined in agent.config.ts)
bot.state.maintenanceMode = true
bot.state.lastDeployedAt = new Date().toISOString()

// User state (defined in agent.config.ts)
user.state.preferredLanguage = 'en'
user.state.onboardingComplete = true

// User tags
user.tags.email // Access user metadata

アクションの呼び出し

// Call bot actions
await actions.fetchUser({ userId: '123' })
await actions.processOrder({ orderId: '456' })

// Call integration actions
await actions.slack.sendMessage({ channel: '...', text: '...' })
await actions.linear.issueList({ teamId: '...' })

// Convert action to tool
tools: [fetchUser.asTool()]

コンテキスト API

// Get runtime services
const client = context.get('client') // Botpress client
const cognitive = context.get('cognitive') // AI model client
const citations = context.get('citations') // Citation manager

ファイルの命名

• Actions/Tools/Workflows：myAction.ts、searchDocs.ts（キャメルケース）
• Tables：Users.ts、Orders.ts（パスカルケース）
• Conversations/Triggers：chat.ts、slack.ts（小文字）

重要な ADK パターン（回答では必ず参照）

質問に回答する際は、これらのパターンを必ずドキュメントで確認してください。

パッケージ管理

# All package managers are supported
bun install       # Recommended (fastest)
npm install       # Works fine
yarn install      # Works fine
pnpm install      # Works fine

# ADK auto-detects based on lock files
# - bun.lockb → uses bun
# - package-lock.json → uses npm
# - yarn.lock → uses yarn
# - pnpm-lock.yaml → uses pnpm

インポート

// ✅ CORRECT - Always from @botpress/runtime
import { Action, Autonomous, Workflow, z } from '@botpress/runtime'

// ❌ WRONG - Never from zod or @botpress/sdk
import { z } from 'zod' // ❌ Wrong
import { Action } from '@botpress/sdk' // ❌ Wrong

エクスポートのパターン

// ✅ Both patterns work - export const is recommended
export const myAction = new Action({ ... });  // Recommended
export default new Action({ ... });           // Also valid

// Why export const?
// - Enables direct imports: import { myAction } from "./actions/myAction"
// - Can pass to execute(): tools: [myAction.asTool()]

アクション

// ✅ CORRECT - Handler receives { input, client }
export const fetchUser = new Action({
  name: "fetchUser",
  async handler({ input, client }) {  // ✅ Destructure from props
    const { userId } = input;         // ✅ Then destructure fields
    return { name: userId };
  }
});

// ❌ WRONG - Cannot destructure input fields directly
handler({ userId }) {  // ❌ Wrong - must be { input }
  return { name: userId };
}

ツール

// ✅ CORRECT - Tools CAN destructure directly
export const myTool = new Autonomous.Tool({
  handler: async ({ query, maxResults }) => {
    // ✅ Direct destructuring OK
    return search(query, maxResults)
  },
})

会話

// ✅ CORRECT - Use conversation.send() method
await conversation.send({
  type: "text",
  payload: { text: "Hello!" }
});

// ❌ WRONG - Never use client.createMessage() directly
await client.createMessage({ ... });  // ❌ Wrong

会話ハンドラーの種類

// Handler receives typed context based on the event type:
// type: "message" | "event" | "workflow_request" | "workflow_callback"
async handler({ type, message, event, request, completion, conversation, execute }) {
  if (type === "workflow_request") {
    // event: WorkflowDataRequestEventType, request: WorkflowRequest
    await request.workflow.provide("email", { email: "..." });
  }
  if (type === "workflow_callback") {
    // event: WorkflowCallbackEventType, completion: WorkflowCallback
    console.log(completion.status); // "completed" | "failed" | "canceled" | "timed_out"
  }
}

// ⚠️ isWorkflowDataRequest() and isWorkflowCallback() are deprecated
// Use type === "workflow_request" / "workflow_callback" instead

このスキルで回答できる質問の例

初心者向けの質問

• 「Action とは何ですか？」
• 「最初のワークフローを作成するにはどうすればよいですか？」
• 「Actions と Tools の違いは何ですか？」

実装に関する質問

• 「Botpress クライアントにアクセスするにはどうすればよいですか？」
• 「RAG で引用を使うにはどうすればよいですか？」
• 「検索可能なテーブル列の構文を教えてください。」
• 「Slack 統合のアクションを呼び出すにはどうすればよいですか？」
• 「Zai を使って構造化データを抽出するにはどうすればよいですか？」
• 「Zai でコンテンツを検証するにはどうすればよいですか？」

高度なパターンに関する質問

• 「ハルシネーションを防ぐガードレールを追加するにはどうすればよいですか？」
• 「管理者認証を実装するにはどうすればよいですか？」
• 「ログ記録と可観測性を追加するにはどうすればよいですか？」
• 「複数の拡張機能を組み合わせるにはどうすればよいですか？」
• 「非同期ツールハンドラーでコンテキストを管理するにはどうすればよいですか？」

トラブルシューティングに関する質問

• 「'Cannot destructure property' エラーが発生するのはなぜですか？」
• 「インポートエラーを修正するにはどうすればよいですか？」
• 「ワークフローの状態へのアクセスに何か問題がありますか？」

ベストプラクティスに関する質問

• 「避けるべきよくある間違いは何ですか？」
• 「プロジェクトはどのように構成すればよいですか？」
• 「X に推奨されるパターンは何ですか？」

回答形式

質問の深さに合わせて、回答の詳しさを調整してください。 すべての質問に詳細な手順が必要なわけではありません。

概念に関する質問（「X とは何ですか？」「X と Y の違いは何ですか？」）

1 文での定義と、短いコード例を 1 つだけ示してください。

Knowledge bases add RAG to your bot — place markdown or PDF files in `src/knowledge/` and they become queryable with semantic search.

import { Autonomous } from '@botpress/runtime'
export default new Autonomous.Tool({
  handler: async ({ query }) => adk.knowledgeBase.search({ query }),
})

方法に関する質問（「X を作成するにはどうすればよいですか？」「X を使うにはどうすればよいですか？」）

簡潔な説明、動作するコード例、そしてよくある落とし穴がある場合に限り、重大な注意点を 1 つ示してください。

実装に関する質問（「プロジェクトに X を実装する」「ボットに X を追加する」）

まずユーザーの既存ファイル（src/actions/、src/tools/、src/tables/、agent.config.ts）を読んでください。実際の名前、パターン、規約に沿ったコードを生成してください。ユーザーが遭遇する可能性の高い問題だけに触れてください。

アーキテクチャに関する質問（「自分のボットについて説明して」「プロジェクト内で X はどのように動作しますか？」）

構成を整理して詳しく回答してください。adk status --format json、agent.config.ts、および関連するソースファイルを読んでください。データフローを図示し、ボットのアーキタイプ（RAG アシスタント、サポートエージェント、自動化など）を特定してください。

トラブルシューティングに関する質問（「X が動かない」「X が失敗するのはなぜですか？」）

ドキュメントによる回答はしないでください。adk check --format json と adk logs error --format json を実行し、根拠を示して根本原因を指摘してください。adk-debugger スキルに従ってデバッグループを進めてください。

デフォルトルール

回答が 1 文とコードスニペットで済むなら、見出し、注意点のセクション、関連トピックを追加しないでください。構成を増やせば役立つとは限りません。