create-task

ユーザーが新しい Harbor タスクを最初から最後まで作成できるように案内してください。コマンドを並べるだけでなく、特に通常もっとも難しい検証方法について、各判断を一緒に進めてください。

ステップ 1：タスクのひな形を作成する

harbor task init "<org>/<task-name>"

便利なフラグ：

• --description "..."
• --author "Jane Doe <[email protected]>"（複数の作成者を指定する場合は繰り返します）
• --no-pytest — pytest のテストテンプレートをスキップします（Reward Kit またはカスタム検証器を使う予定の場合に使用します）
• --no-solution — solution/ ディレクトリをスキップします
• --metadata-template path.toml — task.toml に事前に値を入力します

生成されるもの：

<task-name>/
├── instruction.md         # Task prompt for the agent
├── task.toml              # Config and metadata
├── environment/Dockerfile # Container definition
├── solution/solve.sh      # Reference solution (optional)
└── tests/test.sh          # Verifier script

ユーザーが複数ステップのタスク（共有コンテナ上で、ステップごとに指示やテストがあり、途中で停止できる、順序付けられたステップ）を作成したい場合は、まずシングルステップのレイアウトを作成してから、下記の複数ステップのタスクのセクションに記載されている steps/ レイアウトに変換してください。

ステップ 2：instruction.md を作成する

これはエージェントに渡されるプロンプトです。明確に書けるよう、ユーザーをサポートしてください。

• 目標を具体的に示す — 作成するファイルや実現する動作
• 期待する出力を指定する — パス、形式、内容
• 制約を含める — 言語、ツール、アプローチ
• テストの内容を明かさない — 確認方法ではなく、完了時の状態を説明する

例（ssh-key-pair チュートリアルより）：

# SSH Key Pair Generation

Generate an SSH key pair in the files `~/.ssh/id_rsa` and `~/.ssh/id_rsa.pub`.

Don't make them password protected.

ステップ 3：環境を構築する

environment/Dockerfile を編集して、タスクに必要な依存関係をインストールします。エージェントはこのコンテナ内で作業します。

FROM ubuntu:24.04
WORKDIR /app

# Install what the task requires — NOT the solution
RUN apt-get update && apt-get install -y openssh-client && rm -rf /var/lib/apt/lists/*

複数コンテナの構成では、代わりに environment/docker-compose.yaml を使います（注：ほとんどのクラウドサンドボックスプロバイダーは Dockerfile のみをサポートします）。

ソリューションやテストを書く前に、環境を対話的にテストしてください。

harbor task start-env -p "<task-path>" -e docker -a -i

通常、ここでタスクの作成者は Dockerfile に何かが足りないことに気づきます。

ステップ 4：検証方法を決める

これがもっとも重要な判断です。 ユーザーに「このタスクをどのように評価しますか？」と尋ねてから、適切な方法を選べるようサポートしてください。

また、「検証器はエージェントと同じ環境で実行しますか、それとも別の検証環境で実行しますか？」とも尋ねてください。

• テストでエージェントのワークスペース全体、インストール済みツール、またはサービスを調べる必要がある場合は、デフォルトの共有環境を使います。
• コード、依存関係、API キー、または OS の要件をエージェントに見られないようにする場合や、クリーンなイメージから検証を実行する場合は、別の検証環境を使います。

検証用のコンテナを分ける場合、tests/ が検証用イメージのビルドコンテキストになり、イメージには /tests/test.sh（Linux）または /tests/test.bat（Windows）が必要です。Harbor は、エージェントのワークスペース全体ではなく、/logs/artifacts と設定されたアーティファクトを検証環境にコピーします。

[verifier]
environment_mode = "separate"

[verifier.environment]
docker_image = "ubuntu:24.04"

オプション A：Reward Kit（ほとんどの場合におすすめ）

検証に複数の基準がある場合、部分点が必要な場合、LLM／エージェントの評価者を使う場合、または再利用可能なチェックを組み合わせると便利な場合に使います。rewardkit スキルを参照してください。

適しているケース：

• 確認項目が複数ある（ファイルの存在、内容の正しさ、コマンドの動作など）
• 主観的な品質基準がある（読みやすさ、文章の正確さ）
• 合否だけでなく部分点を付けたい
• file_contains、command_succeeds、json_key_equals などの組み込み機能を組み合わせたい

tests/test.sh：

#!/bin/bash
uvx --python '>=3.12,<3.14' --from 'harbor-rewardkit==0.2.*' rewardkit /tests

注：パッケージ名は harbor-rewardkit ですが、実行可能ファイル名は rewardkit です。そのため、--from 'harbor-rewardkit==0.2.*' rewardkit を使います。uvx harbor-rewardkit を直接実行すると失敗します。

続いて、tests/checks.py および／または tests/judge.toml を追加します。基準を設計するには、rewardkit スキルを呼び出してください。

オプション B：pytest（決定的なユニットテスト形式のチェックに適しています）

検証が単純なアサーション形式の Python で済む場合に使います。--no-pytest が渡されていない場合は、デフォルトのテンプレートが使われます。

tests/test.sh：

#!/bin/bash
apt-get update && apt-get install -y curl
curl -LsSf https://astral.sh/uv/0.9.7/install.sh | sh
source $HOME/.local/bin/env

uvx --with pytest==8.4.1 pytest /tests/test_outputs.py

if [ $? -eq 0 ]; then
  echo 1 > /logs/verifier/reward.txt
else
  echo 0 > /logs/verifier/reward.txt
fi

tests/test_outputs.py の例：

from pathlib import Path

def test_file_exists():
    assert (Path.home() / ".ssh" / "id_rsa").exists()

オプション C：カスタムシェル

1 つのコマンドで合否が決まる単純なチェック（例：1 つのコマンドの実行結果によるバイナリ形式の合否判定）に使います。

#!/bin/bash
if diff -q /app/output.txt /tests/expected.txt; then
  echo 1 > /logs/verifier/reward.txt
else
  echo 0 > /logs/verifier/reward.txt
fi

Reward ファイル形式（すべてのオプション）

• /logs/verifier/reward.txt — 数値 1 つ（通常は 0 または 1）
• /logs/verifier/reward.json — 複数の指標の場合は {"accuracy": 0.95, "runtime_sec": 1.2}

test.sh では常に絶対パスを使用してください。

Step 5: 解答を作成する

solution/solve.sh を作成します。タスクを実際に解決するスクリプトです。Oracle エージェントはこれを実行し、タスクが解決可能で、正しい解答でテストに合格することを確認します。

#!/bin/bash
ssh-keygen -t rsa -f ~/.ssh/id_rsa -N ""

実行可能にします：chmod +x solution/solve.sh。

Step 6: task.toml を設定する

重要なフィールドを確認します。

[task]
name = "<org>/<task-name>"
version = "1.0.0"
description = "One-line description"
keywords = ["jax", "mnist", "rewardkit"]  # always populate — used for search/filtering

[metadata]
difficulty = "easy" | "medium" | "hard"
category = "programming" | "machine-learning" | "gpu" | ...
tags = ["..."]

[agent]
timeout_sec = 120.0       # How long the agent has

[verifier]
timeout_sec = 600.0       # How long tests have

[environment]
network_mode = "public"   # Baseline at env start (defaults to public)
cpus = 1                  # CPU cores
memory_mb = 2048          # RAM in MB
storage_mb = 10240        # Disk in MB

keywords は必ず設定してください。 ドメイン（言語／フレームワーク／ベンチマークファミリー）、検証スタイル（rewardkit、judge-grading、pytest）、および特筆すべきハードウェア（gpu）を表す、小文字のトークンを 3〜8 個選びます。これらは harbor datasets list とレジストリ検索に表示されます。

ネットワークポリシー

ネットワークアクセスには次の 3 つのレイヤーがあります。

1. ベースライン — 環境の開始時に設定され、フェーズ間で復元されます
2. フェーズのオーバーライド — 任意。agent.run() または verify() の実行中にのみ適用されます
3. 実行時のマージ — harbor run の --allow-environment-host、--allow-agent-host、--allow-verifier-host

フィールド	レイヤー	適用されるタイミング
[environment].network_mode	ベースライン	エージェント環境の開始時。共有検証環境にも適用されます
[verifier.environment].network_mode	ベースライン	分離された検証環境の開始時
[agent].network_mode、[steps.agent].network_mode	オーバーライド	対応する agent.run() の実行中
[verifier].network_mode、[steps.verifier].network_mode	オーバーライド	対応する verify() の実行中
--allow-environment-host	実行時	environment.extra_allowed_hosts にマージされ、[environment] のベースラインに適用されます
--allow-agent-host	実行時	agent.extra_allowed_hosts にマージされ、エージェントフェーズの許可リストに適用されます
--allow-verifier-host	実行時	verifier.extra_allowed_hosts にマージされ、検証フェーズの許可リスト（および分離された検証環境のベースライン）に適用されます

モードは public、no-network、または allowed_hosts = ["pypi.org"] を指定した allowlist です（選択した環境が対応している場合、正確なホスト名、IPv4／IPv6 アドレスリテラルまたは CIDR 範囲、先頭にワイルドカードを付けたホスト名を指定できます。URL、ポート、パスは指定できません）。[environment].network_mode を省略すると、デフォルトで public になります。

[agent]／[verifier] は任意のフェーズオーバーライドです。設定され、かつフェーズのベースラインと異なる場合にのみ適用されます。ベースラインと一致する場合は何も行われません。

共有検証環境（デフォルト）：検証はエージェントのコンテナ内で実行されます。ベースラインは [environment] です。分離された検証環境：[verifier.environment] が設定されていればその値、それ以外の場合は [environment] のコピーがベースラインになります。

# Agent starts offline; agent phase opens network; verifier stays offline
[environment]
network_mode = "no-network"

[agent]
network_mode = "public"

[verifier]
network_mode = "no-network"

フェーズのオーバーライドがベースラインと異なる場合、環境プロバイダーは dynamic_network_policy に対応している必要があります（E2B は対応していますが、通常の Docker は対応していません）。エージェントと検証環境に異なるベースラインが必要で、実行時の切り替えを避けたい場合は、environment_mode = "separate" を使用してください。

[environment]
network_mode = "no-network"

[verifier]
environment_mode = "separate"

[verifier.environment]
network_mode = "public"   # Verifier baseline — not a phase override

task.toml を編集せずに評価ジョブの実行時ホストフラグを指定するには：

harbor run -p "<task-path>" -a oracle \
  --allow-environment-host pypi.org \   # env start (Dockerfile apt/curl)
  --allow-agent-host files.pythonhosted.org \  # agent.run() only
  --allow-verifier-host llm-proxy.example.com   # verify() only (e.g. LLM judge proxy)

ベースラインが public の場合、実行時ホストフラグは警告を出して無視されます。

例：examples/tasks/network-policy-matrix/。完全なリファレンス： docs-mintlify/tasks/network-policies.mdx。

API キーが必要な Reward Kit の judge の場合：

[verifier.env]
ANTHROPIC_API_KEY = "${ANTHROPIC_API_KEY}"

Step 7: Oracle エージェントで検証する

harbor run -p "<task-path>" -a oracle

Oracle は solution/solve.sh を実行し、その後に検証を行います。Reward は 1.0 になるはずです。そうならない場合は、次の順でデバッグしてください。

1. solve.sh は実際にタスクを解決していますか？（start-env -a -i を実行して、手動でスクリプトを実行します）
2. 検証は成功を正しく検出していますか？（/logs/verifier/ の出力を確認します）
3. パスは正しいですか？（絶対パスか相対パスか）
4. Dockerfile で依存関係がインストールされていますか？

Step 8: 実際のエージェントでテストする（任意）

harbor run -p "<task-path>" -a terminus-2 -m anthropic/claude-sonnet-4-6

タスクが簡単すぎる（すべてのモデルが 1.0）または不可能（すべてのモデルが 0.0）な場合は、難易度の調整を検討してください。

ステップ 9：README.md を更新する（必ず最後に行う）

harbor task init を実行すると、README.md はひな形のまま残ります。作業を終える前に内容を記入し、将来の人間（およびエージェント）がすべてのファイルを読まなくてもタスクを理解できるようにしてください。 以下を含めてください。

• エージェントの動作 — 1段落で説明し、instruction.md へのリンクを記載します。
• 環境 — ベースイメージ、主なインストール済みパッケージ、キャッシュ済みデータ、ハードウェア（GPU／CPU／RAM）、エージェントのタイムアウト。
• 検証器 — Reward Kit のタスクでは、報酬の各評価項目と、それぞれのタイプ（プログラムによる判定／LLM ジャッジ／エージェントジャッジ）、および評価内容を表にします。集計方法も記載します。
• 構成 — タスクディレクトリのツリーと、各項目の1行の説明。
• 実行方法 — Oracle と実際のエージェントを使う具体的な harbor run コマンド。タスクで GPU が必要な場合は、適切なプロバイダーフラグを指定します。

これは宣伝ではなくドキュメントとして記述してください。読者が知りたいのは、タスクを変更する際に何を変更すればよいかです。

複数ステップのタスク

作業が順序付けられたフェーズに分かれ、それぞれを個別に評価したい場合、フェーズ間で早期終了したい場合、またはエージェントが自身の過去の作業を基に進める能力をテストしたい場合に使用します。各ステップは1つのコンテナーを共有し、ファイルはステップ間で保持されます。

ディレクトリ構成

タスクルートの instruction.md、tests/、solution/ を、ステップごとに1つのサブディレクトリを含む steps/ ディレクトリに置き換えます。

各 [[steps]].name は、255 UTF-8 バイト以下のディレクトリ名と一致し、Unicode の大文字小文字変換および正規化後も一意でなければなりません。パス区切り文字、制御文字、Windows で予約されている文字やデバイス名、末尾のピリオドや空白は使用しないでください。すべてのタスク入力とリンク先の内容をタスクディレクトリ内に保ってください。検証では、タスク内の共有リンクが許可されます。タスクを公開する際は、共有入力に通常のファイルとディレクトリを使用してください。

<task-name>/
├── task.toml
├── environment/Dockerfile       # Built once, shared across all steps
├── steps/
│   ├── scaffold/
│   │   ├── instruction.md       # Prompt for this step
│   │   ├── workdir/             # Uploaded to WORKDIR before the agent runs
│   │   │   └── setup.sh         # Optional pre-agent hook (reserved filename)
│   │   ├── tests/test.sh        # Per-step verifier
│   │   └── solution/solve.sh    # Per-step Oracle solution (optional)
│   ├── implement/
│   │   └── ...
│   └── document/
│       └── ...
└── tests/                       # Optional shared helpers + fallback test.sh

タスクレベルの tests/ は各ステップの検証時に /tests にアップロードされ、その後、ステップ固有の tests/ が重ねて配置されます（同名のファイルは後から配置されたものが優先されます）。共有ヘルパーにはこれを使用してください。

steps/{name}/workdir/setup.sh は予約済みファイル名です。存在する場合、workdir/ のアップロード後、エージェントの実行前に、そのステップのエージェントユーザーとして、cwd = WORKDIR で実行されます。ゼロ以外の終了コードが返されると、ステップと試行は中断されます。エージェントにこのファイルを見せない場合は、最後の行に rm -- "$0" を記述してください。

task.toml

schema_version = "1.4"

# How per-step rewards roll up into the trial-level verifier_result.
# "mean" (default): per-key mean across steps that produced a result.
# "final": the last step's verifier_result verbatim.
multi_step_reward_strategy = "mean"

[task]
name = "<org>/<task-name>"
version = "1.0.0"

[[steps]]
name = "scaffold"              # Must match the directory under steps/
min_reward = 1.0               # Abort trial if this step's reward < 1.0
[steps.agent]
timeout_sec = 60.0             # Overrides task-level [agent].timeout_sec
[steps.verifier]
timeout_sec = 30.0

[[steps]]
name = "implement"
# Dict form gates on specific keys from a multi-dim reward:
min_reward = { correctness = 0.8, style = 0.5 }
[steps.agent]
timeout_sec = 120.0
[steps.verifier]
timeout_sec = 30.0

[[steps]]
name = "document"
[steps.agent]
timeout_sec = 60.0
[steps.verifier]
timeout_sec = 30.0

ステップごとに、次の設定を上書きできます。agent.timeout_sec、agent.user、agent.network_mode、verifier.timeout_sec、verifier.env、verifier.user、verifier.network_mode、verifier.environment_mode、verifier.environment、steps.verifier.environment.network_mode、healthcheck.*、artifacts。未設定のフィールドはタスクレベルの値にフォールバックします。

報酬戦略の選択

• "mean" — すべてのステップのシグナルを集計します。継続的な進捗に対する報酬に適しています。
• "final" — 最後のステップの verifier_result が試行の報酬になります。最終ステップが、タスク全体をすでに表す辞書を返すエンドツーエンドチェックである場合に適しています。ただし、min_reward によって早期中断が発生した場合、"final" が使用するのは意図した最終ステップの結果ではなく、中断されたステップの結果です。

成果物

ステップレベルの artifacts は、そのステップの検証後に steps/{name}/artifacts/ に収集されます。タスクレベルおよび試行レベルの成果物は、ステップレベルの成果物に加えて、すべてのステップで収集されます。

Oracle による検証

harbor run -p "<task-path>" -a oracle は、各ステップの solution/solve.sh を実行し、その後、各ステップの検証器を順番に実行します。集計戦略にかかわらず、試行の報酬は 1.0 になるはずです。

完全なリファレンスと実例

• ドキュメント：docs-mintlify/tasks/multi-step.mdx
• タスク例：examples/tasks/hello-multi-step-advanced/

特別な機能（該当する場合に記載）

• ネットワークポリシー：[environment]／[verifier.environment] でベースラインを設定し、フェーズごとのオーバーライドは [agent]／[verifier] で設定します。ステップ 6 の ネットワークポリシー を参照してください
• MCP サーバー：エージェントのツールを追加するには、task.toml に [[environment.mcp_servers]] を追加します
• ヘルスチェック：起動準備が必要なサービスには、[environment.healthcheck] を追加します
• GPU：environment.gpus を設定し、必要に応じて environment.gpu_types を設定します
• ビルド済みイメージ：Dockerfile からビルドする代わりに environment.docker_image を設定します。environment/Dockerfile は省略でき、実行時ファイル（設定ファイル、スクリプト、データ）を environment/ 直下に配置できます。環境の起動時に、Harbor がそれらをコンテナの作業ディレクトリにアップロードします。
• 非 root ユーザー：分離するには agent.user／verifier.user を設定します

よくある落とし穴

• 報酬ファイルを書き忘れる → タスクは報酬 0 でひっそりと「合格」します
• test.sh で相対パスを使用する → Harbor が別の cwd から実行すると動作しません
• Dockerfile に解決策をインストールする → エージェントに答えが知られてしまいます
• テストスクリプトが instruction.md に漏れる → エージェントに評価基準が見え、攻略が簡単になります
• chmod +x solution/solve.sh を忘れる → Oracle エージェントが失敗します
• task.toml に keywords = [] を残す → タスクがレジストリ検索に表示されません
• README.md をひな形のままにする → チームメイトがタスクの概要をすぐに把握できません
• 環境の起動時に適用されることを期待して [agent] に network_mode を指定する → ベースラインには [environment].network_mode を使用します。agent／verifier のフィールドはフェーズごとのオーバーライドです
• Docker でフェーズのオーバーライドがベースラインと異なる → プロバイダーが dynamic_network_policy に対応していない限り、タスクは拒否されます。別の verifier 環境を使用するか、ベースラインと一致させてください