この記事でやること
- ClaudeのチャットからGraphを回させる前に、デスクトップ側で決めておくことを整理する
- 「エージェントから呼ばれる前提」のGraphの作り方で、気をつける点をまとめる
- 一覧に出ない、queuedのまま動かない、といったときに見る場所を順に並べる
前提・環境
- osFoundryのデスクトップアプリを使っている。Graphの実行はデスクトップでしかできない
- Claudeのカスタムコネクタに
https://api.osfoundry.io/api/v1/external-mcpを追加済みで、osFoundry側で接続を承認している - 使うツールは
list_graph_sessions、run_graph_session、get_graph_run、cancel_graph_runの4つ。Claude Codeではmcp__osfoundry__run_graph_sessionのような名前になる - 記事中のプロジェクト名、Graph名、値は表示例
共有の単位を押さえる
共有は「プロジェクト × Graphセッション」の組み合わせで決まります。Graphにはプロジェクトの項目がなく、端末に保存されているだけなので、どのプロジェクトに見せるかを1つずつ選ぶ作りです。
| 決めること | 場所 | ポイント |
|---|---|---|
| Claudeが入るプロジェクト | 鍵アイコン → Connected → 接続を選択 → Projects | Add to project で追加。Claudeはここ以外のGraphを探さない |
| 見せるGraphセッション | 同じタブの Share desktop Graph sessions | プロジェクトごとにチェック。チェックしたものだけが一覧に出る |
| 共有のオン・オフ | 同じ欄の Share selected Graphs / Stop sharing | チェックが0件だとオンにできない |
表示例:Claudeの接続のProjects欄
Share desktop Graph sessions の欄は、デスクトップアプリでしか表示されません。ブラウザ版で探しても見つからないので注意です。
チェックする前に確認すること
- そのGraphは、誰も見ていない状態で最後まで走るか
- 「毎回確認」にしているツールを途中で使っていないか
- 引数なしで呼ばれても、おかしなことをしないか
- 2回実行されたら困る副作用(メール送信、ファイル書き込みなど)がないか
1つ目と2つ目はつながっています。Claude経由の実行中は確認に答える人がいないので、「毎回確認」のツールは確認を出さずに拒否されます。そのツールが必須のGraphなら、途中で止まって失敗として返ってきます。確認なしで動くツールは普通に使えます。
4つ目は idempotency_key で守られています。run_graph_session ではこのキーが必須(8〜128文字)で、応答が失われてClaudeが同じキーで送り直しても、実行は1回にまとまる前提です。
エージェントに呼ばせるGraphの作り方
説明欄に入力を書く
list_graph_sessions が返すのは名前、説明、slug、バージョン、状態だけです。Graphのスクリプトも引数のスキーマもClaudeには見えません。Claudeが arguments を正しく埋められるかは、説明欄の書き方しだいです。
週次KPIをまとめて、前週比の大きい変化を3つ返す。
引数: {"week": "2026-W45"} ISO週。省略すると直近の完了週。
最後は要約を返す
結果はJSONにして10万文字までで、超えると中身が付かず result_truncated: true だけが返ります。日本語なら10万文字は約300KBで、上限に収まってもモデルに読ませるには多すぎます。Claudeから呼ばれるGraphは、最後のステップで要約を作って返す形にしておくと扱いやすくなります。全体はデスクトップの実行履歴に execution_id で残ります。
並列はGraphの中でやる
デスクトップは受け取った実行を1つずつ順番に処理します。Claudeに同じGraphを5本同時に投げさせても、5本目は前の4本が終わるまで始まりません。並列にしたい処理は、Graphの中で並列にします。
頼み方
Graphの名前、プロジェクト名、引数をはっきり書きます。待ち方も一言添えておくと、ツール呼び出しが無駄に増えません。
osFoundryのLaunch planプロジェクトで「週次KPIダイジェスト」を week=2026-W45 で回して。
結果は20秒くらい待ってから、10秒おきに確認すればいい。
デスクトップは20秒おきにキューを見に来るので、起動直後に何度確認してもqueuedが返るだけです。
うまくいかないときに見るところ
上から順に見ると早いです。
1. list_graph_sessions が空
- Claudeの接続が、そのプロジェクトに追加されているか
- Share desktop Graph sessions で、そのプロジェクトの下にGraphがチェックされているか
- そのプロジェクトのボタンが Stop sharing になっているか(=共有がオンか)
- デスクトップアプリが開いていて、サインインしているか。一覧はデスクトップが送ったものなので、一度も同期していなければ空です
2. ずっとqueuedのまま
- デスクトップアプリが閉じていないか、スリープしていないか
- 別の実行が走っていないか。順番待ちの可能性があります
キューはサーバー側にあるので、デスクトップを開き直せば続きから処理されます。
3. 「Graph session is no longer shared with this project」で取り消された
実行が始まる直前に、デスクトップが共有をもう一度確かめています。キューに載っている間にチェックを外したか、Stop sharing を押したか、デスクトップからそのセッションがなくなった場合にこうなります。
4. result_truncated: true が返ってきた
結果が10万文字を超えています。中身はデスクトップの実行履歴で見られます。次からはGraphの最後で要約するようにします。
5. 「Graph run not found or access removed」
get_graph_run と cancel_graph_run が扱えるのは、その接続が自分で始めた実行だけです。別の接続から聞いても、存在しないIDと同じ返事になります。
よくある疑問
実行中のGraphを止められますか
cancel_graph_run で止められます。queuedならそのまま取り消され、実行は始まりません。実行中なら取り消し要求が立ち、デスクトップが3秒おきに確認して止めます。
実行中の途中経過はClaudeに見えますか
見えるのは状態(queued、実行中、完了など)と、終わったときの結果です。途中のエージェントの出力が流れてくるわけではありません。細かい経過はデスクトップのGraph画面で追えます。
Claude側の許可とosFoundry側の許可は別物ですか
別物です。run_graph_session は書き込み扱い(destructiveHint: true)なので、Claudeが呼ぶ前に許可を求めます。osFoundry側では、どのGraphをどのプロジェクトに見せるかを共有の設定で決め、実行中のツールの確認設定はデスクトップの設定がそのまま効きます。
まとめ
- 共有はプロジェクトごと、Graphセッションごと。チェックしたものしかClaudeには見えない
- 誰も見ていない前提で走るGraphにする。「毎回確認」のツールは実行中は拒否される
- 説明欄に引数を書き、最後は要約を返す。並列はGraphの中で
- 困ったら、プロジェクトへの追加、チェック、デスクトップの起動、順番待ちの順に見る
接続の一覧がどこにあるかはConnectedのページに、複数のエージェントに作業を分ける考え方はMaestroのオーケストレーションのページにあります。
