メインコンテンツへスキップ

​
概要

Tools API は Shannon のツールレジストリへの直接アクセスを提供します。利用可能なツールの一覧表示、パラメータ Schema の確認、タスクワークフローを経由せずにツールを直接実行できます。

​
機能

  • ツール検索 — カテゴリフィルタリングで利用可能なすべてのツールを閲覧
  • JSON Schema 確認 — 任意のツールの完全なパラメータ Schema を取得
  • 直接実行 — Agent ワークフロー外でツールを呼び出し
  • 危険なツールのブロック — 危険とマークされたツールは Gateway レベルで自動的に非表示・ブロック
  • 使用量トラッキング — 実行ごとに Token 消費量とコストを記録
  • Session コンテキスト — オプションで Session にバインド（session_id と user_id のみに制限）

​
セキュリティモデル

Shannon は dangerous とマークされたツールに対して厳格なセキュリティ境界を適用します：
  • List エンドポイントは exclude_dangerous=true を自動適用 — 危険なツールは公開されません
  • Get および Execute エンドポイントは危険なツールに対して 403 Forbidden を返します
  • ツールメタデータは各 Gateway インスタンスで 5 分間インメモリキャッシュされます
  • ツール実行の HTTP クライアントタイムアウトは 120 秒です
危険なツールはいかなる公開 API エンドポイントからもアクセスできません。この制限は Gateway レベルで強制され、クライアントから回避することはできません。

​
ツール一覧の取得

利用可能なすべてのツールを一覧表示します。危険なツールは自動的に除外されます。 
curl http://localhost:8080/api/v1/tools \
  -H "Authorization: Bearer <token>"

​
クエリパラメータ

パラメータ型必須説明
categorystringいいえカテゴリでフィルタリング（例："search"、"code"）

​
カテゴリフィルタの例

curl "http://localhost:8080/api/v1/tools?category=search" \
  -H "Authorization: Bearer <token>"

​
レスポンス

[
  {
    "name": "web_search",
    "description": "Search the web for current information",
    "category": "search",
    "version": "1.0",
    "parameters": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "Search query"
        },
        "max_results": {
          "type": "integer",
          "description": "Maximum number of results",
          "default": 10
        }
      },
      "required": ["query"]
    },
    "timeout_seconds": 30,
    "cost_per_use": 0.004
  }
]

​
ツールの取得

指定したツールのメタデータとパラメータ Schema を取得します。 
curl http://localhost:8080/api/v1/tools/web_search \
  -H "Authorization: Bearer <token>"

​
パスパラメータ

パラメータ型必須説明
namestringはいツール名

​
レスポンス

{
  "name": "web_search",
  "description": "Search the web for current information",
  "category": "search",
  "version": "1.0",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      },
      "max_results": {
        "type": "integer",
        "description": "Maximum number of results",
        "default": 10
      }
    },
    "required": ["query"]
  },
  "timeout_seconds": 30,
  "cost_per_use": 0.004
}

​
ツールの実行

指定した引数でツールを直接実行します。 
curl -X POST http://localhost:8080/api/v1/tools/web_search/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "arguments": {
      "query": "latest AI news",
      "max_results": 5
    },
    "session_id": "optional-session-id"
  }'

​
パスパラメータ

パラメータ型必須説明
namestringはいツール名

​
リクエストボディ

フィールド型必須説明
argumentsobjectはいツールのパラメータ Schema に一致するツール固有の引数
session_idstringいいえコンテキストバインド用の Session ID
session_id を指定した場合、ツールには session_id と user_id のみが渡されます。セキュリティのため、tenant_id などの他の Session フィールドは除去されます。

​
レスポンス

{
  "success": true,
  "output": {
    "results": [
      {
        "title": "Major AI Breakthrough Announced",
        "url": "https://example.com/ai-news",
        "snippet": "Researchers announce a significant advancement in..."
      }
    ]
  },
  "text": "Found 5 results for 'latest AI news'",
  "error": null,
  "metadata": {
    "source": "searchapi"
  },
  "execution_time_ms": 1234,
  "usage": {
    "tokens": 7500,
    "cost_usd": 0.004
  }
}

​
レスポンスフィールド

フィールド型説明
successboolean実行が正常に完了したかどうか
outputobjectツールからの構造化出力
textstring人間が読める結果の要約
errorstring | null実行失敗時のエラーメッセージ
metadataobjectツール固有のメタデータ（例：データソース）
execution_time_msinteger実行時間（ミリ秒）
usage.tokensintegerこの実行の Token 数
usage.cost_usdnumber推定コスト（USD）
使用量は非同期（fire-and-forget）で token_usage テーブルに記録されます。Token 数は合成値です：max(100, int(cost_usd / 0.000002))。

​
ツールレスポンスオブジェクト

フィールド型説明
namestringツール識別子
descriptionstring人間が読める説明
categorystringツールカテゴリ（例："search"、"code"、"data"）
versionstringツールバージョン
parametersobject (JSON Schema)ツールのパラメータ Schema
timeout_secondsinteger許容される最大実行時間
cost_per_usenumber1 回の呼び出しあたりの推定コスト（USD）

​
エラーレスポンス

ステータスエラー説明
400Bad requestツール名の欠落またはリクエストボディが無効
401Unauthorized認証情報の欠落または無効
403Forbiddenツールが危険とマークされておりアクセス不可
404Tool not found指定された名前のツールが存在しない
502Bad gatewayLLM Service（ツールバックエンド）が利用不可
すべてのエラーは標準フォーマットに従います： 
{
  "error": "error message here"
}

​
危険なツールのエラー

Get または Execute で危険なツールにアクセスしようとすると以下が返されます： 
{
  "error": "Tool not available via direct execution"
}

​
次のステップ

カスタムツール

カスタムツールの作成と登録方法を学ぶ

エージェント

ツールを自動的に使用する Agent を設定