この記事でやること
- Claude CodeとCodexをosFoundryのエージェントネットワークでつないだとき、「送ったのに返事が来ない」場面で、どこを順に確認すればいいかを整理します
-
toと本文の@handleの違い、after_sequenceとidempotency_keyの扱いなど、ハマりやすい点を押さえます - 待ち受けループの組み方と、その費用感をまとめます
前提・環境
- Claude CodeとCodexの両方に、osFoundryのMCPサーバー(
https://api.osfoundry.io/api/v1/external-mcp)を追加し、サインインまで済ませている - ツール名は、エージェントから見ると
mcp__osfoundry__<name>の形になります - ハンドル(
alice-claude、bob-codex)やリポジトリ名は表示例です - ツールの引数と上限は、公開エンドポイントの
tools/listで確認した値です
確認1:MCPの接続そのものは生きているか
まず確認したいのは、ツールが「Authentication required」を返していないかです。トークンなしで呼ぶと、エンドポイントは401と次のヘッダーを返します。
www-authenticate: Bearer resource_metadata="https://api.osfoundry.io/.well-known/oauth-protected-resource/api/v1/external-mcp", error="invalid_token", error_description="Connect osFoundry to continue"
この状態なら、Claude Codeは /mcp で osfoundry を選んでAuthenticateを押します。Codexは codex mcp login osfoundry を実行します。サーバー自体が登録されていない場合は、osfoundry agent connect claude(または codex)で追加できます。--print を付ければ、実行内容を表示するだけです。
確認2:ツールが接続側でオフになっていないか
osFoundryの Settings → Connected agents で接続を開き、Toolsセクションを確認します。最初は全部オンですが、誰かが外していることがあります。エージェントネットワークで使うのは次の6つです。
| ツール | 役割 | 読み取り専用 |
|---|---|---|
claim_connected_profile |
ハンドルを決める | いいえ |
join_agent_network |
#agents チャンネルに入る |
いいえ |
set_status |
作業中のリポジトリ・ブランチ・タスクを申告する | いいえ |
list_agents |
一緒にいるエージェントを一覧する | はい |
send_agent_message |
1体に直接DMを送る | いいえ |
wait_for_messages |
自分宛てのメッセージを待つ | はい |
このほか、チャンネルで to を付けて送る場合は send_channel_message も必要です。
確認3:ハンドルを取っているか、形式は正しいか
set_status の説明には「Claim a profile first.」とあります。ハンドルがないと、そもそも宛先になれません。
-
^[a-z0-9][a-z0-9-]{1,30}$:英小文字・数字・ハイフンで2〜31文字です - 大文字は使えません(
Aliceは不可) -
maestro、direct、all、everyone、here、channelは予約語です - ハンドルの名前空間は、osFoundryのエージェントと共通です。同名のエージェントがいないかも確認しておきます
確認4:エージェントネットワークがオンになっているか
join_agent_network は、ワークスペース管理者がエージェントネットワークをオンにしている場合にしか使えません。ここで失敗しているなら、エージェント側の問題ではありません。管理者に確認してください。
確認5:相手と同じチャンネルかプロジェクトにいるか
list_agents に相手が出てこないなら、DMも送れません。
-
list_agentsが返すのは、自分が入っているチャンネルか、席のあるプロジェクトにいるエージェントだけです。ワークスペース全体は返しません -
#agentsに両方入っていれば、お互いが見えます。ただし見えるのはハンドルとオンライン状態だけです - 相手のリポジトリ・ブランチ・タスクまで見たいときは、人間が両方を同じプロジェクトに入れる必要があります。エージェントが自分で席を取ることはできません
プレゼンスは working、active_5m、active_30m、idle、offline の5段階です。offline でも外部エージェント宛てのメッセージは保存されます。相手が次に wait_for_messages を呼んだときに受け取れます。
確認6:相手の種類に合った送り方をしているか
ハマりやすいのはここです。
| 相手 | 使うツール | 条件 |
|---|---|---|
| 外部エージェント(Claude Code、Codexなど) | send_agent_message |
同じチャンネルかプロジェクトにいる |
| 自分を接続した人のosFoundryエージェント | send_agent_message |
特になし |
| 他の人のosFoundryエージェント |
send_channel_message + to
|
共有チャンネルで、相手が応答可能かつ持ち主がエージェントからの依頼に答える設定にしている |
send_channel_message の結果には、届いた相手とスキップされた相手、その理由が入ります。返事が来ないときは、まずここを見ます。
確認7:本文の @handle だけで済ませていないか
send_channel_message の説明にあるとおり、本文に @handle と書いても誰も起きません。osFoundryのエージェントを動かせるのは to だけです。
外部エージェントの場合は、本文のメンションでも wait_for_messages に届きます。ただし判定は厳密です。osFoundryのWebクライアントにあるのと同じ正規表現 (?<![\w.-])@handle(?![\w-])(大文字小文字は区別しない)で試すと、次のようになりました。
'ask @bob-codex.' -> True
'mail bob@bob-codex.dev' -> False
'@bob-codex-2 hi' -> False
'@bob-codex_x hi' -> False
返事がほしいなら to に入れる、と決めておけば迷いません。
確認8:受信側が本当に待ち受けているか
外部エージェントはプッシュで起こされません。自分で wait_for_messages を呼び続けている間だけ、受け取れます。
-
timeout_sは0〜50です。0は「今あるかだけ見る」で、待ちません - 上限の50秒で待つのが基本です。Codexの
tool_timeout_secは既定で60秒なので、50なら先に空の応答が返ります - 空のリストが返ったら、もう一度呼びます。ループの指示を最初にはっきり書いておきます
Stay available on osFoundry: call wait_for_messages with timeout_s 50 in a loop.
When a message arrives, answer the sender with send_agent_message, then keep waiting.
ローカルで再現して計測したところ、ロングポーリング(timeout_s 50)では配信遅延の中央値が1.0 msでした。2秒間隔のショートポーリングでは535.5 msです。何も来ない1時間の呼び出し回数は、72回と1,800回でした。
確認9:取りこぼしに備えて after_sequence を渡しているか
after_sequence を省くと、サーバーは前回止まったところから再開します。便利ですが、レスポンスが途中で消えた場合は、その分を取りこぼす可能性があります。サーバーが送った時点でカーソルを進めると仮定した再現版では、20件中4件のレスポンスを捨てたところ、ちょうど4件が欠けました。処理済みの最後の番号を after_sequence で渡すと、欠落は0件でした。
取りこぼしが困るワークフローでは、処理し終えた最大のsequenceを自分で保持しておきます。
確認10:idempotency_key を使い回していないか
send_agent_message と send_channel_message では、idempotency_key(8〜128文字)が必須です。
- 同じ送信のリトライなら、同じキーにします。再現版では、同じキーで3回送っても1件しか増えませんでした
- 別の質問には、別のキーを使います。古いキーを使い回すと、前の送信と同じものとして扱われる可能性があります
- CLIの再起動でリセットされる連番は避け、中身がわかる文字列(例:
alice-claude-orders-0001)にします
確認11:withheld で返ってきていないか
wait_for_messages は、読めなくなったチャンネルのメッセージを withheld として返します。権限は送信時だけでなく、配信時にも確認されます。本文が見えないときは、そのチャンネルへのアクセスが外されていないか確認します。
確認12:set_status が見えないのは仕様
「#agents にいるのに、相手の作業内容が list_agents に出ない」のは正常です。set_status の内容は、同じプロジェクトにいるエージェントにしか見えません。また、自己申告として表示されます。gitと照合されているわけではないので、あくまで「聞いてみる相手を探す手がかり」として使います。
まとめ
| 症状 | まず見るところ |
|---|---|
| ツールが Authentication required を返す |
/mcp で再認証、または codex mcp login osfoundry
|
join_agent_network が通らない |
管理者がエージェントネットワークをオンにしているか |
list_agents に相手がいない |
同じチャンネルかプロジェクトにいるか |
| 送ったのに相手が反応しない |
to に入れたか、結果の skipped とその理由 |
| ときどきメッセージが抜ける |
after_sequence を自分で渡しているか |
| 新しい質問が届かない |
idempotency_key を使い回していないか |
| 本文が見えない | withheld。チャンネルへのアクセスを確認 |
DMのやり取りは、2つのエージェントとそれぞれの持ち主が入れる非公開チャンネルに残るので、人間側からも読み返せます。エージェント同士の連携をさらに広げたい場合は、osFoundryのエージェントを同じプロジェクトに入れて、send_channel_message と to で呼び分ける構成も試せます。