Dify で『さくらのAI Engine』用カスタムツール(プラグイン)を作って呼び出してみた

さくらのAI Engine

先日リリースしました『さくらのAI Engine』ですが、想像を超えたフィードバックをいただき、早くも次の機能拡張を踏まえたアップデートの検討に向けた議論が活発に行われています。フィードバックをお寄せいただいた皆様、本当にありがとうございます。

こちらでハンズオン形式の記事を公開していますので、是非合わせてご覧ください。

さくらのAI Engine ことはじめ（1）：基本（チャット）機能とRAG、MCPによる自然言語検索

さくらのAI Engineことはじめ（2）：音声ファイルの文字起こし

Dify カスタムツール と プラグイン

AI Engineは、チャット、RAG、音声の文字起こしの3つがAPIとして提供されています。チャットAPIはOpenAPI互換ですが、細かい挙動の違いなどがあり、DifyのOpenAI用ブロックそのままでは利用できません。簡単にAI EngineをDifyから呼び出していただけるよう、カスタムツールを作りました。

一般的にはこのような外部モジュールはプラグインと呼ばれることが多いですが、Difyではカスタムツールが正式名称ですので、この記事では今後カスタムツールで統一します。

OpenAPI と Dify カスタムツール

OpenAPI は、API の仕様を標準化して書くための仕組みです。たとえば「このエンドポイントに GET リクエストを送るとこういうレスポンスが返ってきます」といった情報を、機械が読める形でまとめておけます。イメージとしては、API の取扱説明書を誰が見ても、そしてコンピュータが見ても理解できる形にしたものです。もともと Swagger という名前で知られていましたが、現在では OpenAPI Specification（OAS）という名称で世界的に使われています。開発者にとっては今や定番の技術であり、API を公開するならまず OpenAPI で仕様を記述しておく、という流れが一般的になっています。

OpenAPI の大きな利点は、仕様を一度書いてしまえば、それを活用してさまざまなことが自動化できる点にあります。たとえば、Swagger UI のようなツールを使えば、定義ファイルから見やすい API ドキュメントを自動で生成できます。これによって、わざわざ手作業で API リファレンスを整備する必要がなくなります。

こうした特徴から、OpenAPI は「API の設計図」と呼ばれます。

DifyカスタムツールはこのOpenAPIフォーマットをインポートすることで専用ブロック用テンプレートを作ることができます。

さっそくやってみる

このハンズオン手順ではDifyのアカウント開設が完了し、コンソールにアクセス出来ていることを想定しています。

1. カスタムツールの作成

Difyコンソール上部のツールをクリックします。

カスタム → カスタムツールを作成する をクリックします。

以下のOpenAPI準拠スキーマを貼り付けます。

openapi: 3.0.3
info:
  title: Sakura AI - Chat Completions (Dify Tool)
  version: 1.0.0
  description: >
    Sakura AI の Chat Completions エンドポイントを Dify の Custom Tool として呼び出します。
    返却 JSON の choices[0].message.content をワークフロー側で text にマップしてください。
servers:
  - url: https://api.ai.sakura.ad.jp
paths:
  /v1/chat/completions:
    post:
      summary: Create chat completion
      operationId: createChatCompletion
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
            examples:
              sample:
                value:
                  model: gpt-oss-120b
                  messages:
                    - role: system
                      content: "こんにちは！"
                  temperature: 0.7
                  max_tokens: 200
                  stream: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Set as: Bearer <Token>'
  schemas:
    Message:
      type: object
      required: [role, content]
      properties:
        role:
          type: string
          enum: [system, user, assistant]
        content:
          type: string
    ChatRequest:
      type: object
      required: [model, messages]
      properties:
        model:
          type: string
          example: gpt-oss-120b
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        temperature:
          type: number
          format: float
          default: 0.7
        max_tokens:
          type: integer
          default: 200
        stream:
          type: boolean
          default: false
    ChatResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                type: object
                properties:
                  role:
                    type: string
                  content:
                    type: string
                  refusal:
                    nullable: true
                  annotations:
                    nullable: true
                  audio:
                    nullable: true
                  function_call:
                    nullable: true
                  tool_calls:
                    type: array
                    items: {}
                  reasoning_content:
                    type: string
                    nullable: true
              logprobs:
                nullable: true
              finish_reason:
                type: string
                nullable: true
              stop_reason:
                nullable: true
        service_tier:
          nullable: true
        system_fingerprint:
          nullable: true
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer

自動で中身を読み取るツールにセットされています。

認証方法を設定します。<TOKEN>は皆さんの環境ごとに正しい値に置き換えてください。

保存をクリックするとカスタムツールが作成されます。

2. ワークフローの作成

2.1. カスタムツールブロックの設定

続いて先ほど作成したカスタムツールを呼び出すワークフローを作成します。

今度は画面上部からスタジオをクリックします。

最初から作成 → チャットフロー をクリックします。

適当な名前を付けて 作成する をクリックするとワークフローのひな型が起動します。

真ん中のLLMはOpenAI用ですので削除します。削除は選択して DEL キーで行えます。

先ほど作成したカスタムツールを挿入します。

あとでもう一つブロックを入れるので、回答ブロックを少し右に寄せておきます。

CREATECHATCOMPLETIONブロックを開いて設定画面から以下の値を入れます。

• model : gpt-oss-120b
• gpt-oss-120b：[ { "role": "user", "content": "{<変数:sys.query>}}" } ]

<変数:sys.query> の指定は少し注意が必要です。文字列で投入するのではなく、以下の様にシステムが自動で挿入する変数を指定します。

最初にブロックを開いたときに 変数を挿入する というリンクがありますので、それをクリックして選択します。

指定が完了したら右に向いている▷をクリックするとテスト実行がされます。

以下の様に何か出力が出ていれば成功です。

2.2. コード実行ブロックの設定

このカスタムツールブロックはAPIからの回答がJSONで出力されます。Difyの回答ブロックはtextを渡す必要があるので要素をより出す必要があります。

コードブロックを挿入して矢印でつなぎます。

コード実行ブロックを開いて入力変数の arg1 で json を指定します。

コードを JAVASCRIPT に変更して以下のスクリプトを貼り付けます。

// 関数テンプレート方式: 実行器が main(inputs_obj) を呼びます
function main(inputs_obj) {
  // arg1 に Tool の json を接続している前提
  const inData = inputs_obj?.arg1 ?? null;

  // ツールの json が配列の場合とオブジェクトの場合の両対応
  const data = Array.isArray(inData) ? inData[0] : inData;

  // 本文だけ取り出し（なければ空文字）
  const content = data?.choices?.[0]?.message?.content ?? "";

  // ★ 返り値オブジェクトのキー名 'result' は、出力変数名に合わせてください（String）
  return { result: String(content) };
}

2.3. 回答ブロックの設定

最後に、コードブロックがJSONから要素を抜き出したtextを受け取る様に設定します。

設定タブの応答からコードブロックの出力変数を指定できるようになっています。

2.4. テスト

ではプレビューからテストしてみましょう。

無事動作しました！

まとめ

本記事では『さくらのAI Engine』をDifyから呼び出す手順をまとめました。『さくらのAI Engine』には無料使用枠もありますので、是非使ってみて下さい。