SDK

@jinba-toolbox/sdkパッケージを使用してTypeScriptおよびJavaScriptアプリケーションからJinba Toolboxを操作する

​

概要

@jinba-toolbox/sdk パッケージは、Jinba Toolboxに登録されたToolを利用するための型安全なクライアントライブラリです。REST APIをラップし、ToolSetの一覧取得、Toolの実行、Versionの管理、実行履歴の取得などの便利なメソッドを提供します。

想定される利用者:

• Toolを実行するAIエージェント
• 自動化のためのCLIツール
• Jinba Toolboxと統合するサードパーティアプリケーション
• Jinba Toolbox上で開発する開発者

​

インストール

# npm
npm install @jinba-toolbox/sdk

# pnpm
pnpm add @jinba-toolbox/sdk

# yarn
yarn add @jinba-toolbox/sdk

​

クイックスタート

1. インポートしてクライアントを作成する

   import { createClient } from "@jinba-toolbox/sdk";
   
   const client = createClient({
     apiKey: process.env.JINBA_TB_API_KEY!,
     organizationId: "org-id", // optional default
   });
   
2. ToolSetの一覧を取得する

   const toolSets = await client.listToolSets();
   console.log(toolSets);
   
3. Toolを実行する

   const result = await client.run("slack-tools", "post-message", {
     channel: "#general",
     text: "Hello from Jinba Toolbox!",
   });
   
   console.log(result.output);
   // { ts: "1234567890.123456", channel: "C01234567" }
   

​

クライアント設定

createClient 関数は JinbaTBClientConfig オブジェクトを受け取ります：

interface JinbaTBClientConfig {
  /** APIベースURL（デフォルト: https://toolbox-api.jinba.dev） */
  baseUrl?: string;
  /** 認証用APIキー */
  apiKey: string;
  /** デフォルトの組織ID（省略可能、リクエストごとにオーバーライド可能） */
  organizationId?: string;
  /** リクエストタイムアウト（ミリ秒、デフォルト: 30000） */
  timeout?: number;
}

すべてのオプションを指定した例：

const client = createClient({
  baseUrl: "https://toolbox-api.jinba.dev",
  apiKey: "jtb_xxxxxxxxxxxx",
  organizationId: "org_abc123",
  timeout: 60000,
});

コンストラクタで organizationId を設定すると、個々のメソッド呼び出しで省略できます。すべてのメソッドには、デフォルトをオーバーライドするためのオプションの orgId パラメータも用意されています。

​

APIリファレンス

​

組織

// 認証済みユーザーが所属する組織の一覧を取得
const orgs = await client.listOrganizations();
// Returns: OrganizationWithRole[]

// 組織の詳細を取得
const org = await client.getOrganization("org-id");
// Returns: Organization

​

ToolSet

// 組織内のToolSet一覧を取得
const toolSets = await client.listToolSets();
// Returns: ToolSet[]

// スラッグでToolSetを取得（Toolを含む）
const toolSet = await client.getToolSet("slack-tools");
// Returns: ToolSet & { tools: Tool[] }

// 新しいToolSetを作成
const newToolSet = await client.createToolSet({
  slug: "slack-tools",
  name: { default: "Slack Tools" },
  description: { default: "Slack integration tools" },
  sandbox: {
    provider: "e2b",
    language: "typescript",
    packages: [{ name: "@slack/web-api" }],
    resources: { timeout: 60000 },
  },
  visibility: "private",
  tags: ["slack"],
});

// ToolSetを更新
await client.updateToolSet("slack-tools", {
  visibility: "public",
  tags: ["slack", "messaging"],
});

// ToolSetを削除
await client.deleteToolSet("slack-tools");

​

Tool

// ToolSet内のTool一覧を取得
const tools = await client.listTools("slack-tools");
// Returns: Tool[]

// スラッグでToolを取得
const tool = await client.getTool("slack-tools", "post-message");
// Returns: Tool

// 新しいToolを作成
const newTool = await client.createTool("slack-tools", {
  slug: "post-message",
  name: { default: "Post Message" },
  description: { default: "Post a message to a Slack channel" },
  inputSchema: {
    type: "object",
    properties: {
      channel: { type: "string", description: "Channel name or ID" },
      text: { type: "string", description: "Message text" },
    },
    required: ["channel", "text"],
  },
  outputSchema: {
    type: "object",
    properties: {
      ts: { type: "string" },
      channel: { type: "string" },
    },
  },
  code: `// tool implementation code`,
});

// Toolを更新
await client.updateTool("slack-tools", "post-message", {
  description: { default: "Post a message to any Slack channel" },
});

// Toolを削除
await client.deleteTool("slack-tools", "post-message");

​

実行

// 公開済みToolを実行
const result = await client.run("slack-tools", "post-message", {
  channel: "#general",
  text: "Hello!",
});
// Returns: RunResult

console.log(result.success);    // true
console.log(result.output);     // { ts: "...", channel: "..." }
console.log(result.durationMs); // 1234

// 特定のVersionを指定して実行
const result = await client.run(
  "slack-tools",
  "post-message",
  { channel: "#general", text: "Hello!" },
  { version: "1.2.0" }
);

// Toolをテスト（ドラフトコードを実行、公開Versionは不要）
const testResult = await client.test("slack-tools", "post-message", {
  channel: "#test",
  text: "Testing...",
});

​

Version

// ToolSetのVersion一覧を取得
const versions = await client.listVersions("slack-tools");
// Returns: ToolSetVersion[]

// 新しいVersionを公開
const version = await client.publishVersion("slack-tools", {
  version: "1.3.0",
  releaseNotes: "Added thread reply support",
});
// Returns: ToolSetVersion

​

実行履歴

// 組織内のRun一覧を取得
const runs = await client.listRuns();
// Returns: Run[]

// Runの詳細を取得
const run = await client.getRun("run_abc123");
// Returns: Run

​

主要な型

​

RunResult

run() と test() から返されるオブジェクト：

interface RunResult {
  runId: string;
  version: string;
  success: boolean;
  output?: Record<string, unknown>;
  error?: { name: string; message: string; traceback?: string };
  logs?: { stdout: string[]; stderr: string[] };
  durationMs?: number;
}

​

ToolSet

interface ToolSet {
  id: string;
  organizationId: string;
  slug: string;
  name: LocalizedText;
  description: LocalizedText;
  sandbox: SandboxConfig;
  visibility: "public" | "private" | "restricted";
  mcpEnabled: boolean;
  tags: string[];
  latestVersion?: string | null;
  publishedVersion?: string | null;
  createdAt: string;
  updatedAt: string;
}

​

Tool

interface Tool {
  id: string;
  toolSetId: string;
  slug: string;
  name: LocalizedText;
  description: LocalizedText;
  inputSchema: JSONSchema;
  outputSchema: JSONSchema;
  code: string;
  entrypoint?: string | null;
  createdAt: string;
  updatedAt: string;
}

​

エラーハンドリング

SDKは非2xxレスポンスに対して JinbaTBError をスローします：

import { JinbaTBError } from "@jinba-toolbox/sdk";

try {
  const result = await client.run("my-toolset", "my-tool", { input: "data" });
} catch (error) {
  if (error instanceof JinbaTBError) {
    console.error(`Status: ${error.statusCode}`);
    console.error(`Message: ${error.message}`);
    console.error(`Details: ${JSON.stringify(error.details)}`);
  }
}

リクエストが設定されたタイムアウトを超えた場合、408ステータスコードがスローされます。

​

ベストプラクティス

• コンストラクタでデフォルトの organizationId を設定する — すべてのメソッドに渡す手間を省けます。
• APIキーには環境変数を使用する — 認証情報を絶対にハードコードしないでください。
• JinbaTBError を適切にハンドリングする — クライアントエラー（4xx）とサーバーエラー（5xx）を区別できます。
• timeout を延長する — 複雑なSandboxワークロードを実行するToolの場合に有効です。
• run() 呼び出し時にVersionを指定する — アプリケーションが決定論的な動作に依存する場合に推奨します。

​

関連ドキュメント

• REST API — 完全なエンドポイントリファレンス
• MCP統合 — ToolSetをAIエージェント向けMCPサーバーとして使用
• バージョニングと公開 — Versionのライフサイクルを理解する