langgraph-agent-design
api/app/services/agents/ 配下でLangGraphエージェント(親/子グラフ・ノード・State)を新規作成/変更する際に必ず使う。スパゲティ化を防ぐための設計8原則のチェックリスト。
SKILL.md.claude/skills/langgraph-agent-design/SKILL.md
GitHubLangGraph エージェント設計チェックリスト(api/app/services/agents/)
エージェント実装はスパゲティ化しやすい。着手前・実装後にこのチェックリストで 自己点検する。詳細な根拠は CLAUDE.md「LangGraph / LLM エージェント設計方針」 節を参照(本スキルはそれを実装時に使える形にしたもの)。
8原則チェックリスト
- 1エージェント = 1モジュール = 1グラフ になっているか。
各子エージェントは自分の
build_graph()で完結させ、run()はgraph.ainvoke(new_state(...), config)を呼ぶだけの薄いラッパにする (company.py・ market.py が実例)。 共有BaseAgentは作らない(エージェントごとにノード構成が異なるため)。 - 親と子の責務が分離されているか。親(orchestrator.py)
は「意図判定 → 委任」だけを行い、実処理は子グラフに閉じ込める。親の
ノードから子グラフを呼ぶときは必ず
ainvoke(state, config)で呼び、config(Langfuseコールバック付き)をそのまま渡す(子runが親runに ネストするため)。 - ノードが小さく単一責務になっているか。1ノード1目的、名前で役割が
分かるようにする(
resolve/collect/analyze/reportの 4ノード構成が company.py / market.py の型)。分岐ロジックはノード内に 埋め込まずroute_*のような条件関数に切り出す(orchestrator.pyの_routeが実例)。 - State が
state.pyの1箇所で定義されているか。新しいフィールドが 要る場合はAgentState(reducer付きTypedDict)にフィールドを足す形で 拡張し、他のTypedDictをネストしない(langgraphの型解決が壊れるため)。 エージェント固有の「事実情報」型(CompanyFacts/MarketFacts等)は state.py に定義してよいが、AgentState 本体へのネストはしない。 - LLMアクセスが
runtime.pyのinvoke_llm経由か。直接LLMクライアント を呼ばない。失敗時は必ずfallback文字列(ルールベースのrule_based_analysis等)を渡し、オフライン/テストでも動くようにする。 - 副作用(DB・ネットワーク)がノードの外か、明示した収集ノード
(
_collect系)に限定されているか。純粋な整形・判定ロジック (build_report/_facts_to_prompt等)はテスト可能な純粋関数として 切り出す(会話生成部分にDB呼び出しを混ぜない)。 - RunnableConfig(Langfuseコールバック付き)がトップで1度組み立てられ、 親→子へそのまま伝播しているか。子グラフ呼び出しのたびに新しい configを作り直さない。
- 応答がJob非同期+ポーリングになっているか。長時間処理は
services/jobsのジョブとして実行し、進捗はAgentStep(phase)で 表現する(API層の責務。エージェント自体はこれを意識せず、進捗が要る 場合は呼び出し元がジョブのprogressを更新する形にする)。
新規エージェント追加時の型(company.py / market.py が雛形)
resolve/select(対象確定)→ collect(収集・副作用はここに限定)
→ analyze(LLM分析・invoke_llm使用)→ report(整形・純粋関数)
- 収集ソースが複数ある場合は
asyncio.gatherで並列取得する (_collect_oneの実例を参照)。 - 外部呼び出しの失敗方針は
backend-workflowスキルのリトライ/キャッシュ 節に従う(「失敗=機能縮退」系はリトライしない、TTLキャッシュはasync_ttl_cache)。 - 新エージェントを親(orchestrator)から呼び出す場合は、意図判定
(
classify_intent_llm)とルーティング(_route)の追加が必要になる。 親のノード自体を太らせず、委任ロジックのみ追加する。
完了時
backend-workflowスキルの検証コマンド(uv run pytest -q/uv run ruff check app/ tests//uv run mypy app/)を通す。- 一区切りついたら
git-workflowスキルに従い commit + push する。