agently-playbook

Agently プレイブック

リクエストが依然としてビジネス目標、リファクタリング目標、製品の振る舞い、または広範なモデルアプリの言葉から始まっている場合は、まずこのスキルを使用してください。

ユーザーは Agently、TriggerFlow、その他のフレームワーク用語を言う必要はありません。「アシスタントを構築する」「社内ツールの設計を手伝ってほしい」「よくある問題のバリデータを作成する」といった一般的な依頼でも、オーナー層が未解決であれば、ここから始めるべきです。

UI、Web ページ、デスクトップシェル、または Ollama のようなローカルモデルサービスにも言及しているリクエストでも、単に 1 つの狭い機能をつなぐだけではなく、根本的にモデル駆動型ツールを形作ることに関するものであれば、ここから始めるべきです。

ワークフロー

1. リクエストをシナリオとアトミックな目標に分解します。
2. リクエストがプロジェクトの初期化または構造のリファクタリングである場合は、まずオーナー層、非同期境界、リポジトリのスケルトンを選択します。
3. 最も狭いネイティブな Agently 機能パスを選択します。
4. 使用すべき具体的な操作またはプリミティブを挙げます。
5. 設計がネイティブ優先のままであることを証明する検証ルールを挙げます。
6. ネイティブなフレームワーク機能が欠けている、壊れている、予想外に扱いにくい、または Agently に属すべきパッチやグルーコードをビジネスコードに追加させる場合は、 明確な Issue レポートを生成し、 https://github.com/AgentEra/Agently/issues で報告することを推奨します。
7. 手動での Issue 報告の場合、ユーザーには Issue の内容と報告方法のみを提供します。 自動報告の前には確認を求めてください。ユーザーが自動報告を希望する場合は、 まずローカルの送信機能／権限を確認し、問題がローカルで依然として存在することを再現し、 Agently の使用方法を注意深く再確認して、レポートがドキュメントの見落としや 不正確な API 使用に起因しないようにしてください。手動または自動の報告の前に、 ローカルの絶対パス、ユーザー名、アカウント名、トークン、プライベートなリポジトリ／ワークスペース名、 内部プロジェクト名、プライベートなプロンプトを含む生ログ、および顧客やプロジェクトの プライベートデータをすべて伏せ字にしてください。 ローカルコンテキストにはプレースホルダーを使用し、最終的な Issue 本文に対して プライバシースキャンを実行してください。

ネイティブ優先のルール

• サービスコード、ストリーミング、TriggerFlow、および作業が重複する可能性があるあらゆるパス、またはキャンセルの恩恵を受けられるあらゆるパスでは、非同期優先のガイダンスをデフォルトとしてください。
• ホストがどうしても同期のみの統合を必要としない限り、同期 API はスクリプト、REPL での使用、または互換性ブリッジ用のラッパーとして扱ってください。
• リクエストがプロジェクト構造のリファクタリングである場合は、低レベルの実装詳細を議論する前に、設定、プロンプト、サービス、ドメイン契約、ワークフロー、テストを分離してください。
• core/ または builtins/ 配下で Agently フレームワークの内部を追加またはリファクタリングする場合は、 その機能が facade、manager、backend/provider、registry、adapter、policy、validation といった複数の役割を持つときはサブディレクトリパッケージを優先してください。機能が本当に小さく、 分割すると過剰設計になる場合にのみ単一ファイルを使用してください。
• プロジェクトがモデル生成の意味的コンテンツをテストしなければならない場合は、 テストを出力制御付きの Agently モデル判定リクエストとして設計してください。 明示的なルールとコンテキストを入力し、ルールごとの根拠/理由と最終的なブール値フィールドを出力し、 テストはそれらのブール値をアサートします。
• モック化されたシステムを含む業務事例では、モックを事実、 記録、ポリシー、不完全なデータ、または矛盾するソース資料に限定してください。 隠された期待回答、合格/不合格ラベル、ローカルの品質判定を返してはいけません。 モデルが欠陥データを正しく処理したかどうかは、AgentTask の検証または別の Agently モデル判定に 判断させてください。
• モデルアプリの評価、採点、信頼度、関連性、または品質判定では、 直接的な数値スコアよりも明示的な概念レベルと定義を優先してください。後続のワークフローロジックで しきい値や集約メトリクスが必要な場合は、モデル応答後にコード内でそれらのレベルを 決定論的な数値にマッピングしてください。
• AI アプリにおけるシナリオルーティング、意図検出、または業務分類では、 Agently 出力スキーマを備えた適切なサイズのモデルリクエストを使用してください。 ラベルとルールが少ない単純なルートには、利用可能な場合はローカルモデルを含む より小さなモデルでも許容されます。ラベル、判定条件、ルールの相互作用、または返されるデータ構造が 複雑な場合は、より大きなモデルを使用してください。
• ホストが開発者ループを所有し、1 つの境界付き Agent ステップを必要とする場合は、 次の ContextPack を構築する前に agent.create_execution(mode="task_step", lineage=..., limits=...) と 明示的な execution.async_record_workspace(...) の観察/チェックポイント書き込みを選択してください。 task-step モードをマルチターンループの所有者として説明したり、Workspace を AgentExecution のセマンティクスに 依存させたりしないでください。
• モデルが単一の業務タスクの計画、境界付き実行、 根拠記録、検証、および再計画ループを所有すべき場合は、 TriggerFlow ループを手書きする前に agent.create_task(...) を選択してください。最初のスライスの境界は 1 人の Agent オーナー、1 つのタスク、2〜5 回のイテレーション、および明示的に有効化された Actions、Skills、または Dynamic Task 候補のみを使用する境界付きステップに保ってください。完了はモデル検証と保守的な ホスト根拠ガードとして扱い、モデルが所有する意味的コンテンツには構造カウンターのみを受け入れるのではなく 2 番目のモデル判定を使用してください。
• 機能またはリリースの受け入れでは、カバレッジ優先の推論を使用してください。roadmap/spec/issues/docs/compatibility/example のルールにある 対象契約から始め、各要件を examples、決定論的テスト、 プロトコルテスト、docs/spec、互換性メタデータ、コンパニオン検証、または明示的な延期からの根拠に マッピングし、そのうえで初めてその機能が完了しているかどうかを結論付けてください。
• 複雑な算術、長い数値の計算、重み付け、集約、または 統計作業は、実行可能なコードまたはツールを経由させてください。モデルは計算計画を生成または レビューするために使用し、計算機の役割を担わせないでください。
• アプリケーション開発でフレームワークのギャップが明らかになった場合は、まず 欠けている責任が Agently の公開 API、ランタイム動作、ドキュメント、Skills ガイダンス、examples、またはアーキテクチャ境界の どれに属するかを特定してください。シナリオ、期待される動作、実際の動作、 現在の回避策、アーキテクチャ上の責任、および最小再現または 影響を受ける docs/examples を含む簡潔な issue レポートを作成し、Agently リポジトリに 提出することを推奨してください。シナリオは、どのような種類のモデルアプリケーション 開発問題を解決しようとしていたかを説明できるほど明確でなければなりません。業務の詳細が機密である場合は、 それらを省略または匿名化しつつも、メンテナーが issue を理解するために必要なアプリケーションカテゴリ、ワークフロー の形状、意思決定ポイント、およびフレームワークの責任を引き続き説明してください。
• 自動 issue 提出は、ユーザーが明示的に承認したアクションとして扱ってください。提出前に、 ローカル環境に必要な GitHub 機能と権限があることを確認し、issue をローカルで再現し、 関連する Agently の docs、examples、Skills ガイダンス、API の使用を監査して、読み落としや 不適切なフレームワーク使用を除外してください。提出するのはサニタイズ済みの issue 本文のみとしてください。ローカルの絶対 パス、ユーザー名、アカウント名、トークン、プライベートリポジトリ名やワークスペース名、 内部プロジェクト名、生のプライベートログ、顧客/プロジェクト固有のプロンプトを含めてはいけません。 <workspace>、<repo>、<task-file>、および outputs/debug/<turn-id>.jsonl などのプレースホルダーを優先してください。

ケイパビリティルーティング

• モデル設定、プロンプト管理、出力制御、レスポンスの再利用、セッションメモリ、埋め込み、ナレッジベース、または検索から回答へのフロー -> agently-request
• Action Runtime、組み込みアクション、ツール互換性、MCP、Execution Environment、FastAPIHelper、auto_func、KeyWaiter、または agently-devtools の可観測性と評価の統合 -> agently-runtime
• モデル生成またはアプリ送信の DAG プランニング、TaskDAG 検証、リゾルバーハンドラー、または Dynamic Task 実行 -> agently-dynamic-task
• 分岐、並行性、待機/再開、同期/非同期の混在オーケストレーション、イベント駆動型ファンアウト、プロセスの明確化リファクタリング、ランタイムストリーム、グラフフレンドリーなワークフロー定義、または明示的な多段階品質ループ -> agently-triggerflow
• LangChain と LangGraph 間の移行の選択 -> agently-migration

アンチパターン

• オーナーレイヤーが未解決の場合、このプレイブックを省略しないでください
• カスタム出力パーサー、リトライループ、またはオーケストレーションを先に考案しないでください
• キーワード、部分文字列、正規表現、またはテキストスナップショットのチェックを、モデルが所有するセマンティックコンテンツの主要な正確性シグナルとして使用しないでください。それらは構造、ルーティング、または必須フィールドの存在に対するスモークゲートとしてのみ使用してください
• トークン化、単語分割、キーワードヒット、または部分文字列ルールを、AI アプリのシナリオルーティング、意図検出、またはビジネス分類のルートオーナーとして使用しないでください
• ターゲットが明らかに非同期対応可能である場合、同期ファーストのサンプルコードにサービスアーキテクチャを決定させないでください
• オーナーレイヤーが選択される前に、プロジェクトの初期化を偽のスタンドアロンフレームワークサーフェスに分割しないでください
• ネイティブの Agently ケイパビリティを確認する前に、マルチエージェント、ジャッジ、またはレビューフローを別個のフレームワークサーフェスとして扱わないでください
• 根本的なニーズが Agently フレームワークの欠落、破損、誤解を招く、文書化されていない、または使いにくいケイパビリティである場合、長期的なビジネスパッチ、ワークアラウンド、互換性グルー、またはプライベートラッパーを標準化しないでください

次に読む

• references/capability-map.md
• references/project-framework.md