@claude-vector/agent-api

AIエージェント向けの構造化APIレイヤー。claude-searchの機能をRESTful APIとして提供し、AIエージェントが効率的に利用できるよう設計されています。

特徴

• 🔌 構造化API - JSON形式の統一されたレスポンス
• 📊 予測システム - 操作の時間・リソース・コストを事前予測
• 🔄 トランザクション管理 - 安全なロールバック機能
• 📡 非同期追跡 - 長時間実行操作のリアルタイム監視
• 🎯 能力宣言 - 利用可能な機能の自動検出
• 🚀 WebSocket対応 - リアルタイム更新通知

インストール

npm install @claude-vector/agent-api

使用方法

サーバーの起動

CLIから起動（推奨）

# claude-searchコマンドを使用
claude-search agent --port 3000

# カスタムホストとポート
claude-search agent --host 0.0.0.0 --port 8080

プログラムから起動

import { AgentAPIServer } from '@claude-vector/agent-api';

const server = new AgentAPIServer({
  port: 3000,
  host: 'localhost'
});

await server.start();

クライアントの使用

import { createClient } from '@claude-vector/agent-api';

const client = createClient('http://localhost:3000');

// 能力確認
const capabilities = await client.getCapabilities();
console.log(capabilities.data.features);

// 検索実行
const searchResult = await client.search('authentication middleware', {
  limit: 20,
  threshold: 0.3  // 推奨値（詳細は下記の閾値設定ガイド参照）
});

// セッション作成
const session = await client.createSession('Fix login bug', {
  priority: 'high',
  autoContext: true
});

// 非同期操作の開始（全インデックス再作成）
const operation = await client.startOperation('index', {
  path: './src',
  force: true  // 既存インデックスを削除して再作成
});

// 非同期操作の開始（差分更新）
const incrementalOp = await client.startOperation('index', {
  path: './src',
  force: false  // 変更されたファイルのみ更新（デフォルト）
});

// 操作状態の確認
const status = await client.getOperation(operation.data.operationId);
console.log('Status:', status.data.status);  // 'queued', 'in_progress', 'completed', 'failed'
console.log('Progress:', status.data.progress);  // 0-100

// 完了時の結果
if (status.data.status === 'completed') {
  console.log('Index stats:', status.data.result.stats);
  // { fileCount: 234, chunkCount: 1456, indexSize: 18432000 }
}

🎯 閾値設定ガイド

推奨値

• デフォルト: 0.3 - ほとんどのユースケースで最適
• 0.5以上: 非常に高い関連性のみ（完全一致に近い）
• 0.3-0.5: 関連性のある結果（推奨範囲）
• 0.1-0.3: 幅広い結果（関連性は低め）

用途別の設定例

// 厳密な検索（関数名や変数名の完全一致）
await client.search('getUserById', { threshold: 0.5 });

// 一般的なコード検索（推奨）
await client.search('authentication logic', { threshold: 0.3 });

// 探索的な検索（広範囲の関連コード）
await client.search('caching strategy', { threshold: 0.2 });

新機能：自動閾値調整

結果が0件の場合、自動的に閾値を下げて再検索します：

// format: 'simple' で簡潔なレスポンス
const result = await client.search('specific feature', {
  threshold: 0.5,
  autoRetry: true,  // デフォルトで有効
  format: 'simple'   // 新機能：簡潔なレスポンス
});

// 自動調整が行われた場合
if (result.note) {
  console.log(result.note);
  // "Auto-adjusted threshold from 0.5 to 0.3"
}

レスポンスフォーマット

// シンプルモード（format: 'simple'）
{
  query: "authentication",
  results: [
    { file: "auth.js", score: 0.85, summary: "function authenticate(user) {..." },
    { file: "middleware.js", score: 0.72, summary: "const authMiddleware = (req, res..." }
  ],
  count: 2
}

// 詳細モード（デフォルト）
{
  query: "authentication",
  results: [
    { 
      file: "auth.js", 
      score: 0.85, 
      content: "full content here...",
      line: 42
    }
  ],
  executionTime: 134,
  threshold: 0.3,
  limit: 10
}

API エンドポイント

基本エンドポイント

• GET /health - ヘルスチェック
• GET /api-docs - APIドキュメント（ブラウザで表示可能）
• GET /api/capabilities - 利用可能な機能の一覧

検索・インデックス

• POST /api/search - セマンティック検索の実行
  • 実際のVectorSearchEngineを使用
  • リアルタイムでコードベースを検索
• POST /api/operations - インデックス作成などの非同期操作
  • type: "index" - インデックスの作成/更新
    • force: true - 全インデックス再作成
    • force: false - 差分更新（デフォルト）
  • WebSocketで進捗をリアルタイム配信
  • v1.3.2新機能: プロジェクトの.claude-search.config.jsから除外パターンを自動読み込み

インデックス作成時の除外パターン設定

Agent APIは自動的にプロジェクトルートの.claude-search.config.jsを読み込み、除外パターンを適用します：

// .claude-search.config.js の例
export default {
  patterns: {
    exclude: [
      '**/node_modules/**',      // node_modulesを除外
      '**/dist/**',              // ビルド出力を除外
      '**/target/**',            // Rust/Tauriのビルドを除外
      'scripts/node_modules/**', // ネストしたnode_modulesも除外
      '**/*.min.js',             // 圧縮ファイルを除外
    ]
  }
}

設定ファイルがない場合は、デフォルトの除外パターンが適用されます。

セッション管理

• POST /api/sessions - 新規セッションの作成
• GET /api/sessions/:id - セッション情報の取得

操作管理

• GET /api/operations/:id - 操作状態の確認
• POST /api/batch - バッチ操作の実行

WebSocket サポート

リアルタイム更新を受信：

const ws = client.connectWebSocket();

// 操作の進捗を監視
ws.subscribeToOperation(operationId);

ws.onMessage((data) => {
  if (data.type === 'operation-progress') {
    console.log(`Progress: ${data.progress}%`);
  }
});

予測システム

操作実行前に必要なリソースを予測：

const estimator = new Estimator();

const estimate = await estimator.estimate({
  type: 'index',
  params: { fileCount: 1000 }
});

console.log(`推定時間: ${estimate.time.typical}ms`);
console.log(`推定コスト: $${estimate.cost.total}`);
console.log(`信頼度: ${estimate.confidence * 100}%`);

トランザクション管理

複数の操作を安全に実行：

const stateManager = new StateManager();

// トランザクション開始
const transaction = await stateManager.beginTransaction();

try {
  // 操作を記録
  await stateManager.recordOperation(transaction.transactionId, {
    type: 'file.update',
    params: { path: 'config.js' }
  });
  
  // 成功時はコミット
  await stateManager.commit(transaction.transactionId);
} catch (error) {
  // エラー時はロールバック
  await stateManager.rollback(transaction.transactionId);
}

エラーハンドリング

すべてのエラーは構造化された形式で返されます：

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Query is required",
    "details": {
      "field": "query"
    }
  }
}

レート制限

APIには以下のレート制限があります：

• グローバル: 60リクエスト/分
• 検索: 30リクエスト/分
• インデックス: 10リクエスト/時間

環境変数

• AGENT_API_PORT - APIサーバーのポート (デフォルト: 3000)
• AGENT_API_HOST - APIサーバーのホスト (デフォルト: localhost)

開発

# テストの実行
npm test

# 開発モード（自動リロード）
npm run dev

ライセンス

MIT