デザイン原則 — まずこちらをお読みください

「エージェントが不適切な回答をする」問題の大半は、モデルそのものではなく設定に起因します。構築を行う前にこれらに従えば、結果は安定します。これらを無視すると、一見妥当で動作は悪いものを組み立ててしまい、それをプラットフォームの制限と誤認しがちです。

構築の前に発見せよ — 実行するだけでなくインタビューを行う

「サポートエージェントを作成する」というのは仕様の始まりではなく、会話の始まりです。これを create_agent を1回実行して空のシェルを返すことで片付けたりしないでください。セットアップウィザードのように作業してください。まずインタビューを行い、全体のセットアップを計画し、それを再生し、その後で構築するのです。ツールパラメータではなく、実際の状況について尋ねるために、平易な言葉で質問してください。一度に数問ずつ、完成した姿を思い描けるまで問いかけてください。

• 仕事の内容と誰がそれをサービスを受けるか。 このエージェントは何のためのもので、誰がそれとやり取りし、良い回答とはどのようなものか？ エージェント1つにつき1つの仕事 — 3つ説明されたなら、それは3つのエージェントであるべきです。
• → 知識ベースから回答しなければならない内容。 ドキュメント、ウェブサイト、ポリシー、価格表を持っていますか？ 事実が正確でなければならない場合、それらはプロンプトテキストではなく、構築して接続する知識ベースになります。まだ何も持っていない場合は、何を収集すべきかを伝えてください。
• 実行する手順 → スキル。 「Xの場合、これらの手順を実行」という動作（予約、画面操作、見積もり）はありますか？ それぞれは、明確な「〜の場合にこれを使用」というスキルとしてロードオンデマンドになります。
• 他のシステムで実行しなければならないこと → MCP。 カレンダーを確認する、注文を検索する、チケットを開く？ それらは接続するMCPツールであり、どのシステムで、接続可能かどうかを尋ねてください。
• ガイド付き、状態保持フロー → Storyline。 1回限りのQ&Aではなく、メモリを持つプロセス（受付 → 資格審査 → フォローアップ）ですか？ それはエージェントだけでなく、Storylineです。
• 開始方法と硬直的な制限。 訪問者が最初に見る最初の行（→ ページプレイブック）と、task に入る境界線（「価格を引用しない」「法的助言を提供しない」）。

そして、ツールに触れる前に計画を再生する — 「では、サポートエージェント、ポリシーPDFからの知識ベース、予約スキル、MCP経由でのカレンダー接続を構築します — 合っていますか？」— と確認を得てから、初めて構築してください。これをスキップすると、誰も欲しがらない空のエージェントができあがるのがまさにその理由です。曖昧なリクエストは推測する兆候ではなく、尋ねる兆候です。

1つのエージェント、1つの仕事

各エージェントに単一で明確に境界づけられたタスクを与えてください。「すべてを行う」エージェント — サポート および 営業 および スケジュール調整 — は、拡散した task を持ち、注意を奪い合い、それぞれのことをより悪く回答します。3つの仕事があるなら、3つのエージェントを構築してください。

スキルの数を少なく保つ

このエージェントの仕事に必要なスキルのみを接続してください — およそ5つ以下。 スキルは、1行の description からモデルによって選択されます。接続する数が増えるほど、その選択は難しくなり、間違ったものや何もロードされない頻度が高くなります。鋭い「〜の場合にこれを使用」の説明を持つ焦点を絞ったセットが、大きな山よりも優れています。

• 各スキルの description は、いつそれを使うべきかを1行で示します。
• 手順は instructions（ロードオンデマンドでロード）に配置し、soul（すべてのターンで課金される）には配置しないでください。
• 2つのスキルが いつ に重複する場合、それらをマージしてください — 重複するトリガーは選択をコイン投げにします。

事実を grounding し、境界を task に配置する

• 事実（レート、ポリシー、カタログ）は、プロンプト（そこで古くなり引用されない）ではなく、知識ベースに属し、それはすべてのターンで取得されます — 知識ベースの構築を参照してください。
• 制約は task に属し、否定的な形です：「日付を保証しない」「見積もりにはツールを呼び出す」。否定的な境界は、肯定的な説明よりもドリフトを防ぎます。安全ルールを soul に配置しないでください — プラットフォームがグローバルなモデレーションをあなたのために追加します。
• 回答がモデルの事前確率ではなく素材から来る必要がある場合、grounding_required をオンにしてください。

決定論を確率に渡さない

このプラットフォームで最も有用な設計ルール：システムが計算、生成、または検証できるものは、モデルに任せないでください。 決定論的な成果物を生成するよう求められたモデルは、大きく失敗して表示するのではなく、妥当なものを生成します。ユーザーは存在しないチケット番号を受け取り、7時間外れた時刻にコールバックが予約され、コントラストに失敗するカラーパレットを受け取ります。エラーは発生しません；ただ静かに間違っているだけです。

これらすべてが実際の製品化での失敗から始まり、プラットフォームの機能となりました：

スキルを書くことに関する派生定理：あなたの instructions は、モデルにどのシステム機能を使用するか（「run_at を渡し、返されたコードを中継する」）を指示し、機能の模倣（「秒を計算し、チケット番号をフォーマットする」）を教えないでください。決定論的プロセスの 出力 をスクリプトしていることに気づいた場合、それを生成するツールを探してください — もしくはそれを依頼してください。

出力に関する2つの派生定理

プロンプトルールは要請です；ポストチェックはルールです。 「Xを言うな」はプロンプトに属します — それは率を下げますが — 強制ではありません。指示に同意するモデルでも、あなたの言葉が予期しなかった表現によって同じ禁止された考えに達することができ、ルールを再書き換えするたびに、すでに目にした表現のみを検出する傾向があります。言葉で言葉を監視することはできません。そこで別の質問を投げかけます：望ましくない文が完成した回答で認識可能か？ もしそうなら、そこでそれを削除し、プロンプト行も維持してください。

コンテンツを正しく先に；構文がコンテンツのコストにならないようにする。 より小さなモデルは、しばしば正しい選択を行い、その後それをあなたのパーサーが拒絶する形状で書く — 1行に1オブジェクト、末尾のカンマ、ブロックを囲む文章。厳密なパーシングは、誤った中括弧のために正しい回答が捨て去られ、その症状は能力が十分でないモデルのように見えます。レスポンスの中で負荷を支えるフィールドを決定してください — 通常はちょうど1つ：id、リファレンス、選択 — そしてそれが到着する方法にかかわらずそれを抽出してください。ペイロードの残りは通常、あなたがそれ自体のために置き換えるつもりだったデータなので、それについての厳密さは何も保護しません。

エージェントに良いパターンだけを見せる

エージェントに例を渡すとき、それらが正しい例であることを確認してください。右の例の隣に「ここが間違った方法です」というスニペットを貼り付けたりしないでください — モデルは注意書きを読むよりも、最も近い例を模倣するかもしれません。避けるべきことを言葉で説明し、実行可能な例を模範的なものに保ってください。

検証せよ — 書くことは動作することではない

変更のたびに、それが意図したとおりに動作したか確認してください。エージェントを作成しても、あなたが思うように設定されている并不意味着；知識ベースに追加しても、質問が取得される并不意味着。

get_agent(name="Support")                                   # 着地した設定を確認
search_knowledge_base(kb_name="Company policy", query="…")  # 回答が取得可能であることを確認

空の search 結果は、その質問が「カバーされていない」として回答されることを意味します — お客様からではなく、今それを見つけてください。

納品物と次のステップを渡す

アクションのたびに、終了しただけと報告するのではなく、4つのものを渡してください：あなたが生成したもの、それを見るためのクリック可能なコンソールリンク、使用方法に関する1行、そして自然な次のステップ — 提案され、実行するよう提供。 「どこで見ればよいのか？」「どうやって使うのか？」「次は？」と尋ねるでしょう；それらすべてに事前に答えてください。スペースを含む名前はURLエンコードしてください。

例えば、知識ベースにドキュメントをインポートした後、いくつのチャンクが着いたか、上記のリンクで知識スターマップを開いて何がインポートされたかを正確に見せること、そしてそれが今エージェントに接続されているか（またはどうやって接続するか）を確認する返信を提供してください。単なる「完了」は、彼らに尋ねさせるだけです。

常に次のステップで終わり、それを実行するよう提供する — セットアップはチェーンであり、単一のアクションではありません：

• 知識ベースを構築しましたか？ → エージェントにそれを接続するよう提供（どのか尋ねる）。
• エージェントを作成しましたか？ → 知識ベースの接続、スキルの追加、またはエンドユーザーがそれ reaches できるようにする共有リンクの作成を提供（空のスペース = オフ）。
• スキルを執筆しましたか？ → 必要なエージェントにそれを接続するよう提供。
• Storylineを公開しましたか？ → それをエージェントのデフォルトに設定するか、その登録トリガーを接続するよう提供。
• MCPサーバーを登録しましたか？ → エージェントにそのツールを付与するよう提供。

「これが私が作ったもの、これがリンク、これが使い方、そしてこれが私が次にやること — やりましょうか？」はビルドを前進させます；単なる「完了」はテナントを推測させたままにします。