stackbone

Stackbone SDK スキル

このスキルでは、Stackbone ワークスペース内での作業方法を説明します。API リファレンスは含まれていません。すべてのシグネチャ、オプション、エラーコード、制限は Stackbone のドキュメントに記載されており、そこで確認してください。

情報の参照先

ドキュメントは、MCP サーバー stackbone-docs（https://docs.stackbone.ai/mcp、公開、ツール search_docs、get_doc、list_docs）経由で提供されます。CLI は stackbone init / stackbone link の実行時に、このサーバーをコーディングエージェントに接続します。stackbone docs を実行すると接続情報が表示されます。

• セッションは list_docs から開始してください。 目次が返され、各領域とセクションに含まれるすべてのページと、各ページの説明が1行で表示されます。タスクで必要なページは、以下のページの探し方で確認してください。その一覧からページのパスを取得して get_doc を実行します。パスを記憶だけで入力しないでください。ページの場所は変わることがありますが、タイトルは変わりません。
• このセッションでまだ読んでいないサーフェスへの呼び出しを記述する前に、そのページを読んでください。
• メソッド、オプション、エラーコード、制限がどのページに記載されているかわからない場合は、質問を平易な言葉で search_docs に渡してください。領域がわかっている場合は area（sdk、cli、examples、faqs、home）も渡し、最適な検索結果に対して get_doc を実行します。
• シグネチャを記憶だけで書かないでください。誤ったシグネチャでもコンパイルは通り、'use step' 内で実行時に失敗します。

セッションで stackbone-docs ツールを利用できない場合は？ https://docs.stackbone.ai/llms.txt を取得してください。同じインデックスが、ページごとにタイトル、説明、raw Markdown へのリンクを1行で示します。タイトルからページを選び、そのリンクを取得してください。https://docs.stackbone.ai/llms-full.txt には、すべてのページが1つのファイルにまとめられています（約700 KB）。

基本となる考え方

• ワークスペースは、ディスク上のファイル規約に基づいて検出されます。deep-agents/<name>/index.ts はすべてエージェントです（フォルダー名が名前となり、model はクライアントが選択するモデルです）。workflows/<name>.workflow.ts はすべてワークフローです（名前はファイル名、エクスポート名は <camelCase(name)>Workflow です）。編集が必要なレジストリはありません。
• ディープエージェントは1つのファイルで定義します。@stackbone/sdk/deep から export default defineDeepAgent({ name, model, tools }) を使います。指示はそのファイルにはなく、ボックスのカタログにあるプロンプトとして、エージェントが所有し、その名前をキーに管理されます。Studio で作成して公開します。プロセス内で実行され、ランタイムが標準の OpenAI / Anthropic チャットワイヤー経由で提供します。HTTP コードを書く必要はありません。
• ワークフローは、'use workflow' を付けた通常の非同期関数で、その副作用は 'use step' を付けたヘルパー関数内に置きます。各ステップは永続的なチェックポイントです。一度だけ実行され、永続化され、失敗時には再試行されます。
• すべてのサーフェスには、アンビエントクライアントを通じてアクセスします。どのツール本体またはステップからでも import { stackbone } from '@stackbone/sdk' を使います。createClient() も接続文字列も必要ありません。

作業手順

1. 対象を特定します。 エージェントは deep-agents/<name>/index.ts、ワークフローは workflows/<name>.workflow.ts です。存在しない場合は、stackbone add agent|workflow|workflow-agent <name> でひな形を作成します（stackbone-cli スキル）。ファイル構成や package.json のピン留めを手作業で記述しないでください。
2. 書く前に読みます。 変更が関わる各サーフェスのページを読みます（ページの探し方）。ページ全体を読んでください。必要なオプションは、通常ページの後半にあります。
3. 以下の形式でコードを記述します。 ツール本体やステップは小さく保ち、すべてのアンビエント呼び出しをその中に置きます。
4. エミュレーターで確認します。 stackbone dev を実行し、エージェントとチャットするか、stackbone workflows start <name> --input '…' を実行します。続いて stackbone runs get <runId> と stackbone logs tail --run <runId> を実行します（stackbone-cli スキル）。実行が変更箇所を通過するまでは、変更は完了していません。
5. 失敗した場合は？ stackbone-debug スキルに切り替えて原因を特定し、修正するためにここへ戻ります。

3つの形式

ディープエージェント：deep-agents/<name>/index.ts

import { tool } from '@langchain/core/tools';
import { z } from 'zod';
import { defineDeepAgent } from '@stackbone/sdk/deep';
import { stackbone } from '@stackbone/sdk';

const readTone = tool(
  async () => {
    const tone = await stackbone.config.get('tone'); // any ambient surface works here
    return tone.error ? 'neutral' : String(tone.data);
  },
  {
    name: 'read_tone',
    description: "Return the agent's current tone setting.",
    schema: z.object({}),
  },
);

export default defineDeepAgent({
  name: 'support', // must equal the folder name — it is who owns this agent's prompts
  model: 'openai/gpt-4o-mini', // a bare id, resolved through the deployment's model provider
  // No instruction here on purpose: it is a prompt keyed by this agent's name, written in
  // Studio. Add `instructions: { key, variables }` to point at another key or feed it {{vars}}.
  tools: [readTone],
  // interruptOn: { send_mail: true }, // pause for a human before this tool runs
});

永続ワークフロー：workflows/<name>.workflow.ts

import { z } from 'zod';
import { stackbone } from '@stackbone/sdk';
import { welcomes } from '../src/schema'; // your Drizzle tables live at src/schema.ts

export const inputSchema = z.object({ userId: z.string(), email: z.string().email() });
export const outputSchema = z.object({ userId: z.string(), welcomed: z.boolean() });
type OnboardingInput = z.infer<typeof inputSchema>;

export async function onboardingWorkflow(input: OnboardingInput) {
  'use workflow'; // cheap, deterministic glue: it replays on resume
  const valid = await validateSignup(input);
  return await persistWelcome(valid.userId);
}

async function validateSignup(input: OnboardingInput) {
  'use step';
  if (!input.email.includes('@')) throw new Error(`Invalid email: ${input.email}`);
  return { userId: input.userId };
}

async function persistWelcome(userId: string) {
  'use step'; // runs once, persisted, retried: make it idempotent on userId
  await stackbone.database.insert(welcomes).values({ userId }).onConflictDoNothing();
  return { userId, welcomed: true };
}

エージェントを呼び出すワークフロー：1つのステップがターンを委譲します

import { callDeepAgent } from '@stackbone/sdk/workflow';

async function askAgent(message: string) {
  'use step'; // the whole agent turn is this one durable step
  const { text } = await callDeepAgent('support', message);
  return text;
}

streamDeepAgent（同じインポート）は、workflow-agent のスキャフォールドで使用されるストリーミング版です。返信は実行のチャット画面にストリーミングされ、Studio にはワークフローがチャットとして表示されます。

どこでも共通するルール

• { data, error } を分割代入し、両方の分岐を処理してください。 すべてのアンビエントサーフェスは、この形式の値を返します。ステップを失敗させるには throw するか、処理するケースでは error.code に基づいて分岐してください。error を握りつぶしてはいけません。
• 代わりに例外をスローするサーフェスが3つあります。 stackbone.database は Drizzle ネイティブです（行を返し、エラー時はスローします）。callDeepAgent／streamDeepAgent はスローして、外側のステップを失敗させます。stackbone.connection(id) は ConnectorCallError をスローします。照合には instanceof ではなく err.code を使用してください。
• ステップは冪等にしてください。 'use step' は2回実行されることがあります。2回実行しても安全なように記述してください。
• トリガーを開始したコネクター経由で書き込みを行うワークフローには、isOwnEcho が必要です。 この書き込みによってトリガーが配信する変更が発生するため、実行が自分自身を再び開始します。重複は発生していないので、重複排除ではこれを止められません。書き込みに echoPath を指定し、書き込み前にステップをガードしてください：if (await isOwnEcho(connectorId, value)) return { … }（@stackbone/sdk/workflow からインポートします。早期リターンでも、宣言済みの outputSchema の値を返す必要があります）。value はトリガーに合わせてください。新しいオブジェクトを監視するトリガーなら、新しいオブジェクトの ID です。updatedAt などの変更列を追跡するトリガーなら、その列です。ID は変化しないため、ID でガードすると、そのオブジェクトに対する以降の人間による編集をすべて無視してしまいます。イベントの ID は絶対に使用しないでください。イベントの ID は実行のたびに新しくなります。選ぶ前に Home の Trigger events ページを読み、トリガー固有の注意事項に記載された正確なパスを使ってください。
• requestApproval() はワークフロー本体で実行し、'use step' 内では実行しません。 また、メインのバレルではなく @stackbone/sdk/workflow からインポートしてください。副作用は decision.status === 'approved' の場合にのみ実行します。
• 指示をコードに記述してはいけません。 指示はボックスのカタログにあるプロンプトで、エージェントが所有し、その名前をキーとして Studio（または stackbone prompts create）で作成・公開します。instructions: { key, variables } は別のキーを指定するか、{{vars}} を渡すものであり、指示テキストを含むものではありません。プロンプトが作成されていないエージェントでも、起動して応答します。
• モデルには単独の ID（'openai/gpt-4o-mini'）を指定してデプロイ環境のモデルプロバイダーに解決させるか、構築済みの LangChain チャットモデルインスタンスを使用します。キーを使ってクライアントを作成してはいけません。
• ランタイム依存関係はワークスペースのルート package.json（deepagents、@langchain/*、workflow）に置き、プロセスごとに1つだけ用意します。エージェントごとの package.json や、ネストした node_modules は使用しません。
• 注入される環境変数をハードコードしたり、入力を求めたりしてはいけません。 STACKBONE_POSTGRES_URL、MODEL_PROVIDER_API_KEY、MODEL_PROVIDER_BASE_URL、STACKBONE_INSTALLATION_ID、ストレージ認証情報はランタイムが注入します。オペレーターが管理する値には stackbone.secrets と stackbone.config を使用してください。
• ワークフローの契約は、兄弟関係にある inputSchema／outputSchema のエクスポートとして宣言してください。 入力型は z.infer で inputSchema から導出し、出力は推論ではなく宣言します。
• RAG スキーマはプラットフォームによってプロビジョニングされます。 独自のテーブルは src/schema.ts と stackbone db migrate create（stackbone-cli スキル）で作成してください。RAG テーブルを手書きしてはいけません。

ページの探し方

ドキュメントはコードの名前に沿っているため、検索が必要になることはほとんどありません。

• アンビエントサーフェスには、SDK の下にその名前と同じタイトルのページがあります：stackbone.database、stackbone.storage、stackbone.rag、stackbone.ai、stackbone.config、stackbone.secrets、stackbone.settings、stackbone.prompts、stackbone.connection。呼び出しを書く前に、そのページを get_doc してください（パスは list_docs で確認できます）。例外が 2 つあります：stackbone.workflows は Background jobs & workflow triggers に記載されており、requestApproval／承認サーフェスは Human-in-the-loop に記載されています。
• 各シェイプには、SDK の各セクション（Agents、Workflows、Workflow + Agents）の下に Overview と Getting started があります。セッション中にそのシェイプを初めて作成するときは、両方を読んでください。セクション内のほかのページ（Calling a sibling agent、Browser tools、Serial execution）も一覧に並んでいます。
• 独自のページがないヘルパーや型（interruptOn、callDeepAgent、callConnector、connectorTool、defineWorkspace、Result<T>、エラーコード）：識別子をそのまま search_docs で検索し、area に sdk を指定して、最上位の検索結果を確認してください。
• 具体的なサンプル：area に examples を指定して list_docs を使ってください。製品に関する質問（エージェントとワークフローのどちらか？どのモデルか？）：area に faqs を指定してください。

その他のスキル

• stackbone-cli：スキャフォールドの作成（init、add）、実行（dev）、移行（db migrate）、実行／承認／ログの管理、リリース（build、package、link）。
• stackbone-debug：エラー、失敗または停止した実行、保留中の承認の原因を特定します。
• stackbone-coder：一行のアイデアからインタビューを通じて新しいものを始め、その後、コード作成のためにこちらに戻ります。