build-agent

Agenta エージェントを構築する

平易な言葉で書かれたリクエストを、Agenta 上で動作し、テスト済みのエージェントに変換します。JSON 設定ファイルを 1 つ作成し、同梱されたスクリプトをいくつか実行して実現します。**呼び出し回数と所要時間を最小限に抑えてください。**最もシンプルなエージェントは 2 ステップで作成できます。設定ファイルを作成し、build.sh を実行します。シンプルな依頼について、考えすぎないでください。

Agenta は、LLM アプリとエージェントの構築、テスト、デプロイを行うためのオープンソースプラットフォームです。このスキルでは Agenta HTTP API を使って Agenta エージェント を構築します。

**まずこのスキルを使ってください。**必要なものはすべてこのフォルダーにあります。以下の手順と scripts/ 内のスクリプトです。ここに記載された情報は、稼働中の Agenta デプロイ環境で確認済みです。デフォルトではウェブやコードベースを調べないでください。本当に行き詰まった場合に限り、フォールバックとしてオープンソースのリポジトリ（https://github.com/Agenta-AI/agenta）とドキュメント（https://docs.agenta.ai）を参照できます。ここに書かれている内容を優先してください。

初回実行：認証情報と前提条件

ビルドを始める前に、この 2 つを一度だけ行ってください。

**1. 認証情報。**スクリプトには AGENTA_API_KEY が必要です。ユーザーがセルフホストしている場合のみ AGENTA_HOST も必要です（デフォルトでは Agenta クラウドの https://cloud.agenta.ai が使われます）。

• ユーザーに API キーを尋ねてください。案内先は、Agenta プロジェクト設定の API keys ページです（クラウドの場合は https://cloud.agenta.ai 内）。ユーザーがセルフホストしている場合に限り、ホスト URL も尋ねてください。その場合、ユーザー独自の Agenta ドメインを指定します。
• その後、希望する方法で設定を代行することを提案してください。
  • **こちらで書き込む：**作業ディレクトリに .env ファイルを作成し、AGENTA_API_KEY=...（セルフホストの場合は AGENTA_HOST=... も）を記述します。lib.sh がローカルの .env を自動的に読み込みます。
  • 貼り付け用のブロックを渡す：export 用の行、またはユーザー自身が作成する .env の内容を提示します。
• キーを表示したり、コミットしたりしないでください。ディレクトリがリポジトリの場合は .env を .gitignore に追加してください。

2. 前提条件。bash scripts/check-prereqs.sh を実行してください。bash、curl、jq がインストールされているか確認します。不足している場合は、ユーザーのプラットフォームに合わせた正確なインストールコマンドが表示されます。そのコマンドをユーザーに提示し、ツールをインストールするよう依頼してから続行してください。

すべてのエージェントの構成

エージェントは parameters.agent に含まれる 1 つの JSON オブジェクトです。その中で決めるのは 4 項目だけです。instructions.agents_md（エージェントの役割と動作）、tools（呼び出し可能な連携アクション）、skills（再利用可能なノウハウ）、およびトリガー（スケジュールまたはイベント）が必要かどうかです。それ以外は固定の定型部分なので、そのままコピーしてください。

{
  "instructions": { "agents_md": "<what the agent is and does>" },
  "llm": { "model": "sonnet", "provider": "anthropic", "connection": { "mode": "self_managed" } },
  "tools": [],
  "mcps": [],
  "skills": [],
  "harness": { "kind": "claude" },
  "runner": { "kind": "sidecar", "interactions": { "headless": "auto" } },
  "sandbox": { "kind": "local" }
}

特に指示がない限り、llm / harness / runner / sandbox は上記のままにしてください。model はエイリアス（sonnet、opus、haiku、default）であり、生のモデル ID ではありません。設定項目の完全な説明（ツール項目、スキル項目、誤った場所に配置すると 500 エラーになる項目など）は、references/config-schema.md を参照してください。

ループ（順番に実行し、依頼に不要な手順は省略します）

1. 依頼を読み、何が必要かを判断します。以下の判断表を使います。ほとんどの依頼では、指示だけが必要です。依頼に含まれていないツールやトリガーを探す必要はありません。
2. 連携アクションが必要な場合は、 bash scripts/discover-tools.sh "<capability>" を使って連携機能を確認します。これにより、正確な tools エントリと各接続の状態が出力されます。詳細は references/tools-and-connections.md を参照してください。
3. 必要な接続が ready でない場合は、処理を停止して、接続するようユーザーに依頼します。 推測したり、結果を捏造したりしないでください。接続が必要な連携機能とその理由を伝え、そこで停止します。これは正しい完全な結果であり、失敗ではありません。
4. 設定を書き込みます。 configs/ 配下のファイルに記述してください。連携アクションは tools に、再利用可能なノウハウは skills に、動作は instructions.agents_md に記述します。複数のツールを使うエージェントやスケジュール実行するエージェントの場合は、使用するツールを順番どおりに明記し、最後に終端アクションを指定した、明示的な番号付き手順として instructions.agents_md を記述してください。そうしないと、実行が迷走したり、途中で止まったりします。詳細度については references/writing-instructions.md を参照してください。
5. 一度に作成してテストします： bash scripts/build.sh <config> <slug> "<test message>" を実行します。OUTPUT 行と RESOLVED 行を確認してください。RESOLVED には harness=claude model=sonnet connection=self_managed が表示されている必要があります。
6. トリガーが必要な場合は、 バリアント ID とリビジョン ID の両方を指定して作成します（両方とも create-agent.sh / build.sh の出力に表示されます）。スケジュールは bash scripts/create-schedule.sh で、イベントサブスクリプションは discover-triggers.sh を実行し、接続が ready であることを確認してから bash scripts/create-subscription.sh で作成します。リビジョン ID の指定は必須です。指定しないと、実行するバージョンがトリガーに紐付かず、Agenta UI でエラーとして扱われます。手元にバリアント ID しかない場合は、リビジョン ID の代わりに文字列 latest をそのまま指定してください。bash scripts/triggers.sh schedules（または subscriptions）で確認します。
7. 報告します。 作成したもの、アーティファクト ID、テスト内容、結果、ユーザー側で対応が必要な事項を、簡潔な箇条書きで伝えます。

判断表

依頼の内容…	必要なもの	追加する内容
ユーザーが貼り付けたテキストを変換する（要約、書き換え、分類）	追加なし	instructions のみ
ノウハウを適用する（文体、レビュー基準など）	スキル	skills エントリを1つ
外部ツール（GitHub、Slack など）で読み取りや書き込みを行う	ゲートウェイツール	discover-tools.sh を実行し、その後 tools エントリを追加
時刻に基づいて実行する（例：1日に2回）	スケジュール	エージェントをビルドし、その後 create-schedule.sh を実行
外部イベント（新しい issue、新しいメッセージ）に反応する	サブスクリプション	discover-triggers.sh を実行し、その後 create-subscription.sh を実行（接続が ready である必要があります）
既存のエージェントを変更する	新しいリビジョン	バリアント ID を指定して update-agent.sh を実行し、その後再テスト

スクリプト（API への唯一のインターフェース）

このスキルのディレクトリから bash scripts/<name> として実行します。実際の Agenta エンドポイントを呼び出し、認証情報も自動で読み込みます。API キーを自分で扱う必要はありません。

• check-prereqs.sh — 作業を始める前に、bash／curl／jq を確認します。
• build.sh <config.json> <slug> "<msg>" [name] — エージェントを作成してテストします。最短の手順です。
• create-agent.sh <config.json> <slug> [name] — エージェントだけを作成し、application_id／ variant_id／revision_id を出力します。スケジュールを設定する前に variant id が必要な場合に使います。
• test-agent.sh <application_id> <config.json> "<msg>" — バッチ呼び出しと検証を行います。単一の 非ストリーミング呼び出しで実際のターン全体が返されるため、OUTPUT（最後のアシスタント メッセージ）、TOOLS: 行（呼び出されたすべてのツールと、呼び出し回数および結果数を順に表示）、 承認ゲートで実行が一時停止した場合の APPROVAL: 行、実際に実行で使われた設定の RESOLVED、 および TRACE id を出力します。
• discover-tools.sh "<capability>" ... — 平易な言葉で指定した操作に対応するゲートウェイツールを検索し、各接続の状態と、すぐに配線できるツールオブジェクトを表示します。
• discover-triggers.sh "<event>" ... — イベントトリガーを検索します（サブスクリプション専用）。
• update-agent.sh <variant_id> <config.json> [message] — 既存のエージェントに新しい設定をコミットします。アーカイブして再作成するよりもこちらを優先してください。slug、ID、トリガーはそのまま維持されます。
• create-schedule.sh <variant_id> <revision_id> "<cron UTC>" <event_key> [name] [inputs_json] — cron トリガーを作成します。revision id（create-agent.sh／build.sh から取得）によって、コミット済みのどのバージョンを実行するかが固定されます。省略すると、スケジュールに紐づく revision が設定されません。実際の ID の代わりに latest を渡すと、スクリプトが現在の variant の HEAD revision を検索します。
• create-subscription.sh <variant_id> <revision_id> <event_key> <connection> [name] [trigger_config_json] [inputs_json] — イベントトリガーを作成します。create-schedule.sh と同じく、revision id が必要です（latest のショートカットも使用できます）。接続（ID または slug）は、先に ready でなければなりません。実際に発火したことは triggers.sh deliveries で確認してください。
• triggers.sh schedules|subscriptions|deliveries|rm-schedule <id>|rm-subscription <id>。
• check-tools.sh <trace_id> [terminal_tool] — 任意のフォールバックです。test-agent.sh には、実行時に呼び出されたツールがすでに一覧表示されています（TOOLS: 行）。ゲート付きの WRITE が実際に ok:true を返したことを確認する場合にのみ使用してください。トレーススパンから PASS／INCOMPLETE の判定を得るには、terminal tool を渡します。
• archive-agent.sh <application_id> — アプリをソフト削除します。クリーンアップや slug の解放に使用します。

​scripts/extras/ には、ループでは使わない補助スクリプトが 2 つあります。list-connections.sh （接続の検出結果にはすでに CONNECTIONS ブロックが含まれています。references/tools-and-connections.md を参照） と、annotate-trace.sh（実験者向けのデモ。references/annotate-trace.md を参照）です。

詳細なトピック（必要に応じて参照）

シンプルなエージェントでは、上記の手順に従ってください。タスクで必要になった場合にのみ、次のいずれかを参照します。

目的	参照先
エージェント設定の各フィールドを詳しく理解する	references/config-schema.md
ツールを検索し、接続を配線し、イベントトリガーを追加する	references/tools-and-connections.md
複数のツールを使うエージェントやスケジュール実行するエージェント向けの指示を書く	references/writing-instructions.md
スケジュールまたはサブスクリプションが実行に渡す入力を整える	references/trigger-inputs.md
トレースに対するリフレクションを記録する	references/annotate-trace.md

厳守事項（よくある失敗を防ぐためのルール）

• トリガーにはバリアント ID だけでなく、リビジョン ID も必要です。 create-schedule.sh と create-subscription.sh はどちらも <variant_id> <revision_id> ... を受け取ります。両方を渡す （create-agent.sh / build.sh が出力します）か、バリアント ID しか手元にない場合は、リビジョン ID の 代わりに latest を渡してください。リビジョン ID を省略すると、バージョンが紐づいていない トリガーが作成され、Agenta の UI ではエラー（「どのバージョンを実行しますか？」が必須なのに未設定）として扱われます。
• 呼び出しは最小限にします。 ツールを使わないエージェントに必要なアクションは、設定を書いて build.sh を実行するだけの 2 つです。 リストを再取得したり、ここに記載済みの事実を再確認したり、スキーマを読み直したりしないでください。
• 完了を宣言する前にテストします。 build.sh / test-agent.sh を実行していない主張は、完了とはみなしません。 OUTPUT が正しいこと、RESOLVED に意図した設定が表示されることを確認してください。
• ペルソナは明確な命令形で記述します。 エージェントの基盤は Claude Code です。入力が曖昧だと、 タスクを実行する代わりに、汎用的なコーディングアシスタントのペルソナにフォールバックします。 instructions.agents_md には、エージェントが何者で何をするのかを、曖昧なトピックではなく命令として明記してください。 （単発テストも同様に、動詞を使って表現してください。 "<text>" だけではなく、"次のテキストを要約してください：\n\n<text>" とします。そうしないと、テストがチャットの書き出しとして解釈される可能性があります。）
• cron は UTC、5 フィールド、最短間隔は 1 分です。 ユーザーの現地時刻は自分で変換してください。
• needs_auth なら停止します。 必要な接続が ready でない場合は停止し、ユーザーに接続を依頼してください。そのステップで行う作業はそれだけです。
• 検出は検索であり、万能の判定ではありません。 discover-tools.sh / discover-triggers.sh は、現在のカタログから再現率を重視した最有力候補を返します。一致した 接続状態 は信頼できますが、一致した インテグレーションとアクション が常に正しいとは限りません。検索は単語を照合します。「Notion にメモを保存する」と検索すると、主要なツールとして Slack の SEARCH_MESSAGES が一致し、READY: true と表示されることがあります。一方で、目的の Notion アクションは alternatives に埋もれており、その接続状態は needs_auth という場合もあります。そのため、一致したツールの integration が依頼されたものか確認し、見出しの READY 行ではなく、インテグレーションごとの CONNECTIONS: ブロックを正としてください。一致結果が違う場合は、検索語句を変えるか、候補から選んでください。「新しい Telegram メッセージ」を検索しても、同様に Slack のイベントが返されることがあります。 discover-triggers.sh では、正しい インテグレーション だけでは不十分です。キーワード照合によって、同じインテグレーション内の誤った イベント が選ばれることがあります（たとえば「新しい GitHub issue がオープンした」で、共通する単語「created」だけをもとに GITHUB_ARTIFACT_CREATED_TRIGGER イベントが一致し、接続状態は ready と表示される場合があります）。create-subscription.sh に設定する前に、スクリプトが出力する MATCHED イベントの fires_on 行と ALTERNATIVES ブロックを必ず確認してください。もっともらしい event_key が正しいインテグレーションに属し、接続状態が ready であっても、依頼された内容をトリガーする証拠にはなりません。MATCHED または ALTERNATIVES に依頼されたイベントに該当するものがない場合は、停止して、このインテグレーションはそのトリガーをまだサポートしていないとユーザーに伝えてください。キーワードが最も近い候補を設定してはいけません。
• 既存のエージェントは再作成せず、コミットして変更します。 update-agent.sh <variant_id> <config.json> は同じアプリに新しいリビジョンをコミットします。スラッグ、ID、スケジュールやサブスクリプションはそのまま機能します。アーカイブして再作成すると、そのすべてが失われます。更新後は test-agent.sh で再テストしてください。
• ビルドが失敗してもアプリは作成されています。 build.sh がアプリを作成した後に invoke が失敗した場合、アプリ（とそのスラッグ）はすでに存在します。設定を修正し、既存の application_id に対して test-agent.sh で再テストしてください。同じスラッグを指定して build.sh を再実行してはいけません（競合します）。最初からやり直す場合は、先に archive-agent.sh <application_id> を実行してください。
• invoke では設定をインラインで渡します（これはラボの成果物であり、欠落ではありません）。 build.sh と test-agent.sh は、コミット済み参照をハイドレートしない低レベルの agent-service エンドポイントへの各 invoke に、設定全体をインラインで渡します。これは、確定済みのエンドポイント／認証／ボディ形式の契約とは無関係です。agenta リポジトリの docs/designs/invoke-negotiations/specs.md を参照してください。製品 API の invoke 経路では、サーバー側でコミット済み参照を読み込むため、参照のみを使った invoke は実際に利用可能な製品機能です。このキットはまだその経路を使っていませんが、参照のみで invoke するようスクリプトを書き換える必要はありません。
• 報告は簡潔にします。 箇条書きを数点にまとめます。結果と成果物の ID から先に述べてください。

検証（HTTP 200 を鵜呑みにしない）

test-agent.sh はストリーミングなしの invoke（Accept: application/json）を送信します。レスポンスの data.outputs には、最終的な文字列だけでなく、実行の完全なターンが含まれます。messages（アシスタントの テキストに加え、すべてのツール呼び出しと結果を順番に示す role: "tool" エントリ）、stop_reason、そして 実行が承認ゲートで一時停止した場合に限り pending_interaction が含まれます。スクリプトはこれを 直接読み取るため、以下の OUTPUT／TOOLS／APPROVAL はすべて invoke レスポンスから取得され、トレースは 不要です。（エンドポイント、認証、本文の形式、レスポンスの契約は確定しています。agenta リポジトリの docs/designs/invoke-negotiations/specs.md を参照してください。スクリプトは追加のヘッダーを送信しないため、 デフォルト設定（完全なトランスクリプト、解決済みのワークフロー埋め込み）が適用されます。）

test-agent.sh は実行のトレースから RESOLVED も出力します。意図した内容と一致している必要があります。 別のハーネス／モデルが表示された場合、実行は気付かないうちにフォールバックしています。設定を修正して再テストしてください。 トレースのフラッシュには 1～2 秒ほど遅れが生じますが、スクリプトはすでに再試行します。

複数のツールを使うエージェントでは、OUTPUT だけでなく TOOLS: の行を確認してください。 複数のツール呼び出しを行う実行は、 ツール呼び出しのターンで終わることがあるため、OUTPUT（最後のアシスタントメッセージ）が実際に空になる場合があります。 これは失敗でも解析漏れでもありません。最後のターンが返信ではなく、ツール呼び出しだったことを意味します。 test-agent.sh の TOOLS: 行には、実行が呼び出したすべてのツールが順番に並び、それぞれの結果の ok／ERROR が表示されます（例： github__LIST_COMMITS -> ok -> slack__SEND_MESSAGE -> ok (2 calls, 2 results)）。この行が、「終端ツールまで到達したか、そのツールが ok を返したか」を示す信頼できるシグナルです。 終端ツールが ok の結果とともにリストにあれば、実行はそこまで到達して完了しています。リストにない場合は、 実行が途中で停止しています（初期の読み取りは行ったものの、その後さまよい、最後のアクションに到達しませんでした）。 途中で停止した場合は、より明確で番号付きの指示を使って再テストしてください。通常、設定に問題はなく、実行がさまよっただけです。 references/writing-instructions.md を参照してください。

stop_reason == "paused" の場合、test-agent.sh は APPROVAL: 行を出力します。WRITE（SEND_MESSAGE など）が 人による承認ゲートにかかったことを示します。実行はそこで停止しています。そのツール呼び出しは TOOLS にありますが、 実行前に一時停止したため、対応する結果はまだありません。この invoke 中に WRITE が完了しない場合もあります （承認が未解決のままになることがあります）。

check-tools.sh は、この invoke ではまだ確認できない内容の代替手段です。つまり、ゲートのかかったツールが実際に 後から結果を返したかどうかを確認します。トレースのスパンを読み取り、ツールのスパンは呼び出された時点で現れますが、 結果を含むのは実際に結果が返された後だけです。そのため、bash scripts/check-tools.sh <trace_id> SEND_MESSAGE は、ツールが実行され、結果が返された場合にのみ VERDICT: PASS を出力します。 ツールがディスパッチされたものの、スパンに結果がない場合（承認待ちで停止した典型的な状態）は UNCONFIRMED、 実行されなかった場合は INCOMPLETE を出力します。実行済みツールのリストにツール名があっても、完了した証拠にはなりません。 ゲートのかかった WRITE が、結果なしでリストに残っていることがあります。また、外部への WRITE については、結果が返っていても、 副作用を読み戻して確認するまでは確証になりません（例：チャンネルの履歴を取得する）。読み戻しが唯一確実な確認方法です。