ワーカーエージェントを MCP から操作する
ワーカーエージェントは、画面だけでなく MCP クライアント(Claude Code など)からも作成・実行・確認できます。「部下の稼働状況を毎週確認して私のタスクに登録するエージェントを作って、いま1回試して、問題なければ毎週月曜の朝9時に実行して」のように話しかけるだけで、AI がツールを順に呼び出して設定まで進めます。
接続先
| エンドポイント | 用途 |
|---|---|
https://mcp.tocca.systems/api/mcp/worker-agent | ワーカーエージェントの作成・更新・実行・実行結果の確認 |
Claude Code への登録例(APIキーの発行手順は Claude Code セットアップ を参照):
claude mcp add --transport http twp-worker-agent https://mcp.tocca.systems/api/mcp/worker-agent \
--header "Authorization: Bearer twpu_xxxxxxxx"必要なスコープ
個人用APIキーには、次の2種類のスコープが両方必要です。
-
ワーカーエージェント自体の操作(「AIエージェント」グループ)
スコープ できること worker_agent:read一覧・詳細・実行履歴・ステップログ・ツールカタログ・上限の確認 worker_agent:write作成・更新・削除・有効化・無効化 worker_agent:execute手動実行・実行のキャンセル worker_agent:*上記すべて -
エージェントに許可するツールのスコープ
エージェントはオーナーの権限で動きますが、MCP から作成・更新・実行するときは、許可ツールが使うスコープをAPIキーも持っていることが確認されます。たとえば
create_private_task(プライベートタスクの作成)を許可するならtask:write、list_subordinates(部下の一覧)を許可するならuser:readが要ります。各ツールに必要なスコープはlist_worker_agent_toolsのrequired_api_scopesで確認できます。足りない場合は
422になり、不足しているスコープ名がそのまま返ります。API error 422: 許可ツールの実行に必要な権限がこの資格情報にありません(不足: task:write, user:read)。 Error fields: {"missing_scopes":["task:write","user:read"]}「書き込み系ツールの実行を許可する」(
write_enabled)をオフにしたエージェントでは、書き込みツールのスコープは求められません(参照ツールのスコープは必要です)。
例: 部下の勤怠・工数を確認してプライベートタスクへ登録するエージェントなら、
worker_agent:*+attendance:read+attendance_team:read+user:read+task:writeが目安です。勤怠を読むツールは、本人用のattendance:readに加えてチーム勤怠閲覧のattendance_team:readも求めます(どちらか一方だけでは422になります)。担当タスクの一覧も見せるならtask:readを加えてください。
利用できるツール
| 分類 | ツール |
|---|---|
| ツールカタログ・上限 | list_worker_agent_tools / get_worker_agent_tool / get_worker_agent_limits |
| エージェント | list_worker_agents / get_worker_agent / create_worker_agent / update_worker_agent / delete_worker_agent |
| 有効・無効 | enable_worker_agent / disable_worker_agent |
| 実行 | run_worker_agent / list_worker_agent_runs / get_worker_agent_run / get_worker_agent_run_steps / cancel_worker_agent_run |
見えるのは自分がオーナーのエージェントだけです。他のユーザーのエージェントIDを指定すると 404(見つかりません)になります。
作成から実行・確認までの流れ
- ツール名を確かめる —
list_worker_agent_toolsで、許可できるツールの正確な名前を取得します。推測した名前をallowed_toolsに入れると422になります - 作成する —
create_worker_agentに名前・指示文・許可ツール・スケジュールを渡します。作成直後は無効(is_enabled=false)です - 試しに実行する —
run_worker_agentを呼びます。dry_run: trueを付けると書き込みは行わず、「何をしようとしたか」だけを記録します - 完了を確認する —
run_worker_agentの応答は「実行を開始した」という意味で、結果ではありません。返ってきたrun_idでget_worker_agent_runを呼び、statusがsucceeded/failed/cancelled/skippedになるまで確認します(通常は数十秒〜数分)。完了するとsummaryに実行内容の要約が入ります。途中経過はget_worker_agent_run_stepsで確認できます - 定期実行にする — 問題がなければ
enable_worker_agentで有効にします
MCP から作成したエージェントは、画面の一覧でも確認でき、作成時にはオーナーへ「MCP経由で作成されました」という通知が届きます。
twp CLI から立ち上げる(定期分析エージェントの例)
twp CLI を使うと、指示文をファイルに書いてコマンド1つでエージェントを作成し、その場で1回試してから定期実行に切り替えられます。MCP クライアントを用意しなくても、同じエージェントを作れます。
ここでは例として、見積・請求の差し戻しを毎週分析し、申請前AIチェックの観点追加案を出すエージェントを立ち上げます。分析・改善系のほかの用途(勤怠の傾向確認、タスクの滞留確認など)も、指示文と許可ツールを入れ替えるだけで同じ手順で立ち上げられます。
1. 許可するツールを決める
twp worker-agent tools で、許可できるツールの正確な名前を確認します(--keyword や --category で絞り込めます)。
twp worker-agent tools --category salesこの例で使うツールは次のとおりです。
| ツール | 種別 | 用途 |
|---|---|---|
list_sales_send_backs | 参照 | 直近の差し戻し記録(承認者のコメントと、差し戻し時点のAIチェックの指摘・申請者の理由)を取得する |
get_sales_send_back_summary | 参照 | 週ごとの差し戻し件数を取得する(件数は集計済みの値をそのまま使う) |
list_sales_ai_review_criterion_proposals | 参照 | これまでに出した観点追加案と採否・採否日時を確認する |
propose_sales_ai_review_criterion | 書き込み | 観点追加案を提出する(承認者が画面で採否を決めるまで、AIチェックには反映されません) |
create_note | 書き込み | 週次の報告をノートに残す |
get_department_tree / list_department_members | 参照 | 報告先(承認者)を部署から引き当てる |
send_notification_to_users | 書き込み | 承認者へ報告を通知する |
- エージェントはオーナーの権限で動きます。差し戻し記録を読むツールは、オーナーが見積・請求の一覧を全プロジェクト分閲覧できないと実行時に権限エラーになります。観点追加案の提出と一覧の参照には、販売管理の管理者権限が必要です
- 差し戻し記録は記録を始めた時点から残ります。それより前の差し戻しは、件数・分類の対象になりません
2. 指示文をファイルに書く
指示文は --instructions-file で渡します(20,000文字まで)。「何を取得し、どう判断し、何をどこへ出すか」を順に書くと、実行のたびに同じ形の結果が得られます。
あなたは見積・請求の承認フローの差し戻しを分析し、申請前AIチェックを継続的に改善する担当です。毎週次の手順で進めてください。
## 1. 差し戻しを集めて分類する
- list_sales_send_backs で直近7日間の差し戻しを取得する(next_cursor があれば続きも取得する)
- 承認者のコメントから指摘内容を読み取り、分類する(例: 明細の単位、有効期限と前提条件の不一致、備考の記載漏れ、添付ファイルの誤り、宛名・注文書番号の不一致、AIチェック指摘への理由不足)
## 2. AIチェックで指摘できていたかを突き合わせる
- 分類ごとに、差し戻し時点のAIチェック(ai_review の観点・指摘文・申請者の理由)に同じ内容の指摘があったかを確認する
- 指摘できていなかった分類 → propose_sales_ai_review_criterion で観点追加案を提出する
- 先に list_sales_ai_review_criterion_proposals で同じ趣旨の案が既に出ていないか確認し、重複して出さない
- 本文は全社共通の基準として書く。取引先名・案件名・個人名は書かない
- 根拠にした差し戻し記録の id を send_back_record_ids に入れる
- 指摘できていたのに差し戻された分類 → 原因(申請者の見落とし、理由の記載が不十分 等)を整理する。案は出さない
- ai_review が null の記録は突き合わせできないため、分類だけ行う
## 3. 効果を確認する
- get_sales_send_back_summary で直近8週の差し戻し件数の推移を取得する(件数は自分で数え直さず、返った値を使う)
- list_sales_ai_review_criterion_proposals で採用済み(adopted)の案を取得し、案ごとに採用日以後の同じ分類の差し戻し件数を示す
- 採用後も減っていない観点は「見直し対象」として挙げる
## 4. 報告する
- create_note で「差し戻し週次分析 YYYY-MM-DD」というノートを作り、次の順で書く
1. 件数の推移(週ごと・見積/請求別)
2. 今週の分類と件数
3. 提出した観点追加案(分類・根拠件数)
4. 指摘できていたのに差し戻された分類と原因
5. 見直し対象の観点
- get_department_tree で「<承認者の部署名>」の部署IDを調べ、list_department_members でメンバーを取得してから、send_notification_to_users で承認者へ通知する
- ノートはこのエージェントのオーナーしか開けないため、通知の本文だけで内容が分かるように書く(提出した観点追加案の分類・根拠件数、件数の推移の要点)
- 観点追加案を提出した週は、採否をお願いする旨と採否画面の場所(「取引 > AIチェック理由」タブ下部の「差し戻し由来の観点追加案」)を書き、url に propose_sales_ai_review_criterion が返す review_url(/v1/sales/ai-review-reasons#criterion-proposals)を指定する。通知から採否画面へ直接移動できる
- 差し戻しが0件の週は、件数の推移だけをノートに残し、通知は送らない3. 作成して1回試す
twp worker-agent create \
--name "差し戻し週次分析" \
--instructions-file instructions.md \
--tool list_sales_send_backs,get_sales_send_back_summary,list_sales_ai_review_criterion_proposals \
--tool propose_sales_ai_review_criterion,create_note,get_department_tree,list_department_members,send_notification_to_users \
--schedule weekly:mon@09:00 \
--write-enabled --yes
# 書き込みはせず「何をしようとしたか」だけを記録して試す(AI のクレジットは消費します)
twp worker-agent run start "差し戻し週次分析" --simulate --wait --yes
# 内容に問題がなければ実際に1回実行する
twp worker-agent run start "差し戻し週次分析" --wait --yes- 作成直後は無効です。
run startによる手動実行だけが行われます --waitは実行が終わるまで待ち、最終要約を先頭にした実行記録を表示します(終了コード0=成功・3=失敗または取消・4=待ち時間の上限に達したが実行は継続中)- 途中の判断を確かめたいときは
twp worker-agent run steps "差し戻し週次分析" <実行ID>でステップログを確認します
4. 定期実行に切り替える
twp worker-agent enable "差し戻し週次分析"
twp worker-agent get "差し戻し週次分析" # スケジュールと次回実行予定を確認する指示文やツールを変えるときは twp worker-agent update で、変えたい項目だけを指定します。止めるときは twp worker-agent disable です。
スケジュールの書式
schedule は次の形式で指定します。
{ "type": "weekly", "days_of_week": [1], "time_of_day": "09:00", "timezone": "Asia/Tokyo" }type | 必須の項目 | 制約 |
|---|---|---|
interval(一定間隔) | interval_minutes | 15〜1440分・5の倍数のみ(00:00 起点で揃えます) |
daily(毎日) | time_of_day(HH:mm) | — |
weekly(毎週) | time_of_day・days_of_week | 曜日は ISO 番号(1=月曜 … 7=日曜) |
monthly(毎月) | time_of_day・days_of_month または last_day_of_month | 存在しない日(2月31日など)はその月は実行しません |
- タイムゾーンは
Asia/Tokyo固定です(他の値はエラーになります) - 時刻指定の実行は、指定時刻から最大5分遅れて始まることがあります
- 自動実行がまだ有効になっていない環境では、作成・更新・有効化の応答に
schedule_noticeが含まれます。その間スケジュールは保存されますが自動では動かず、run_worker_agentによる手動実行だけが行われます
実行回数の上限とクレジット
| 上限 | 値 |
|---|---|
| 手動実行 | 1エージェントあたり 1日20回 |
| 有効にできるエージェント | 1ユーザー3件・1テナント20件 |
| 1エージェントの許可ツール | 64個まで |
現在の値と当日の使用状況は get_worker_agent_limits で確認できます。
run_worker_agentを連続で呼ばないでください。 呼ぶたびに手動実行を1回消費します。完了を待つときはget_worker_agent_runを呼び直してください- ドライランでも、AI が考えるためのトークン分のクレジットを消費します
- 実行中・上限到達・クレジット不足などで実行できないときは
409になり、理由(skip_reason)とrun_idが返ります
うまくいかないとき
| 症状 | 確認すること |
|---|---|
422 で missing_scopes が返る | APIキーに不足スコープを追加する(上の「必要なスコープ」)か、そのツールを許可ツールから外す |
422 で allowed_tools のエラーになる | list_worker_agent_tools が返す名前をそのまま使う |
404 になる | 自分がオーナーのエージェントか、agent_id が正しいかを確認する |
| 設定した時刻に動かない | 応答に schedule_notice が含まれていないか、エージェントが有効(is_enabled=true)かを確認する |