エージェント設計
エージェント設計（プロンプト・テンプレート）
エージェントの 名前・コード・説明 に加え、プロンプト と テンプレート をどう設計するかのガイドです。名前と説明は、エージェント一覧の意味検索や MCP 横断利用時の エージェント特定 にも使われます。画面項目の上限などは「エージェント一覧」（No.3.1）を参照してください。
各項目の役割
| 項目 |
役割 |
いつ効くか |
| エージェント名 |
ユーザー向けの表示名 |
エージェント一覧カード、チャットアプリ、チャット履歴、おすすめ一覧 |
| エージェントコード |
システム上の一意 ID |
URL（/knowledge/{code} 等）、MCP の agent_code 引数 |
| 説明 |
専門分野・用途の要約 |
意味検索（エージェント一覧）、MCP でのエージェント選択、おすすめカード |
| プロンプト |
回答の振る舞い・文体・方針 |
毎回のチャット回答 の土台 |
| テンプレート |
新規ナレッジの初期 Markdown |
ナレッジ一覧の「新規」 を押したときだけ |
| ナレッジ本文 |
回答の根拠となる知識 |
質問内容に応じて検索・参照 |
プロンプトはナレッジの代わりになりません。 詳細な知識はナレッジに書き、プロンプトは「誰として・どう答えるか」の枠組みに留めるのが基本です。
なぜ名前・説明が AI のエージェント特定に重要か
iknow.dev では、人間だけでなく AI（LLM）もエージェントを選ぶ 場面があります。名前・説明・コードは、その判断材料になります。
| 場面 |
名前・説明・コードの使われ方 |
| エージェント一覧の検索 |
名前と説明がベクトル化され、入力キーワードに意味的に近いマイエージェントだけが残る |
| おすすめエージェント |
パブリックエージェントの検索・カード表示に 説明文 が出る |
MCP 横断利用（/mcp） |
Cursor / Claude などの LLM が get-reference name=agents で 名前・説明・タグ を読み、どのエージェントに agent_code を付けるか判断する |
| N:N チャットの招待 |
招待候補はパブリックエージェントの 名前 で選ぶ |
MCP 利用時、サーバーはエージェントを自動選択しません。LLM が一覧の description や top_tags を読んで選ぶため、説明に専門分野・対象ユーザー・得意な質問例 を書いておくと、意図したエージェントにたどり着きやすくなります。
エージェント名・コード・説明の書き方
エージェント名
| ポイント |
例 |
| 何の専門家か一目で分かる |
「iknow ナビゲーター」「安栗堂 龍一（労働法）」 |
| 短く覚えやすい |
カード・チャットヘッダーに常時表示される |
| プロンプトの役割と矛盾しない |
名前が「料理」なのにプロンプトが法律専門、は避ける |
エージェントコード
| ポイント |
例 |
半角英数字・_・- のみ（6〜24 文字） |
iknow-navigator、labor-law |
| 変更可能だが URL も変わる |
ブックマーク・Teams 連携・MCP 設定に影響するので慎重に |
| 意味のある短い識別子 |
MCP で agent_code として LLM が指定する |
説明
| ポイント |
例 |
| 専門分野を最初に |
「労働基準法に詳しいパラリーガル。就業規則・残業・解雇の相談向け。」 |
| 誰向けか書く |
「iknow.dev の使い方を案内する公式ナビゲーター。初めての方向け。」 |
| 500 文字以内に要約 |
詳細はナレッジへ。説明は索引として使う |
| 検索されそうな語を含める |
ユーザーがエージェント一覧の検索欄に入れそうなキーワード（Laravel、労働法、など） |
上限
| 項目 |
上限 |
| エージェント名 |
255 文字 |
| エージェントコード |
6〜24 文字（a-zA-Z0-9_- のみ） |
| 説明 |
500 文字 |
プロンプトの書き方
含めるとよい要素
| 要素 |
例 |
| 役割 |
「あなたは iknow.dev の案内役です」 |
| 口調・文体 |
「です・ます調、専門用語は初出で補足」 |
| 回答の方針 |
「ナレッジにない内容は推測せず、その旨を伝える」 |
| 参照の促し |
「回答の根拠ナレッジがあれば案内する」 |
| やってはいけないこと |
「個人情報を要求しない、ナレッジ外の断定をしない」 |
プロンプト例（案内系エージェント）
あなたは iknow.dev のナビゲーターです。
- ユーザーの質問意図を確認し、ナレッジに基づいて正確に答えてください。
- ナレッジに記載がない場合は「ナレッジに該当情報がありません」と伝え、推測で補完しないでください。
- 操作手順は番号付きリストで、URL や画面名を具体的に示してください。
- 丁寧なです・ます調で、初心者にも分かる言葉を選んでください。
プロンプト例（専門領域エージェント）
あなたは ○○ 分野に詳しい専門家アシスタントです。
- 回答は必ずエージェントに登録されたナレッジを根拠にしてください。
- 法令・規格・数値を引用するときは、ナレッジの記載を優先し、出典ナレッジを示してください。
- 判断が分かれる論点は、ナレッジの記述と、記載が不足している点を分けて説明してください。
- 表や箇条書きを活用し、長文より構造化された回答を心がけてください。
上限
テンプレートの書き方
テンプレートは 新規ナレッジの初期本文 です。エージェント内で統一したフォーマットを使うと、執筆・レビューが楽になります。
テンプレート例
# （タイトルをここに）
## 概要
（このナレッジで説明することを 2〜3 文で）
## 詳細
（本文）
テンプレート設計のコツ
| コツ |
理由 |
| 見出しの骨組みだけ用意 |
執筆者が迷わない。本文は自由に書ける |
| 関連ページはリンク機能で設定 |
本文末尾の「## 関連ナレッジ」セクションは不要。エディターの「関連ナレッジ」ボタンまたは MCP の link_to で設定 |
| 表形式データ用は JSON テンプレートも検討 |
数値・一覧系ナレッジ用に別テンプレートを用意 |
上限
| 項目 |
上限 |
| テンプレート |
65,535 文字 かつ 80,000 トークン（既定。保存時に検証） |
公開設定との関係
| 設定 |
プロンプト・ナレッジへの影響 |
| パブリック |
誰でも閲覧可。未ログインでもチャット閲覧可（送信はログイン必要） |
| プライベート |
オーナー・メンバーのみ。社内限定のナレッジ向け |
パブリックエージェントでは、プロンプトとナレッジの内容が外部に公開される前提で書いてください。
エージェント作成後の推奨ステップ
- 名前・コード・説明を設定 — このページのガイドに沿って書く（特に説明は検索・MCP 選定に効く）
- プロンプトとテンプレートを設定 — 回答の振る舞いと新規ナレッジの型を決める
- ナレッジを 1〜数件作成 — 「ナレッジの書き方と設計」を参照
- 既存資料をインポート — 「ナレッジ一覧とインポート」
- チャットで試す — 想定外の回答があればナレッジまたはプロンプトを修正（効かないときは No.5.9）
- 外部連携 — 必要なら MCP や Teams（各連携ガイド参照）
既存エージェントからコピー
新規作成画面の「既存エージェントからコピー」で、説明 / プロンプト / プライベート設定 / テンプレート を流用できます。コード・名前・オーナー・メンバーは引き継がれません。