add-your-agent

Veris Bench にエージェントを追加する

このリポジトリのエージェントを Veris Bench のベンチに Your image 候補として登録し、スモーク試行で動作を確認します。

エージェントは変更しません。 エージェントの隣にサーバーファイル、Dockerfile、候補ファイルを追加します。他に方法がない場合に限り、エージェント自体のコードを変更し、レポートでその旨を伝えてください。

completed になったスモーク試行だけでは、統合が機能している証明にはなりません。データベースへの呼び出しがすべて失敗するエージェントや、グレーダーから見えないモデル呼び出しを行うエージェントでも、試行は完了します。確認事項はステップ 9 を参照してください。

ステップ 1 の前に reference/api.md を、ステップ 2 の前に reference/image.md を読んでください。

入力

変更を加える前に、以下を収集してください。不足している情報があればユーザーに尋ねてください。

入力	入手先
VERIS_API_KEY	環境変数。vbk_ で始まります。発行できるのは人だけです。コンソールの Overview、API keys、Issue から発行します。絶対に表示したり、ファイルに書き込んだりしないでください。
BENCH_API	デフォルトは https://bench.api.veris.ai/v1 です。ユーザーから指定があった場合に限り、別の値を使用してください。
BENCH_ID	ユーザーが指定した場合は、スキルの引数を使用します。それ以外の場合はユーザーに尋ねるか、ユーザーのベンチ一覧を表示して選んでもらってください。
レジストリ	Docker でプッシュできるリポジトリプレフィックス。例：ghcr.io/<org>
モデルキー	エージェントが読み取るシークレット。例：OPENAI_API_KEY。ベンチに設定し、イメージやリポジトリには含めないでください。環境にすでに存在する場合を除き、不足しているキーはユーザーがコンソールで追加します。

手順

1. アクセス権を確認します。 ベンチを読み取ります。access は write である必要があります。read の場合は作業を中止し、その理由をユーザーに伝えてください（reference/api.md の「Access」を参照）。
2. エージェントを編集せずに読みます。 次の点を書き留めます。言語とエントリーポイント、会話の 1 ターンを実行する関数と履歴の保持方法、モデル SDK とそのインストール済みバージョン、呼び出すすべての外部サービスと各アドレスまたは DSN の取得元（変数、設定ファイル、またはリテラル）、読み取るすべてのシークレット、相対パスで開くファイル。今の時点で、SDK が reference/image.md の「Telemetry」に記載された要件を満たすか確認してください。未対応のバージョンではモデル呼び出しが記録されず、何も情報が得られません。
3. ベンチの環境を確認します。 サービスを一覧表示します（reference/api.md の「World」を参照）。エージェントが呼び出すすべてのサービスに対応するツインを確認します。ツインがないサービスをエージェントが呼び出す場合は、そのことをユーザーに伝えてください。Veris がベンチのゲートウェイを有効にしていない限り、呼び出しは実際のベンダーに到達します。
4. サーバーファイルを追加します。 reference/image.md のパターンを使って bench_server.py または bench_server.mjs を作成します。エージェントのターン関数をラップし、セッション ID ごとに会話を 1 つ保持して、/health を提供し、0.0.0.0:8008 でリッスンするようにします。http を使用してください。エージェントがすでに WebSocket を使用している場合に限り、ws を使用してください。
5. サーバーファイル内で、エージェントの接続先をツインに設定します。 エージェントのモジュールを読み込む前に、各ツインのアドレスを VERIS_DS_SERVICE_URLS からコピーし、エージェントがすでに読み取る設定に代入してください。reference/image.md の「Twins」にあるクライアント修正を適用してください。
6. Dockerfile と .dockerignore を作成します。 reference/image.md に従ってください。リポジトリに Dockerfile がある場合は、サーバーを実行できるなら再利用してください。
7. ローカルで確認します。 linux/amd64 向けにビルドして実行し、/health と 1 ターンを送信します（reference/image.md の「Local check」を参照）。プッシュする前に、ここで失敗した問題をすべて修正してください。
8. プッシュして登録します。 プッシュし、ダイジェストで固定して、check-image を実行します。必要に応じてレジストリへのログイン情報を保存し、各シークレットがベンチの candidate-env に含まれていることを確認して、bench/candidate.json を作成し、候補を登録します（reference/api.md を参照）。
9. スモーク試行を実行して検証します。 エージェントのツールを必要とするタスクを 2 つ、ペルソナなし、繰り返しは 1 回に設定します。保留中の処理がなくなったら、以下の表に従ってすべての試行を確認してください。不合格の行はそれぞれ統合の不具合です。成果物を調べて原因を特定し、修正して新しいダイジェストをプッシュし、候補を更新したうえで、保留中の処理がなくなったら同じ試行内で再実行し、もう一度確認してください。
10. レポートします（以下の形式に従ってください）。

すべてのスモークテストで、次の項目を満たせば完了です

チェック項目	確認場所（reference/api.md、「Verify」）	失敗した場合
実行された	status が completed になっている	error の末尾を確認してください。コンテナの最後のログ行が記録されています。
エージェントが応答した	turns が 2 以上で、トランスクリプトにエージェントの応答がある	パスまたはフィールドのマッピングが間違っているか、ターン中にサーバーがクラッシュしています。candidate.log と transcript.jsonl を確認してください。
グレーダーがモデル呼び出しを認識している	agent_trace_reason が null で、agent_trace.json の llm_calls が 0 より大きい	reference/image.md の「Telemetry」を参照してください。agent_trace_reason だけでは不十分です。トレースにモデル呼び出しがない場合も null になります。judge_disabled_trace は、ベンチのグレーダーがトレースを読み取らないことを意味します。バグではないため、このチェックは省略してください。
エージェントがツールを使用した	エージェントにツールがある場合、tool_calls が 0 より大きく、agent_trace.json のツール結果がエラーではない	接続または証明書に関するエラーがツールから返された場合はステップ 5 に進みます。reference/image.md の「Twins」を参照してください。
ツインに到達した	エージェントが使用する各ツインが、エージェントから少なくとも 1 件のリクエストを受け取っている（Verify コマンドの reached）	エージェントの接続先が、引き続き自身のデフォルトアドレスになっています。ステップ 5 をやり直してください。この確認には ledger_summary の件数を使わないでください。プラットフォームが行うリクエストも含まれます。

passed はこの一覧に含まれていません。エージェントがタスクに合格するかどうかは、統合ではなくエージェントの性能を測るものです。2 回の試行では品質はほとんどわかりません。全試験を実行してください。

成功したように見える落とし穴

症状	原因	修正方法
Node エージェント：すべてのデータベースツールが失敗し、ログに pg の SSL 警告がある	node-postgres は、ツインの DSN にある sslmode=require を verify-full として扱います。また、ツインの証明書は自己署名です	サーバーファイルの DSN に uselibpqcompat=true を追加します
Node エージェント：agent_trace_reason が no_spans_received になっている	トレースフックが作業ディレクトリに書き込もうとしていますが、実行ユーザーに書き込み権限がありません	アプリディレクトリの所有者を実行ユーザーに変更します（chown）
Node エージェント：llm_calls が 0 で、candidate.log に veris-otel-node: instrumented OpenAI の行がない	openai パッケージのバージョンが 5 未満です	openai を 5 以降にアップグレードし、イメージのビルド時にインストールされるようロックファイルを更新します
試行が 1 分以内に失敗し、exec format error または pull エラーが表示される	Apple Silicon 上でビルドされた arm64 イメージか、ベンチがイメージを pull できません	--platform linux/amd64 を指定し、check-image を実行します
エージェントの応答が空	image.path または応答フィールドがサーバーと一致していません	bench/candidate.json をサーバーに合わせます
ベンチでのみツールが失敗する	アドレスが直接指定されているか、ベンチが設定しない変数を使用しています	ステップ 5

ユーザーへの報告

• 追加または変更したファイルを 1 行ずつ記載します。
• イメージ参照、候補 ID、試行 ID、およびコンソールリンク https://benchmark.veris.ai/benchmarks/<bench id>?trial=<trial id> を記載します。
• スモークテストごとに、5 つのチェック項目と passed の結果を記載します。
• エージェント自身のコードや依存関係を変更した場合は、その変更内容と理由を記載します。
• 最初のスモークテスト後に行ったすべての修正と、その理由を記載します。
• 次に、https://docs.veris.ai/run-a-trial の手順に従って全試験を実行します。新しいバージョンの場合は、同じ試行内で新しい候補を作成します。