SDK

概要

@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

クイックスタート

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

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

const client = createClient({
  apiKey: process.env.JINBA_TB_API_KEY!,
  organizationId: "org-id", // optional default
});

ToolSetの一覧を取得する

const toolSets = await client.listToolSets();
console.log(toolSets);

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;
}

SDKに組み込まれているデフォルトの baseUrl は https://toolbox-api.jinba.dev（ステージングAPI）です。本番のToolboxに接続するには、baseUrl に https://toolbox-api.jinba.io を明示的に指定してください。

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

const client = createClient({
  baseUrl: "https://toolbox-api.jinba.io",
  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

listOrganizations() と getOrganization() が呼び出すエンドポイントは、サインイン済みユーザーのセッションを必要とします。APIキー（SDKが送信する唯一の認証情報）では、ステータス 401 の JinbaTBError で失敗します。

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を作成
// inputSchema / outputSchema はSDKの型には含まれますがAPIでは無視されます。
// 両方のスキーマは `code` 内の `input` / `output` 定義から抽出されます。
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: {} },
  outputSchema: { type: "object", properties: {} },
  code: `import { z } from "zod";

export const input = z.object({
  channel: z.string().describe("Channel name or ID"),
  text: z.string().describe("Message text"),
});

export const output = z.object({
  ts: z.string(),
  channel: z.string(),
});

export async function run(data: z.infer<typeof input>) {
  // tool implementation code
  return { ts: "1234567890.123456", channel: data.channel };
}`,
});

// 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は不要）
// 注意: テストエンドポイントはサインイン済みユーザーのセッションを必要とし、
// APIキーで呼び出すと401を返します。代わりにコンソールのテストパネルを使用してください。
const testResult = await client.test("slack-tools", "post-message", {
  channel: "#test",
  text: "Testing...",
});

run() は組織の実行エンドポイントに { input, version } を送信します。組織IDはコンストラクタまたは options.orgId で指定する必要があります。

Version

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

// 新しいVersionを公開
// 注意: 公開にはサインイン済みユーザーのセッションが必要です（APIが公開者を記録するため）。
// APIキーでは失敗します。代わりにコンソールから公開してください。
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;
  icon?: string | null;
  tags: string[];
  sandbox: SandboxConfig;
  visibility: "public" | "private" | "restricted"; // APIが返すのは "public" | "private" のみ
  mcpEnabled: boolean;
  latestVersion?: string | null;
  publishedVersion?: string | null;
  createdAt: string;
  updatedAt: string;
  publishedAt?: string | null;
}

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ステータスコードがスローされます。APIはRFC 9457 Problem Details（error ではなく detail）で応答するため、error.message は通常 Request failed with status <code> になります。原因で分岐するには statusCode を確認してください（例：クレジット不足は 402）。

ベストプラクティス

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

Docs

概要

インストール

クイックスタート

クライアント設定

APIリファレンス

組織

ToolSet

Tool

実行

Version

実行履歴

主要な型

RunResult

ToolSet

Tool

エラーハンドリング

ベストプラクティス

関連ドキュメント

​概要

​インストール

​クイックスタート

​クライアント設定

​APIリファレンス

​組織

​ToolSet

​Tool

​実行

​Version

​実行履歴

​主要な型

​RunResult

​ToolSet

​Tool

​エラーハンドリング

​ベストプラクティス

​関連ドキュメント

概要

インストール

クイックスタート

クライアント設定

APIリファレンス

組織

ToolSet

Tool

実行

Version

実行履歴

主要な型

RunResult

ToolSet

Tool

エラーハンドリング

ベストプラクティス

関連ドキュメント