AI エージェント

Semaphore UI を使用すると、AI コーディングエージェントである Claude Code と Codex を実行できます。エージェントテンプレートは、リポジトリのディレクトリでエージェントのコマンドラインツールを起動し、プロンプトを渡します。エージェントは、質問に答える人がいない状態で自律的に作業し、行った内容をタスクログに出力します。

注記

AI エージェントのテンプレートは Semaphore 2.21 以降で利用できます。

エージェントテンプレートは、同僚に口頭で頼むような作業に使用します。たとえば、最新のコミットをレビューする、失敗しているテストを見つけて修正する、依存関係を更新してプルリクエストを作成する、といった作業です。ほかのテンプレートと同様に、手動で開始することも、スケジュール、インテグレーション、ワークフローから開始することもできます。

始める前に

エージェントのコマンドラインツールがインストールされていること。インストール先は、タスクを実行するマシン（Semaphore サーバーまたはランナー）です。

アプリケーション ID コマンドインストール
Claude Code Agent claude claude npm install -g @anthropic-ai/claude-code
Codex Agent codex codex npm install -g @openai/codex

Semaphore は、起動時に PATH 上でコマンドが見つかったアプリケーションを有効にします。管理者がアプリケーションのページでアプリケーションを有効にし、実行ファイルのパスを設定することもできます。
モデルプロバイダーの API キー。API キーを参照してください。
エージェントが作業するリポジトリ。リポジトリに追加しておきます。

アプリケーション	ID	コマンド	インストール
Claude Code Agent	`claude`	`claude`	`npm install -g @anthropic-ai/claude-code`
Codex Agent	`codex`	`codex`	`npm install -g @openai/codex`

テンプレートの作成

タスクテンプレート セクションに移動し、新しいテンプレート、続いて Claude Code Agent または Codex Agent をクリックします。

Claude Code Agent と Codex Agent の項目がある「新しいテンプレート」メニュー

テンプレートを設定します。

Claude Code Agent テンプレートのエディター

テンプレートでは、次のパラメーターを指定できます。

フィールド	説明
リポジトリ	エージェントが作業するリポジトリです。ほかのテンプレートと同様に、Semaphore はタスクの前にリポジトリをクローンまたは更新します。
サブディレクトリのパス	任意。エージェントを起動するリポジトリ内のディレクトリです。省略した場合、エージェントはリポジトリルートで起動します。
MCP サーバー	任意。エージェントがツールを呼び出せるサーバーを登録した MCP インベントリです。MCP サーバーを参照してください。
変数グループ	エージェント用の変数とシークレットです。API キー、プロンプト式の値、エージェントのプロセスの環境変数を指定します。
プロンプト	エージェントに実行させる指示です。プロンプトを参照してください。
CLI 引数	エージェントのコマンドに追加する引数です。CLI 引数を参照してください。
サーベイ変数	タスクの開始時に尋ねる質問です。回答はプロンプトに埋め込めます。
プロンプトチェックボックス	Claude Code プロンプトまたは Codex プロンプトの下にあります。タスクを開始するユーザーがプロンプトを置き換えられるようにします。タスクのプロンプトを参照してください。

保存をクリックし、実行ボタンでテンプレートを実行します。

API キー

エージェントは API キーを環境変数から取得します。キーは、テンプレートの変数グループにシークレット環境変数として追加してください。

アプリケーション	変数	代わりに使用できる変数
Claude Code Agent	`ANTHROPIC_API_KEY`	`CLAUDE_CODE_OAUTH_TOKEN`
Codex Agent	`OPENAI_API_KEY`	`CODEX_API_KEY`

Semaphore を実行しているユーザーのログイン情報は使用されません。タスクごとにエージェント専用の空の設定ディレクトリが用意されるため、認証する方法は変数グループのキーだけです。

いずれの変数も設定されていない場合、タスクログにどの変数を追加すべきかが表示され、その後エージェント自身がエラーで失敗します。

No API key for claude: add ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN as a secret of the template's Variable Group

プロンプト

プロンプトは、エージェントに入力する内容そのものです。プレーンテキストで、必要なだけ長く書けます。プロンプトは標準入力でエージェントに渡されるため、プロセス一覧には表示されません。

プロンプトは必須です。ただし、プロンプト チェックボックスによってタスクが独自のプロンプトを指定できる場合は省略できます。

プロンプト式

テンプレートのプロンプトには、テンプレートの変数グループの値を埋め込めます。GitHub Actions と同じように二重波括弧で式を書くと、Semaphore がタスクの開始時に値へ置き換えます。

式	値
`${{ vars.extra.NAME }}`	変数グループの追加変数。
`${{ vars.env.NAME }}`	変数グループの環境変数。
`${{ secrets.extra.NAME }}`	変数グループのシークレット追加変数。
`${{ secrets.env.NAME }}`	変数グループのシークレット環境変数。

Find the flaky tests in services/api and fix them.
Open a pull request against ${{ vars.extra.base_branch }} and post its link
to ${{ vars.env.TRACKER_URL }} with the token ${{ secrets.env.TRACKER_TOKEN }}.

ルールは次のとおりです。

サーベイ変数は追加変数として扱われます。サーベイ変数 version への回答は ${{ vars.extra.version }}、シークレットのサーベイ変数は ${{ secrets.extra.NAME }} で参照します。環境変数として渡されるサーベイ変数は、代わりに env の下に入ります。回答されなかったサーベイ変数は空文字列になります。
存在しない変数を参照するとタスクは失敗します。エージェントが起動する前に、該当する式を示すメッセージとともに失敗します。Semaphore は、プロンプトに穴が開いたままエージェントを実行することはありません。
書き間違えた式は、テンプレートの保存時に拒否されます。たとえば ${{ secrets.TOKEN }} には extra も env もありません。
それ以外の式はそのまま残ります。 Semaphore が扱うのは vars.… と secrets.… だけなので、${{ github.sha }} を含むワークフローを書くようエージェントに指示することもできます。vars や secrets の式を文字列のまま残すには、先頭にドル記号をもう 1 つ付けます: $${{ secrets.env.NAME }}。
値はそのまま埋め込まれます。 文字列は書かれたとおりに、リストやオブジェクトは JSON として埋め込まれます。埋め込まれた値の中の式が再度展開されることはありません。
プロンプトに埋め込まれたシークレットは、タスクログでマスクされます。エージェントがどこでその値を繰り返しても同様です。

警告

プロンプト内のシークレットは、プロンプトの残りの部分と一緒にモデルプロバイダーへ送信され、エージェントはプロンプトが許す範囲でそれを自由に使用できます。シークレットは、できるだけエージェントのツールに渡してください。変数グループのシークレット環境変数として渡すか、MCP サーバーのトークンとして渡します。

タスクのプロンプト

プロンプト チェックボックスを有効にすると、タスクのフォームにテンプレートのプロンプトが表示され、その実行に限って変更できます。スケジュール、インテグレーション、ワークフローのステップも、同じ方法で独自のプロンプトを持てます。API 経由の場合は、タスクのパラメーターで送信します。

{
  "template_id": 12,
  "params": {
    "prompt": "Review the changes of the last release and list the risky ones."
  }
}

タスクが指定したプロンプトは、書かれたとおりにそのまま使用されます。プロンプト式が置き換えられるのは、テンプレートに保存されたプロンプトだけです。これにより、タスクの実行しか許可されていないユーザーからプロジェクトの変数とシークレットが守られます。テンプレートが許可していない場合、プロンプトを指定したタスクは拒否されます。

MCP サーバー

エージェントは、リモートの MCP サーバーのツールを呼び出せます。たとえば、課題トラッカー、ドキュメント検索、自社のサービスなどです。サーバーは MCP インベントリ タイプのインベントリに保存され、1 つのインベントリを Claude Code と Codex の両方のテンプレートで使用できます。

インベントリ セクションに移動し、新しいインベントリ、続いて MCP インベントリ をクリックします。
サーバーを追加し、保存をクリックします。
テンプレートの MCP サーバー フィールドでそのインベントリを選択します。

3 つのサーバーが登録された MCP インベントリのフォーム

フィールド	説明
スイッチ	オフにしたサーバーは一覧に残りますが、エージェントには渡されません。
名前	エージェントがサーバーを識別する名前です。英字、数字、`-`、`_` を 64 文字まで使用できます。タスクログではツール名の前に表示されます。
URL	HTTP または SSE 経由で MCP を話すサーバーの `http` または `https` アドレスです。URL にユーザー名やパスワードを含めることはできません。
トークン	任意。エージェントは `Authorization` ヘッダーの bearer トークンとして送信します。

保存されたトークンは暗号化されて保管され、再び表示されることはありません。置き換えるには新しいトークンを入力し、削除するには × ボタンを使用します。トークンは、エージェントのプロセスの環境変数として渡されます。エージェントの設定ファイル、コマンドライン、タスクログには書き込まれません。

呼び出しを確認する人がいないため、選択したサーバーのツールはあらかじめ承認されます。エージェントが使用できるのは、選択したサーバーだけです。Semaphore を実行しているユーザーに設定されている MCP サーバーは使用されません。

CLI 引数

CLI 引数 は、Semaphore 自身が設定する引数の後ろに、エージェントのコマンドへ追加されます。各トークンを個別の引数として入力してください。

["--model", "claude-sonnet-5-5"]

CLI 引数は、エージェント自身のコマンドラインが提供する機能、つまりモデル、各種の上限、権限の指定に使用します。エージェントは無人で実行されるため、確認を求めるツールは代わりに拒否されます。エージェントが確認なしで使用できるツールは、引数で設定します。お使いのバージョンのオプションについては、Claude Code CLI リファレンスと Codex CLI リファレンスを参照してください。

プロンプト の下にある CLI 引数 を有効にすると、タスクが独自の引数を追加できます。

変数グループの変数とシークレットは、エージェントのコマンドラインには追加されません。コマンドラインはプロセス一覧から見えてしまうためです。環境変数とシークレット環境変数は、エージェントのプロセスに渡されます。

エージェントの実行方法

Semaphore は、リポジトリのディレクトリ、またはその サブディレクトリのパス でエージェントを起動し、プロンプトを標準入力に渡します。

アプリケーション	コマンド
Claude Code Agent	`claude -p --output-format=stream-json --verbose --include-partial-messages --mcp-config=<file> --strict-mcp-config --no-session-persistence [--allowedTools=mcp__<server>__*,…] <CLI args>`
Codex Agent	`codex exec --json --skip-git-repo-check <CLI args> -`

タスクごとにエージェント専用の設定ディレクトリがあります（CLAUDE_CONFIG_DIR、CODEX_HOME）。タスクのために作成され、終了後に削除されます。Semaphore を実行しているユーザーの設定、ログイン情報、MCP サーバーはエージェントに渡されず、変数グループの変数でこのディレクトリを別の場所に向けることもできません。
タスク間で何も保持されません。実行のたびにエージェントの新しいセッションになります。実行後も残したいものは、コミット、プルリクエスト、ファイルとしてリポジトリに残してください。
エージェントはリポジトリの指示ファイルを読み込みます。CLAUDE.md や AGENTS.md など、コマンドラインツールが作業ディレクトリで自動的に読み込むファイルです。
Docker および Kubernetes ランナーでは、エージェントはコンテナ内で実行されます。そのため、実行イメージに claude または codex コマンドが含まれている必要があります。

タスクログ

タスクログには、エージェントの作業がリアルタイムで表示されます。

Claude Code タスクのログ。モデル、ツール呼び出し、サブエージェント、サマリーが表示されている

エージェントのテキスト。1 行ずつ表示されます。Codex はメッセージが完成した時点で出力します。
ツール呼び出し。1 回の呼び出しが 1 行で表示され、状態、MCP サーバーとツール、引数が示されます。行をクリックすると引数と結果を確認できます。失敗した呼び出しは最初から開いた状態で表示されます。
サブエージェント。サブエージェントの行には、その名前が付きます。
Claude Code の実行の最初の行には、モデルと MCP サーバーが表示されます。接続できなかったサーバーは赤で示されます。
最後のサマリー。ターン数、所要時間、トークン数、コストが、エージェントが報告する範囲で表示されます。

生ログ では、同じログをプレーンテキストで確認できます。

セキュリティ

エージェントはコマンドを実行します。 コマンドラインツールが与える権限の範囲内で、エージェントはリポジトリのディレクトリを読み書きし、タスクを実行するユーザーとしてプログラムを実行し、MCP サーバーのツールを呼び出せます。エージェントテンプレートには、他人が書いたスクリプトに与えるのと同じ程度のアクセス権を与えてください。つまり、作業に必要な最小限の権限を持つリポジトリとトークンを使用し、サーバーから切り離しておきたい作業には専用のランナーを使用します。
プロンプトとエージェントが読み取った内容は、モデルプロバイダーに送信されます。リポジトリのファイル、コマンドの出力、ツールの結果が含まれます。
リポジトリはエージェントに指示を与えることができます。 エージェントが読み取るファイル、課題、ツールの結果に含まれるテキストによって、エージェントの動作が変わる可能性があります。強力なトークンを持つエージェントを、自分が管理していないコンテンツに向けないでください。
トークンとシークレットはタスクログでマスクされます。MCP サーバーのトークンと、プロンプトに埋め込まれたシークレットは ******** に置き換えられます。
変数とシークレットを使用できるのは、テンプレートに保存されたプロンプトだけです。タスクのプロンプトを参照してください。

始める前に​

テンプレートの作成​

API キー​

プロンプト​

プロンプト式​

タスクのプロンプト​

MCP サーバー​

CLI 引数​

エージェントの実行方法​

タスクログ​

セキュリティ​