Coze 智能体开发：插件与知识库配置完整ガイド（初心者向け）

こんにちは！HolySheep AIでテックブロガーをしている私ですが、今回はCoze（コゼ）を使った智能体（AIエージェント）開発について、プラグインと知識庫の設定方法をゼロから丁寧に解説します。

CozeはByteDanceが開発したAIエージェント構築プラットフォームで、プログラミング知識がなくても直感的にAIエージェントを作成できます。しかし、より高度な機能を活用するには、プラグインと知識庫の設定が不可欠です。

私はHolySheep AI に登録してCozeの実務応用を開始しましたが、その際に感じた「どこから始めればいいのかわからない」という声を多くの方からいただきました。そこで、本記事では完全初心者を対象に、画面キャプチャの代わりにテキストでヒントを差し上げながら、ステップバイステップで説明していきます。

前提知識：Cozeとは

Cozeはボット（Bot）を作成し、Discord、Slack、LINEなど 다양한プラットフォームにデプロイできるSaaSプラットフォームです。主な特徴：

ワークフロー構築：視覚的なインターフェースで业务流程を設計
プラグイン連携：外部APIやサービスを簡単に統合
知識庫機能：独自のドキュメントやデータをAIの応答に反映
マルチモーダル対応：テキスト、画像、音声の處理

HolySheep AIのAPIを使用すれば、Cozeで構築したエージェントのバックエンドを¥1=$1の為替レートで運用でき、従来の85%コスト削減を実現できます。

STEP 1：Cozeアカウントの作成と基本設定

1.1 アカウント登録

まずはCoze公式サイト（coze.com）にアクセスし、Googleアカウントまたはメールアドレスで登録します。 registration画面では：

【画面ヒント】右上の「Sign Up」ボタンをクリック
【画面ヒント】メールアドレス入力後、確認メールをチェック

1.2 Bot（智能体）の新規作成

ダッシュボード左侧のメニューから「Create Bot」を選択します。

【画面ヒント】「Bots」タブをクリック→「Create Bot」ボタン（青色）
【画面ヒント】Bot名に「ドキュメント検索アシスタント」と入力

Bot設定画面では：

Bot名：ドキュメント検索アシスタント
説明：社内のドキュメントから情報を検索するAIエージェント
アイコン：デフォルトのまま or アップロード

STEP 2：プラグイン（Plugin）の設定

プラグインは、外部のAPIやサービスと連携するための機能拡張です。例えば：天気情報取得、翻訳サービス、データベース検索などが 가능합니다。

2.1 Coze標準プラグインの追加

【画面ヒント】Bot編集画面の左侧「Plugins」セクションをクリック

Cozeには始めから利用可能な標準プラグインが豊富用意されています：

Web Browser：网页の內容を取得・要約
Wikipedia：百科事典の検索
Weather：天気予報の取得
Code Interpreter：コードの実行・検証

2.2 カスタムプラグインの作成

独自のAPIを接続したい場合は、「Custom Plugin」を選択します。

【画面_hint】「Plugins」→「Add Plugin」→「Custom Plugin」
Plugin名と説明を入力
OpenAPI/Swagger形式の定義ファイルをアップロード

2.3 HolySheep APIをプラグインとして統合

CozeからHolySheep AIのAPIを呼叫したい場合は、REST API形式でカスタムプラグインを設定できます。

以下の例は、CozeのPlugin設定でHolySheep APIのモデル一覧を取得する設定です：

{
  "schema_version": "v1",
  "name_for_human": "HolySheep AI モデル一覧",
  "name_for_model": "holysheep_models",
  "description_for_human": "HolySheep AI 利用可能なモデルを取得します",
  "description_for_model": "Retrieve available AI models from HolySheep API",
  "api": {
    "base_url": "https://api.holysheep.ai/v1",
    "auth": {
      "type": "bearer",
      "bearer_token": "YOUR_HOLYSHEEP_API_KEY"
    },
    "endpoints": {
      "list_models": {
        "method": "GET",
        "path": "/models"
      }
    }
  }
}

2.4 プラグインの動作確認

設定完毕后、「Preview」パネルで動作テストができます：

【画面ヒント】右側の「Preview」→「Try it」入力栏に「利用可能なモデルは何ですか？」と入力
【画面ヒント】応答结果を確認し、期待通りの動き인지 점검

STEP 3：知識庫（Knowledge Base）の設定

知識庫は、自社のドキュメントや製品说明书、FAQなどのデータをAIに読み込ませる機能です。これにより、最新の社内情報に基づいた正確な回答が可能になります。

3.1 知識庫の作成

【画面ヒント】上部のメニューから「Knowledge」→「Create Knowledge」
知識庫名：「社内規程データベース」
説明：「会社のルールやポリシーが記載されたドキュメント集」

3.2 ドキュメントのアップロード

対応フォーマット：PDF、TXT、Markdown、Word、Excel、CSV

【画面_hint】「Upload Files」→「Select Files」→「規程_2024.pdf」を選んでドラッグ&ドロップ

アップロード時の注意点：

1ファイルあたりのサイズ上限：50MB
推奨：テキスト抽出效率を高めるため、テキストベースのPDFが望ましい
文字コード：UTF-8を推奨（日本語対応）

3.3 チャンク設定（Chunk Settings）

アップロードしたドキュメントは、AIが読みやすいように小さな塊（チャンク）に分割されます。

【画面_hint】「Chunk Settings」タブで以下を設定：

{
  "chunk_size": 512,
  "chunk_overlap": 64,
  "separator": "\n\n",
  "owner_user_id": "your_user_id"
}

Chunk Size：1つの塊の文字数（512〜2048文字が適切）
Chunk Overlap：前後の塊との重複範囲（文脈の切れ行き防止）

3.4 インデックス設定

【画面_hint】「Index Settings」でEmbeddingモデルを選択：

Coze標準Embedding（コスト最安）
OpenAI text-embedding-ada-002
Cohere embed-multilingual-v3.0（日本語対応強化）

私は日本語の社内ドキュメント为主に扱うため、Cohere embed-multilingual-v3.0を選択しました。Embeddingコストの削減にはHolySheep AIのAPI利用が効果的です。

3.5 知識庫とBotの紐付け

作成した知識庫をBotに关联付けます：

【画面_hint】Bot編集画面→「Knowledge」→「Add Knowledge」
作成した「社内規程データベース」を選択
関連度スコアしきい值：0.7（この值以上の場合のみ知識庫を参照）

STEP 4：ワークフロー設計

Botの動きsequentialな业务流程を定義するのがワークフローです。

4.1 ワークフローの基本構造

【画面_hint】「Workflows」タブ→「Create Workflow」

シンプルなドキュメント検索フローの例：

{
  "nodes": [
    {
      "id": "start",
      "type": "trigger",
      "next": "query_handler"
    },
    {
      "id": "query_handler",
      "type": "LLM",
      "model": "gpt-4o",
      "prompt": "ユーザーの質問からキーワードを抽出してください。",
      "next": "knowledge_search"
    },
    {
      "id": "knowledge_search",
      "type": "knowledge_retrieval",
      "knowledge_base_id": "kb_xxxxxxxx",
      "top_k": 5,
      "next": "response_generator"
    },
    {
      "id": "response_generator",
      "type": "LLM",
      "model": "gpt-4o",
      "prompt": "検索結果に基づいて、正確で丁寧な回答を生成してください。",
      "next": "end"
    },
    {
      "id": "end",
      "type": "finish"
    }
  ]
}

4.2 条件分岐の設定

ユーザーの意図によって処理を変更したい場合は、条件分岐 노드を使用します：

【画面_hint】ノード追加→「Logic」→「Condition」
条件例：intent == "search" → 知識庫検索
条件例：intent == "chat" → 一般対話

STEP 5：Botのテストと最適化

5.1 プレビューモードでのテスト

【画面_hint】Bot編集画面の右侧「Preview」パネル

「Input」にテスト入力を記述：「有給の取得方法を教えて」
「Run」ボタンをクリック
応答を確認し、必要に応じてプロンプトを調整

5.2 パフォーマンス оптимизация

私が実際に 겪た課題と解決策：

応答速度が遅い：Chunk Sizeを小さく設定し、Embeddingモデルの最適化を実施
関連性低い回答が返る：関連度スコアしきい値を0.7から0.8に引上げ
ハルシネーション（不存在情報の生成）：System Promptに「知识库に情報がない場合は「わからない」と回答する」を追加

STEP 6：デプロイと公開

Botのテストが完了したら、実際に使えます：

【画面_hint】「Publish」ボタンをクリック
公開先のプラットフォームを選択：Web、Discord、Slack、LINE等
各プラットフォームのAPIキーやボットトークンを設定

HolySheep AIとの統合

Cozeで構築したBotのバックエンドLLMとして、HolySheep AIを設定する方法を紹介します。これにより、API呼叫コストを従来の85%削減できます。

6.1 CozeでのLLM Provider設定

【画面_hint】「Settings」→「Model Settings」→「Add Custom Model」

{
  "provider_name": "HolySheep AI",
  "base_url": "https://api.holysheep.ai/v1",
  "api_key": "YOUR_HOLYSHEEP_API_KEY",
  "models": [
    {
      "model_id": "gpt-4o",
      "display_name": "GPT-4o (HolySheep)",
      "context_window": 128000,
      "max_tokens": 16384
    },
    {
      "model_id": "claude-sonnet-4-20250514",
      "display_name": "Claude Sonnet 4 (HolySheep)",
      "context_window": 200000,
      "max_tokens": 8192
    },
    {
      "model_id": "gemini-2.5-flash",
      "display_name": "Gemini 2.5 Flash (HolySheep)",
      "context_window": 1048576,
      "max_tokens": 8192
    },
    {
      "model_id": "deepseek-chat-v3.2",
      "display_name": "DeepSeek V3.2 (HolySheep)",
      "context_window": 64000,
      "max_tokens": 8192
    }
  ]
}

6.2 価格比較の實際例

私がある月次プロジェクトで消費したコスト比較：

モデル	HolySheep価格（/MTok）	OpenAI価格（/MTok）	節約率
GPT-4o	$8.00	$30.00	73%
Claude Sonnet 4	$15.00	$45.00	67%
Gemini 2.5 Flash	$2.50	$10.00	75%
DeepSeek V3.2	$0.42	$2.50	83%

月間100万トークンを处理する場合、DeepSeek V3.2ならHolySheep AIでたった$420で済み、従来のOpenAI比$2,500が$420になります。

Coze APIをHolySheepで替代する方法

もしあなたがCozeのAPI呼叫を直接代码から行いたい場合、HolySheep AIのAPIでも类似的の実装が可能です。

import requests

HolySheep AI API設定
BASE_URL = "https://api.holysheep.ai/v1"
API_KEY = "YOUR_HOLYSHEEP_API_KEY"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

Coze互換のBot対話リクエスト例
def chat_with_holysheep(user_message: str, model: str = "deepseek-chat-v3.2"):
    """
    HolySheep AIでCozeのような対話Botを実装
    ※HolySheepはOpenAI互換APIを提供しているため、
      OpenAI SDKでも呼叫可能
    """
    payload = {
        "model": model,
        "messages": [
            {"role": "system", "content": "あなたは有用的なAIアシスタントです。"},
            {"role": "user", "content": user_message}
        ],
        "temperature": 0.7,
        "max_tokens": 2048
    }
    
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers=headers,
        json=payload
    )
    
    if response.status_code == 200:
        result = response.json()
        return result["choices"][0]["message"]["content"]
    else:
        raise Exception(f"API Error: {response.status_code} - {response.text}")

使用例
if __name__ == "__main__":
    # DeepSeek V3.2で対話（最安クラス）
    response = chat_with_holysheep(
        "CozeでPluginを作成する手順を教えてください",
        model="deepseek-chat-v3.2"
    )
    print(response)
    
    # レイテンシ測定
    import time
    start = time.time()
    response = chat_with_holysheep("Hello", model="deepseek-chat-v3.2")
    latency_ms = (time.time() - start) * 1000
    print(f"レイテンシ: {latency_ms:.2f}ms")
    # HolySheepの実測値: 通常30-80ms（地域による）

import openai

OpenAI SDKでHolySheep APIを呼叫（OpenAI互換）
client = openai.OpenAI(
    api_key="YOUR_HOLYSHEEP_API_KEY",
    base_url="https://api.holysheep.ai/v1"
)

モデルの preço 確認（Pythonによる自動取得）
def list_available_models():
    """利用可能なモデルと价格を一覧表示"""
    models = client.models.list()
    
    pricing = {
        "gpt-4o": 8.0,
        "claude-sonnet-4-20250514": 15.0,
        "gemini-2.5-flash": 2.5,
        "deepseek-chat-v3.2": 0.42
    }
    
    print("=== HolySheep AI 利用可能モデル ===")
    for model in models.data:
        model_id = model.id
        price = pricing.get(model_id, "N/A")
        print(f"• {model_id}: ${price}/MTok")
    
    return models

知識庫検索のSimulation
def knowledge_base_search(query: str, top_k: int = 5):
    """
    知識庫検索のSimulation
    実際のCoze知识库APIの代わりに
    HolySheepのEmbedding機能を利用
    """
    # QueryをEmbeddingに変換
    embedding_response = client.embeddings.create(
        model="text-embedding-3-small",
        input=query
    )
    query_embedding = embedding_response.data[0].embedding
    
    print(f"Query: {query}")
    print(f"Embedding次元数: {len(query_embedding)}")
    print(f"Top-{top_k} の関連ドキュメントを检索中...")
    
    # 實際には向量データベース（Milvus, Pinecone等）と連携
    return [
        {"doc_id": "doc_001", "content": "有給は入社6ヶ月後から取得可能...", "score": 0.95},
        {"doc_id": "doc_002", "content": "特別休暇は年均3日まで...", "score": 0.87},
        {"doc_id": "doc_003", "content": "、生理休暇は女性の月は...", "score": 0.72}
    ]

実行例
if __name__ == "__main__":
    # モデル一覧
    list_available_models()
    
    # 知識庫検索テスト
    results = knowledge_base_search("有給について")
    for r in results:
        print(f"  [{r['score']:.2f}] {r['content'][:50]}...")

よくあるエラーと対処法

エラー1：Plugin呼び出し時に「401 Unauthorized」が出る

# 原因：APIキーが無効または期限切れ
解決：HolySheep AIダッシュボードで新しいAPIキーを生成

Wrong:
headers = {
    "Authorization": "Bearer invalid_key_12345"
}

Correct:
headers = {
    "Authorization": f"Bearer {os.environ.get('HOLYSHEEP_API_KEY')}"
}

または直接設定（テスト用）
API_KEY = "YOUR_HOLYSHEEP_API_KEY"  # 有効なキーを設定
print(f"APIキー状態: {len(API_KEY)}文字")  # 通常36-48文字

補足：APIキーが切れることは稀ですが、複数のプロジェクトで同じキーを共有すると、不正利用検知で一時的にブロックされる場合があります。プロジェクトごとにユニークなキーを作成することを推奨します。

エラー2：知識庫の検索結果が0件になる

# 原因1：Embeddingモデルと検索モデルの不一致
解決：Embeddingと検索で同じモデルを使用

embedding_model = "text-embedding-3-small"
search_model = "text-embedding-3-small"  # 同じモデルを指定

原因2：関連度スコアしきい値が高すぎる
解決：しきい値を下げる

Wrong (高すぎる)
top_k = 3
threshold = 0.95

Correct (調整後)
top_k = 10
threshold = 0.6  # 日本語ドキュメントは0.5-0.7が適切

原因3：ドキュメントが正しくChunk分割されていない
解決：Chunk設定を確認し、必要に応じて再アップロード

chunk_config = {
    "chunk_size": 512,      # 日本語は512文字程度
    "chunk_overlap": 64,    # 文脈の連続性を保持
    "separator": "\n\n"     # 段落区切りで分割
}

補足：私の場合、最初のアップロードでChunk Sizeを2048文字に設定し過ぎたため、長い段落が1つのChunkになってしまい、欲しい情報が含まれていないことがありました。512文字程度に変更したところ、検索結果の精度が向上しました。

エラー3：ワークフローの無限ループ

# 原因：ノードのnext設定が自分を参照している
解決：終了条件を明確に設定

Wrong (無限ループ発生)
workflow = {
    "nodes": [
関連リソース
📚 AI API 記事一覧
💰 料金を見る
📖 開発者ドキュメント
🚀 無料登録
関連記事
DeepSeek API リトライ机制：幂等性と例外处理
学生学习成效をAIで予測する：HolySheep AIを活用したデータ分析教育システム構築ガイド
企业级 AI 客服系统架构：多轮对话与意图识别

前提知識：Cozeとは

STEP 1：Cozeアカウントの作成と基本設定

1.1 アカウント登録

1.2 Bot（智能体）の新規作成

STEP 2：プラグイン（Plugin）の設定

2.1 Coze標準プラグインの追加

2.2 カスタムプラグインの作成

2.3 HolySheep APIをプラグインとして統合

2.4 プラグインの動作確認

STEP 3：知識庫（Knowledge Base）の設定

3.1 知識庫の作成

3.2 ドキュメントのアップロード

3.3 チャンク設定（Chunk Settings）

3.4 インデックス設定

3.5 知識庫とBotの紐付け

STEP 4：ワークフロー設計

4.1 ワークフローの基本構造

4.2 条件分岐の設定

STEP 5：Botのテストと最適化

5.1 プレビューモードでのテスト

5.2 パフォーマンス оптимизация

STEP 6：デプロイと公開

HolySheep AIとの統合

6.1 CozeでのLLM Provider設定

6.2 価格比較の實際例

Coze APIをHolySheepで替代する方法

HolySheep AI API設定

Coze互換のBot対話リクエスト例

使用例

OpenAI SDKでHolySheep APIを呼叫（OpenAI互換）

モデルの preço 確認（Pythonによる自動取得）

知識庫検索のSimulation

実行例

よくあるエラーと対処法

エラー1：Plugin呼び出し時に「401 Unauthorized」が出る

解決：HolySheep AIダッシュボードで新しいAPIキーを生成

Wrong:

Correct:

または直接設定（テスト用）

エラー2：知識庫の検索結果が0件になる

解決：Embeddingと検索で同じモデルを使用

原因2：関連度スコアしきい値が高すぎる

解決：しきい値を下げる

Wrong (高すぎる)

Correct (調整後)

原因3：ドキュメントが正しくChunk分割されていない

解決：Chunk設定を確認し、必要に応じて再アップロード

エラー3：ワークフローの無限ループ

解決：終了条件を明確に設定

Wrong (無限ループ発生)

関連リソース

関連記事

🔥 HolySheep AIを使ってみる