エージェント

エージェントとは？

エージェントは、質問を受け取り、使用するツールを決定し、回答を生成するプログラムです。ReActループ（Reason + Act）を実行します：

ユーザーの質問
  -> LLMが考え + ツールを選択
    -> ツールを実行し、結果を返す
      -> LLMが再び考える（ツール結果を含めて）
        -> 最終回答（または別のツールを選択）

このループは、LLMが最終回答を生成するか、maxSteps（デフォルト：10）に達するまで続きます。

エージェントの作成

import { Schift, Agent, RAG } from "@schift-io/sdk";

const schift = new Schift({ apiKey: "sch_..." });
const rag = new RAG({ bucket: "my-docs" }, schift.transport);

const agent = new Agent({
  name: "My Agent",
  instructions: "You are a helpful assistant. Use the knowledge base.",
  rag,
  tools: [myCustomTool],
  model: "gpt-4o-mini",
  transport: schift.transport,
  maxSteps: 15,
});

const result = await agent.run("What is Schift?");
console.log(result.output);

LLM接続モード

エージェントは、LLMへの接続に3つの方法をサポートします：

1. Schift Cloud（デフォルト）

Schiftの/v1/chat/completionsエンドポイントを経由してルーティングします。OpenAI、Google、Anthropic間でモデルルーティングをサポートします。

const agent = new Agent({
  name: "Cloud Agent",
  instructions: "...",
  model: "gpt-4o-mini", // または "claude-sonnet-4-6"、"gemini-2.5-flash"
  transport: schift.transport,
});

2. 直接プロバイダー

OpenAI、Google、Anthropicのエンドポイントに直接接続します。LLM呼び出しはSchift Cloudをバイパスします（RAGは引き続きSchift Cloudを使用します）。

const agent = new Agent({
  name: "Direct Agent",
  instructions: "...",
  model: "gpt-4o-mini",
  baseUrl: "https://api.openai.com/v1",
  apiKey: process.env.OPENAI_API_KEY,
});

3. セルフホスト

Ollama、vLLM、LiteLLM、またはOpenAI互換エンドポイントに接続します。

const agent = new Agent({
  name: "Local Agent",
  instructions: "...",
  model: "llama3",
  baseUrl: "http://localhost:11434/v1",
});

詳細はセルフホスティングガイドを参照してください。

エージェント vs ワークフロー vs クライアント

	エージェント	ワークフロー	クライアント
使用する場合	対話型Q&A、ツール呼び出し	固定データパイプライン（ETL、バッチ）	単純な埋め込み/検索呼び出し
ループ	ReAct（動的、LLMが決定）	DAG（固定ステップ、決定論的）	なし
ツール	はい	ブロックタイプ	該当なし
メモリ	会話履歴	該当なし	該当なし

設定リファレンス

オプション	型	デフォルト	説明
name	string	必須	表示名
instructions	string	必須	LLM用のシステムプロンプト
model	ModelId | string	"gpt-4o-mini"	LLMモデル識別子
transport	Transport	—	Schift Cloudトランスポート（schift.transportから）
baseUrl	string	—	カスタムOpenAI互換エンドポイント
apiKey	string	—	直接/セルフホストモード用のAPIキー
tools	AgentTool[]	[]	エージェントが使用できるツール
rag	RAG	—	RAGインスタンス（ツールとして自動登録）
memory	MemoryConfig	—	会話メモリ設定。ステートレスにする場合は省略
maxSteps	number	10	最大ReActループ反復数
toolTimeoutMs	number	30000	各ツール実行のタイムアウト（ミリ秒）
maxToolCalls	number	maxSteps * 5	実行あたりの最大ツール呼び出し数
parallelToolExecution	boolean	false	1ターンあたり複数のツール呼び出しを並列実行する
skills	SkillsConfig	—	動的スキル読み込み。Skillsを参照
extensions	Array	—	拡張イニシャライザまたはモジュールパス
mcp	MCPServerConfig[]	—	MCPサーバー設定（将来互換性）

実行オプション

agent.run()に実行ごとのオプションを渡します：

const result = await agent.run("question", {
  requestId: "req_abc123",    // ログ全体でこの実行を追跡
  signal: AbortSignal.timeout(30000), // 30秒後にキャンセル
});

オプション	型	説明
requestId	string	ロギング/トレーシング用の相関ID
signal	AbortSignal	中止時に実行をキャンセル

イベント

エージェントは実行中にイベントを発行します。agent.on()で購読します：

agent.on("tool_call", (event) => {
  console.log(`Calling ${event.toolName}...`);
});

agent.on("agent_end", (event) => {
  console.log(`Done in ${event.totalDurationMs}ms`);
});

// ワイルドカード：すべてのイベントをリッスン
agent.on("*", (event) => {
  console.log(event.type, event);
});

イベント	発火タイミング
agent_start	実行が開始されたとき
turn_start	各ReAct反復が開始されたとき
tool_call	LLMがツール呼び出しを決定したとき
tool_result	ツール実行が完了したとき
message_delta	LLMが最終回答テキストを生成したとき
agent_end	実行が正常に完了したとき
error	エラーが発生したとき
policy_violation	スキルポリシーがツール呼び出しをブロックしたとき

返されたクリーンアップ関数で購読を解除します：

const unsub = agent.on("tool_call", handler);
unsub(); // リスニングを停止

完全なイベントペイロードはEvents referenceを参照してください。

実行結果

agent.run()はAgentRunResultを返します：

interface AgentRunResult {
  steps: AgentStep[];       // ReActループの各ステップ
  output: string;           // 最終回答テキスト
  totalDurationMs: number;  // 総実行時間
}

各ステップには、think、tool_call、tool_result、final_answer、またはerrorのタイプがあります。