エージェントガイド

概要

このガイドでは、ドキュメントバケットとカスタムツールから質問に答えるエージェントを作成する手順を説明します。最終的に、ドキュメントを検索し、ツールを呼び出し、観察可能なイベントを発行する動作するTypeScriptエージェントが完成します。

前提条件

Node.js 18以降
SchiftワークスペースAPIキー（sch_...）
ワークスペース用に設定されたAPIオリジン
Schift CLIのインストール（バケットの作成とデータ投入にのみ必要）

注：まだバケットを作成して検索を確認していない場合は、まずクイックスタートに従ってください。エージェントを追加する前に取得パスを確認すると、デバッグがはるかに容易になります。

ステップ1：SDKのインストール

npm install @schift-io/sdk

ステップ2：ナレッジバケットの準備

バケットを作成し、少なくとも1つのドキュメントをアップロードします：

export SCHIFT_API_KEY=sch_...
export SCHIFT_API_URL=https://api.example.com/v1

schift db create support-docs
schift upload ./handbook.pdf --bucket support-docs
schift search "How do I reset my password?" --bucket support-docs --top-k 5

検索が関連するチャンクを返すことを確認してください。確認できたら、同じバケットをエージェントに接続できます。

ステップ3：エージェントの作成

agent.tsという名前のファイルを作成します：

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

const schift = new Schift({
  apiKey: process.env.SCHIFT_API_KEY,
});

const rag = new RAG({ bucket: "support-docs" }, schift.transport);

const agent = new Agent({
  name: "Support Bot",
  instructions:
    "You are a support assistant. Answer questions using the knowledge base. " +
    "If the answer is not in the documents, say so clearly.",
  rag,
  model: "gpt-4o-mini",
  transport: schift.transport,
  maxSteps: 10,
});

RAGインスタンスは、rag_searchという名前のツールとして自動登録されるため、エージェントは質問が必要に応じてバケットを検索できます。

ステップ4：エージェントの実行

const result = await agent.run("How do I reset my password?");

console.log(result.output);
console.log(`Completed in ${result.totalDurationMs}ms`);
console.log(`Steps: ${result.steps.length}`);

result.stepsの各ステップには、think、tool_call、tool_result、またはfinal_answerなどのタイプがあります。ステップを調べることは、エージェントが特定の回答を生成した理由を理解する最も速い方法です。

ステップ5：カスタムツールの追加

エージェントは、独自のAPIを呼び出せるようになるとより有用になります。天気ツールを追加します：

import type { AgentTool } from "@schift-io/sdk";

const getWeather: AgentTool = {
  name: "get_weather",
  description: "Get the current weather for a city",
  parameters: {
    type: "object",
    properties: {
      city: {
        type: "string",
        description: "City name, for example Seoul",
      },
    },
    required: ["city"],
  },
  handler: async (args) => {
    const city = String(args.city);
    const temperature = await fetchWeatherAPI(city); // 独自の実装
    return { success: true, data: { city, temperature } };
  },
};

const agent = new Agent({
  name: "Support Bot",
  instructions: "Answer support questions and report weather when asked.",
  rag,
  tools: [getWeather],
  transport: schift.transport,
});

ツール名は、エージェント内で一意であり、snake_caseを使用し、/^[a-zA-Z_][a-zA-Z0-9_]*$/に一致する必要があります。

ステップ6：イベントの観察

イベントを購読して、進行状況を表示または実行をログに記録します：

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

agent.on("tool_result", (event) => {
  console.log(`Tool result:`, event.result);
});

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

const result = await agent.run("What is the weather in Seoul?");

返されたクリーンアップ関数は、リスナーが不要になったときに削除します：

const unsub = agent.on("tool_call", handler);
unsub();

ステップ7：エラーの処理

エージェントレベルの障害を処理するために、実行をtry/catchでラップします：

import { AgentError, MaxStepsError } from "@schift-io/sdk";

try {
  const result = await agent.run("A very complex question");
  console.log(result.output);
} catch (err) {
  if (err instanceof MaxStepsError) {
    console.log("The agent used too many steps. Try a simpler question or increase maxSteps.");
  } else if (err instanceof AgentError) {
    console.log(`Agent error: ${err.message}`);
  }
}

エージェントがmaxStepsに達した場合、agent.run()は正常に返り、最後のステップのタイプはerrorになります。ループがどこで終了したかを確認するには、result.stepsを確認してください。

次のステップ

現在の情報が必要な質問にはWeb Searchを追加します。
ReActループと設定オプションの詳細については、エージェントの概念を読みます。
エージェントができることを拡張するには、ToolsとSkillsを確認します。
本番環境向けのパターンについては、エラー処理を確認します。