Sisu フレームワーク

完全な透明性と制御性を備えた信頼性の高い AI エージェントを TypeScript で構築します。

このスキルを使う場合

• 新しい AI エージェントまたはエージェントパイプラインの作成
• LLM モデルによるツール呼び出しの実装
• 制御フロー、エラーハンドリング、またはトレース用のミドルウェアの設定
• 複数の LLM プロバイダー(OpenAI、Anthropic、Ollama)の操作
• トレースビューアを使用したエージェント動作のデバッグ
• RAG(Retrieval Augmented Generation)システムの構築

ディスカバリーファーストルール

新しい Sisu ミドルウェア、ツール、アダプタ、または RAG プリミティブを作成する前に:

1. まず保守されているパッケージサーフェスを確認します
2. カスタムフレームワークコードよりも既存のパッケージの構成を優先します
3. 既存の保守されているパッケージが本当に要件を満たさない場合のみ、新しいミドルウェア/ツールを提案します

sisu CLI が使用可能な場合は、まずそれを使用してください:

sisu list middleware
sisu list tools
sisu list adapters
sisu list vector
sisu info mw-rag
sisu info tool-rag

sisu がインストールされていない場合は、npx の同等物を使用してください:

npx @sisu-ai/cli list middleware
npx @sisu-ai/cli list tools
npx @sisu-ai/cli info mw-rag

CLI が利用できない場合は、以下をご確認ください:

• node_modules/@sisu-ai/* にインストールされているパッケージの README
• npm/GitHub の公式パッケージドキュメント
• エージェント向けドキュメント: http://sisuai.me/agents.html
• https://github.com/finger-gun/sisu/tree/main/examples の公開例

保守されている Sisu パッケージが既に存在する場合、アドホックな rag(...)、カスタムベクトル抽象化、またはカスタムツールレジストリを作成しないでください。

クイックスタート

インストール

pnpm add @sisu-ai/core @sisu-ai/adapter-openai \
         @sisu-ai/mw-register-tools \
         @sisu-ai/mw-conversation-buffer @sisu-ai/mw-trace-viewer \
         @sisu-ai/mw-error-boundary zod dotenv

基本的なエージェントテンプレート

import "dotenv/config";
import { Agent, createCtx, execute, type Tool } from "@sisu-ai/core";
import { registerTools } from "@sisu-ai/mw-register-tools";
import { inputToMessage, conversationBuffer } from "@sisu-ai/mw-conversation-buffer";
import { errorBoundary } from "@sisu-ai/mw-error-boundary";
import { openAIAdapter } from "@sisu-ai/adapter-openai";
import { traceViewer } from "@sisu-ai/mw-trace-viewer";
import { z } from "zod";

// Create context
const ctx = createCtx({
  model: openAIAdapter({ model: "gpt-5.4" }),
  input: "User input here",
  systemPrompt: "You are a helpful assistant.",
});

// Build pipeline
const app = new Agent()
  .use(errorBoundary())
  .use(traceViewer())
  .use(registerTools([...]))  // Add tools here
  .use(inputToMessage)
  .use(conversationBuffer({ window: 8 }))
  .use(execute);

// Run
await app.handler()(ctx);

コア概念

コンテキスト (Ctx)

すべてのデータが単一の型付きコンテキストオブジェクトを通じて流れます。隠された状態を作成しないでください。

主なプロパティ:

• input - ユーザー入力文字列
• messages - 会話履歴
• model - LLM アダプタ
• tools - ツールレジストリ
• memory - キーバリューストレージ
• state - ミドルウェア状態
• signal - キャンセル用の AbortSignal
• log - ロガー

ミドルウェアパターン

ミドルウェアシグネチャ: (ctx, next) => Promise<void>

重要なルール:

• 短絡する場合を除き、常に await next() を呼び出します
• 無関係なコンテキストプロパティを変更しないでください
• ctx.signal をすべての非同期操作に伝播させます

const myMiddleware = async (ctx, next) => {
  // 前処理
  ctx.log.info("Starting");

  await next(); // MUST call this

  // 後処理
  ctx.log.info("Finished");
};

Zod 検証を使用したツール

import { z } from "zod";
import type { Tool } from "@sisu-ai/core";

const myTool: Tool<{ city: string }> = {
  name: "toolName",
  description: "Clear description for the LLM",
  schema: z.object({
    city: z.string().min(1),
  }),
  handler: async ({ city }, ctx) => {
    // ctx is sandboxed - has memory, signal, log, model, deps
    // Cannot access: tools, messages, state, input, stream
    return { result: "data" };
  },
};

一般的なパターン

シンプルなチャットエージェント

const app = new Agent()
  .use(errorBoundary())
  .use(traceViewer())
  .use(inputToMessage)
  .use(conversationBuffer({ window: 8 }))
  .use(async (ctx) => {
    const res = await ctx.model.generate(ctx.messages, {
      toolChoice: "none",
      signal: ctx.signal,
    });
    if (res?.message) ctx.messages.push(res.message);
  });

ツール呼び出しエージェント

const app = new Agent()
  .use(errorBoundary())
  .use(traceViewer())
  .use(registerTools([tool1, tool2]))
  .use(inputToMessage)
  .use(conversationBuffer({ window: 8 }))
  .use(execute);

制御フロー付きエージェント

分岐、ループ、並列実行については CONTROL_FLOW.md をご参照ください。

RAG エージェント

取得拡張生成パターンについては RAG.md をご参照ください。

LLM アダプタ

OpenAI

import { openAIAdapter } from "@sisu-ai/adapter-openai";

// Standard OpenAI
const model = openAIAdapter({ model: "gpt-5.4" });

// Compatible APIs (LM Studio, vLLM, OpenRouter)
const model = openAIAdapter({
  model: "gpt-5.4",
  baseUrl: "http://localhost:1234/v1",
});

Anthropic

import { anthropicAdapter } from "@sisu-ai/adapter-anthropic";
const model = anthropicAdapter({ model: "claude-sonnet-4" });

Ollama (ローカル)

import { ollamaAdapter } from "@sisu-ai/adapter-ollama";
const model = ollamaAdapter({ model: "llama3.1" });

必須ミドルウェア

制御フロー

import { sequence, branch, switchCase, loopUntil } from '@sisu-ai/mw-control-flow';

// Sequential steps
.use(sequence([step1, step2, step3]))

// Conditional branching
.use(branch(
  ctx => /weather/.test(ctx.input ?? ''),
  toolPipeline,
  chatPipeline
))

// Route by intent
.use(switchCase(
  ctx => ctx.state.intent,
  { 'search': searchFlow, 'chat': chatFlow }
))

セーフティと検証

import { guardrails } from '@sisu-ai/mw-guardrails';
import { invariants } from '@sisu-ai/mw-invariants';

.use(errorBoundary())  // Always first
.use(guardrails({
  maxTokens: 2000,
  timeout: 30000
}))
.use(invariants())  // Development mode validation

可観測性

import { traceViewer } from '@sisu-ai/mw-trace-viewer';
import { usageTracker } from '@sisu-ai/mw-usage-tracker';

.use(traceViewer())   // Generates HTML traces
.use(usageTracker())  // Tracks costs

エラーハンドリング

import {
  isSisuError,
  getErrorDetails,
  ToolExecutionError,
  ValidationError,
} from "@sisu-ai/core";

try {
  await app.handler()(ctx);
} catch (err) {
  if (isSisuError(err)) {
    console.error("Code:", err.code);
    console.error("Context:", err.context);
  } else {
    console.error(getErrorDetails(err));
  }
}

errorBoundary ミドルウェアを使用します:

.use(errorBoundary(async (err, ctx) => {
  ctx.log.error('Error:', getErrorDetails(err));
  ctx.messages.push({
    role: 'assistant',
    content: 'I encountered an error.'
  });
}))

環境変数

# Required for examples
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Optional
LOG_LEVEL=info           # debug|info|warn|error
TRACE_HTML=1            # Generate HTML traces
TRACE_STYLE=dark        # light|dark

ベストプラクティス

1. 常に errorBoundary を使用 します(最初のミドルウェアとして)
2. 開発時に traceViewer を有効にします(2 番目のミドルウェアとして)
3. Zod スキーマでツール入力を検証 します
4. conversationBuffer を使用 してコンテキストオーバーフローを防ぎます
5. ctx.signal をすべての非同期操作に伝播 させます
6. ミドルウェアは小さく保ちます - 1 つの責任ずつ
7. 複雑な条件分岐の代わりに制御フロー結合子を使用 します
8. シークレットをログに出力しないでください - createRedactingLogger を使用します
9. 本番環境ではガードレールを設定 します(maxTokens、timeout)
10. キャンセルのために AbortSignal でテスト します

よくある間違い

❌ next() を呼び出さない

// WRONG
const bad = async (ctx, next) => {
  ctx.state.value = 1;
  // Missing await next()!
};

❌ signal を伝播させない

// WRONG
const res = await ctx.model.generate(ctx.messages, {});

// CORRECT
const res = await ctx.model.generate(ctx.messages, {
  signal: ctx.signal,
});

❌ 他のミドルウェア状態を変更する

// WRONG - don't touch other middleware state
ctx.state.otherMiddlewareData = modified;

// CORRECT - namespace your state
ctx.state.myFeature = { myData: value };

❌ console.log を使用する

// WRONG
console.log("debug info");

// CORRECT
ctx.log.info("debug info");

リファレンスドキュメント

詳細なドキュメントについては、以下をご覧ください:

• CONTROL_FLOW.md - 分岐、ループ、並列、グラフ
• RAG.md - 取得拡張生成
• TOOLS.md - 組み込みツール(web、cloud、dev)
• STREAMING.md - トークンストリーミングパターン
• SISU_SKILLS.md - ファイルシステムベースのスキルサポート
• EXAMPLES.md - リポジトリからの 25+ の動作例

外部リソース

• メインリポジトリ: github.com/finger-gun/sisu
• コアドキュメント: packages/core
• 例: examples/
• ミドルウェアリスト: packages/middleware
• ツールリスト: packages/tools