agent-integration

このエージェントリポジトリをゼロから Veris と統合します。

このスキルでは、リポジトリを「通常の顧客エージェントのソース」から「Veris に対応し、プッシュ可能な状態」にします。ユーザーがエージェントリポジトリのパスを指定した場合は、それをリポジトリのルートとして使用します。指定がない場合は、現在の作業ディレクトリを使用します。

既存の .veris/ ファイルや古いスキャフォールドの出力は、あくまで出発点として扱います。このスキルに現在同梱されているリファレンスを、生成する内容の唯一の基準としてください。

基本方針：エージェントは一定で、Veris はテストハーネスです

Veris は、現実的な条件下でエージェントをテストするためのものです。テスト対象はエージェントであり、Veris はその周囲のハーネスです。この非対称性が、このスキルにおけるあらゆる判断の基準になります。

• エージェントは本番環境と同じ方法で Veris 上でも動作します。 エージェントが本番環境で Slack Web API と HTTP 通信するなら、シミュレーション環境でも Veris の Slack モックと HTTP 通信します。本番環境で CLI を実行するなら、シミュレーション環境でも CLI を実行します。シミュレーション専用のコードパスは設けません。
• 統合作業はすべて .veris/ に置きます。 .veris/veris.yaml、.veris/Dockerfile.sandbox、.veris/config.yaml、.veris/.dockerignore はデプロイ記述子であり、このエージェント向けの Helm チャートや docker-compose.yaml に相当します。これらは、この環境でエージェントを起動する方法を記述するものです。エージェントに属する動作を含めてはいけません。
• エージェントを Veris に「適合させる」ラッパー、シム、グルーコードは作成しないでください。 CLI エージェントをラップして呼び出し可能にする Python ファイル、Veris のアクターフォーマットをエージェント固有のフォーマットに変換するスクリプト、Veris 固有のパラメーターを受け入れるようパッチを当てたエージェントなどは、すべて不適切です。そうした方法では、テスト対象がエージェントではなくなります。
• Veris で動作させるために、エージェントのソースコードを変更しないでください。 エージェントが Veris ではそのまま満たせない条件を前提としている場合、それは記録すべき Veris プラットフォームの不足か、本番環境でも問題になるエージェントの実際の不具合です。どちらの場合も、エージェントのソースコードを変更して解決してはいけません。
• ラッパーが必要だと感じたら、作業を止めて課題として扱ってください。 エージェントが本番環境で実際にどのように統合されているかを確認します。本番環境に HTTP サーバーがあるなら、それを使用してください。本番環境では CLI 専用で、Veris のアクターが CLI を操作できないなら、エスカレーションしてください。それは Veris の機能不足であり、グルーコードを作る許可ではありません。
• 純粋な設定ではない .veris/ ファイルとして認められるのは、複数のプロセス（エージェントとデータベースなど）をまとめるコンテナオーケストレーション用の start.sh だけです。 これも、提供された状態のエージェントを起動して実行するだけであり、動作を変えてはいけません。

迷った場合は、エージェントの作者が .veris/ を読んで、「これは Veris 用のデプロイ設定だ」と認識できるべきであり、「誰かがエージェントをフォークしてパッチを当てた」と感じるものであってはいけません。

トランスポートブリッジは明示的な例外です

トランスポートブリッジは、アクターのチャネル形式（例：voice_ws PCM16）とエージェントフレームワーク固有のトランスポート（例：LiveKit WebRTC、SIP メディア、独自のメッセージエンベロープ）の間を変換しながら、基盤となるペイロードのバイト列をそのまま保持します。これはラッパーではありません。同様の構成は、モバイルクライアント、キオスク、IVR ベンダーなど、エージェントの他の製品サーフェスでも本番環境で使われているため、このブリッジは Veris 固有の接着コードではなく、実際の製品コードです。

次の場合、ブリッジが認められます。

• エージェントのフレームワークを再設定して、アクターのチャネル形式を直接扱えるようにできない場合（例：LiveKit Agents はエンドツーエンドで WebRTC を使用し、raw-PCM16-WS トランスポートを備えていません）。
• ブリッジが純粋なトランスポート変換である場合。入出力の音声バイト列／JSON ペイロードは同一で、意味上の再構成を行いません。（音声の場合、エージェントのモデルが受け取る音声バイト列は、アクターが送信したものと同一である必要があります。テキストの場合、エージェントが認識するメッセージペイロードは、アクターが送信したものと同一である必要があります。）
• ブリッジがエージェントのリポジトリ内の本番コード（例：app/bridge.py）として配置され、エージェント独自のテストで検証されている場合。.veris/内には置きません。これはエージェントの WebRTC 上の voice_ws 製品サーフェスであり、Veris はその利用者の1つにすぎません。

次の場合、ブリッジは認められません。

• エージェントが認識するコンテンツを再構成する場合：メッセージの書き換え、ツール呼び出し JSON の再構成、STT 出力の正規化、Veris 固有のアクターフィールドからエージェント固有のパラメーターへの変換などです。これはラッパーであり、上記のラッパー禁止ルールが適用されます。
• フレームワークを設定してアクターのチャネルを扱える場合（voice_ws用の Pipecat と RawAudioFrameSerializer、http用のフレームワーク独自の HTTP プラグインなど）。まずフレームワークを設定し、トランスポートが固定されている場合に限ってブリッジを使用してください。

簡単な判断基準：「同じバイト列でネットワーク形式が異なる」＝トランスポートブリッジ（許可）。「バイト列が異なる／形式が異なる」＝ラッパー（禁止）。

アーキテクチャについてはreference/infrastructure-patterns.md Pattern 9を、音声に特化した適用例についてはreference/voice-channels.mdを参照してください。

クライアントツール呼び出しを採点システムに報告することは、認められた例外です（音声エージェントのみ）

これは「Veris 固有のコードパスを設けない」というルールを実際に破る唯一の例外であり、意図的に設けられています。対象となるのは、ホスト型の音声対音声プラットフォーム（ElevenLabs Conversational AI、OpenAI Realtime、Gemini Live、Vapi など）上に構築された音声エージェントのみです。これらのエージェントのツールは、ベンダーの WebSocket 経由で往復するクライアントツールとして、またはプラットフォームから HTTP 経由でエージェントの Webhook に POST される、Vapi 方式のサーバーツールとして、エージェントプロセス内で実行されます。いずれの場合も、呼び出しは音声文字起こしには反映されません。

必要な理由：音声採点システムは、音声文字起こしと、エージェントが報告したツール呼び出しイベントからトレースを作成します。クライアントツールの呼び出しは音声文字起こしに反映されないため、報告がなければ採点システムはツールが実行されたことを確認できず、実際に行われた操作（カードの凍結や再発行など）を幻覚として誤判定します。テキスト／HTTP エージェントにはこの問題はありません。ツール呼び出しは自動的に記録されるため、この例外は音声エージェントのみに適用されます。

対処方法：各ツールの実行後、エージェントは agent_tool_call イベントをサンドボックスエンジンに POST し、プラットフォームがそれを採点対象のトレースに反映します。これは計測の範囲にとどめ、ラッパーにならないよう、厳密に最小限にしてください。

• シミュレーション外では何もしない。 SIMULATION_ID の有無で判定します（本番環境では未設定なので、すぐに戻ります）。本番環境の動作は変わりません。
• 結果を待たず、失敗しても処理を継続する。 タイムアウトを短く設定し、エラーを握りつぶして警告をログに記録します。報告に失敗しても、呼び出しを中断したり、エージェントの出力を変更したりしてはいけません。
• 観測に徹し、形を変えない。 実際のツール実行後に、実際の名前、引数、結果をそのまま渡して報告します。何が起きたかを記録するものであり、エージェントの動作やモデルが受け取る情報に変更を加えるものではありません。

この例外が認められるのは、クライアントツールを採点システムから確認できるようにする目的に限られ、音声エージェントに限られ、かつこの最小限の形式に限られます。汎用的なシムを作成してよいという意味ではありません。エンドポイント、イベントスキーマ、コピーして使えるフックの詳細は、reference/voice-channels.md を参照してください。

基本ルール

• 各主要な手順の前に、これから何を行うか説明してください。
• 実際にトレードオフのある判断を提示し、ユーザーに選んでもらってください。
• 依存関係を分類するときや、エージェントの統合方法を決めるときは、リポジトリ内の具体的な根拠を示してください。
• 古い Veris 設定を黙って残さないでください。現在推奨されている形式に移行してください。
• .env.simulation を生成しないでください。現在のランタイムフローは agent.environment と veris env vars set です。
• 現在の actor.channels スキーマと正式なサービス名を優先してください。ユーザーから互換性を明示的に求められない限り、古い persona.modality、email_address、旧サービス別名を生成しないでください。
• Veris とエージェントの間を変換する Python ラッパー、シェルシム、その他の「アダプター」コードを書かないでください。エージェントが本番環境で使用する実際のインターフェースを使ってください。それがそのままでは利用できない場合は、ラッパーを作成するのではなく、プラットフォームの課題として提示してください。
• 外部への操作や取り消せない操作の前に確認してください。
  • veris-cli のインストール
  • veris login の実行
  • veris env create の実行
  • veris env vars set による環境変数の設定
  • veris env push によるプッシュ

迅速実行モード

ユーザーが「最後まで進めて」「全部やって」などと言って全フローを事前承認した場合：

• 中間チェックポイント（Phase 2、Phase 3、Phase 4 の終了時）を省略します。
• 判断を行う際には、その場で引き続き説明し、ユーザーが進行状況を把握できるようにします。
• 取り消せない操作や外部への操作の前には、引き続き停止して確認します。対象は veris env create、veris env push、実際のシークレットを指定した veris env vars set です。
• 明確でないトレードオフが実際にある判断（たとえば、重いサービスをバンドルするか外部化するか）では、迅速実行モードでも一時停止して確認します。
• 最後に、行ったすべての判断をまとめて提示します。

必要に応じてこれらのファイルを確認してください

• 現在のサービス名と検出方法については、reference/service-mapping.md を参照してください
• 環境変数の上書きとモック認証情報については、reference/env-var-overrides.md を参照してください
• バンドル可能なローカルインフラについては、reference/bundling-recipes.md を参照してください
• コンテナの再構成パターンについては、reference/infrastructure-patterns.md を参照してください
• 音声エージェント（voice_ws チャネル、フレームワークの選択、末尾の無音、評価者が確認できるようにクライアントツールの呼び出しを報告する方法）については、reference/voice-channels.md を参照してください
• 現在の veris.yaml の構造については、reference/veris-yaml-schema.md を参照してください
• 生成された設定の例については、templates/veris-yaml.md を参照してください
• Dockerfile のパターンについては、templates/dockerfile-sandbox.md を参照してください
• 実行時の環境変数の処理については、templates/env-vars.md を参照してください
• 複数プロセスの起動スクリプトについては、templates/start-sh.md を参照してください
• インテグレーションの失敗については、phases/troubleshooting.md を参照してください

ワークフローの概要

フェーズ	目標
0	Veris ツールと環境を初期設定する
1	リポジトリと現在の実行環境を調査する
2	依存関係とサービス戦略を分析する
3	インテグレーションモードとコンテナアーキテクチャを選択する
4	.veris/veris.yaml を生成する
5	.veris/Dockerfile.sandbox と補助ファイルを生成する
6	実行時の環境変数を設定し、検証してプッシュする
7	1 つのシナリオとシミュレーションでスモーク検証する

---

フェーズ 0：Veris ツールと環境の初期設定

[Phase 0/7]

ユーザーに次のように伝えてください。「残りのインテグレーション作業に必要な Veris ツールと環境設定が、このリポジトリにあることを確認します。」

0.1 リポジトリのルートを確認する

そのディレクトリが親フォルダーではなく、エージェントのリポジトリであることを確認してください。ソースコード、依存関係マニフェスト、アプリケーションのエントリーポイントを探します。

0.2 veris-cli を確認する

veris がインストールされ、動作することを確認してください。

インストールされていない場合：

• uv tool install veris-cli を優先します
• 代替手段として pip install veris-cli を使用します

どのインストール方法を使用するか、その理由とともに説明してください。

0.3 Veris の認証を確認する

ユーザーがすでにログインしているか、またどのプロファイル／バックエンドを使用しているかを確認してください。

認証されていない場合：

• ブラウザー認証には veris login を推奨します
• API キーによるログインは、ユーザーが明示的に希望する場合に限り使用します

認証が完了するまで、veris env push に進まないでください。

0.4 .veris/ を確認または作成する

次のファイルを確認します：

• .veris/config.yaml
• .veris/veris.yaml
• .veris/Dockerfile.sandbox
• .veris/.dockerignore

.veris/ が存在しない場合、または存在していても環境との紐付けがない場合：

1. リポジトリのディレクトリ名から環境名の候補を導き出します。
2. 提案する名前をユーザーに提示します。
3. 承認を得たら、veris env create --self-serve --name "<name>" を実行します。

--self-serve（veris-cli >= 2.27.0）は、このスキルの対象ユーザーに適したモードです。.veris/ はユーザー自身が作成するため、環境はすぐに veris env push を実行できる状態である必要があります。このオプションを指定しない場合、env create はデフォルトでマネージドセットアップモードになり、Veris チームが顧客向けに Dockerfile.sandbox と veris.yaml を生成します。そのセットアップが完了するまでは、veris env push は 409: Run veris env submit first を返します。veris env create --help に --self-serve が表示されない場合は、veris を管理しているインストールマネージャーを使って CLI を更新してください（uv tool upgrade veris-cli または pip install -U veris-cli）。すでに --self-serve なしで環境を作成してしまった場合の復旧方法については、phases/troubleshooting.md を参照してください。

veris env create で作成されるものを説明してください：

• .veris/veris.yaml — Veris シミュレーション設定
• .veris/Dockerfile.sandbox — イメージのビルド定義
• .veris/.dockerignore — ビルドコンテキストからの除外設定
• .veris/config.yaml — このリポジトリの環境との紐付け

0.5 スキャフォールディングは正確な情報ではなく、プレースホルダーとして扱う

生成された .veris/ ファイルは、あくまで出発点にすぎません。古いデフォルト設定や汎用プレースホルダーが使われている場合があります。このリポジトリに適した正しい統合に置き換える責任は、あなたにあります。

そのままフェーズ 1 に進んでください。

---

フェーズ 1：リポジトリと現在のランタイムを調査する

[フェーズ 1/7]

ユーザーに次のように伝えてください：「このリポジトリの現在の実行方法、依存関係、ユーザーとのやり取りの方法を調査します。」

1.1 既存の Veris の状態

.veris/ がすでに存在する場合は、既存の Veris ファイルをすべて最初に読みます。古くなっている、またはレガシーに見えるものがあれば指摘してください。

• persona.modality
• email_address
• crm、calendar、oracle などの古いサービス名
• .veris/config.yaml の環境変数バインディングがない
• 現在のドキュメントと矛盾する前提

1.2 インフラストラクチャファイル

次のいずれかを読み、要約してください。

• docker-compose.yml、docker-compose.yaml、compose.yml
• Dockerfile、Dockerfile.*
• Procfile
• supervisord.conf、supervisord.ini
• vercel.json、serverless.yml、netlify.toml
• Kubernetes マニフェスト

次を特定してください。

• ユーザー向けエージェントとなるプロセス
• ほかに存在するサービス
• 現在のシステムの起動方法

1.3 環境変数とシークレット

次を読みます。

• .env.example、.env.sample、.env.template
• 設定／セッティングモジュール
• シークレットまたはボールトへの参照

エージェントが読み取る環境変数をすべて収集し、次のどれに該当するかを記録してください。

• 安定した非シークレット
• シークレット
• サービスエンドポイント
• オプションまたはデバッグ専用

1.4 依存関係

リポジトリの言語／ランタイムに対応するパッケージマニフェストを読み、次を特定してください。

• パッケージマネージャー
• フレームワーク
• Python／Node のランタイムに関する前提
• 外部サービス用 SDK

1.5 ソースコードのエントリーポイント

ユーザーからの作業を処理する実際のコードパスを探してください。

• アプリ／サーバーのエントリーポイント
• チャット／メッセージハンドラー
• 設定／セッティングモジュール
• リクエストのルーティング
• ユーザーとの会話中に関係するバックグラウンドワーカーまたはウェブフックリスナー

1.5a プラットフォームホスト型エージェント（設定のみのリポジトリ）

リポジトリに従来型のアプリケーションエントリーポイント（main.py、app.py、server.js、index.ts）がない場合は、プラットフォームホスト型エージェントかどうかを確認してください。これは、インストール済みのフレームワーク（CrewAI、LangServe、AutoGen、Dify、n8n、Flowise など）上で動作する設定ファイルのリポジトリです。

該当する兆候：

• 主なファイルが YAML／JSON 設定、プロンプトテンプレート、ツール定義である
• pyproject.toml または package.json に、主要な依存関係としてフレームワークが記載されている
• 小規模なツール／フックファイル以外に、実質的なアプリケーションロジックがない
• README の手順に「[フレームワーク] をインストールしてから、[フレームワークのコマンド] を実行する」と記載されている

該当する場合：

• フレームワークがランタイムです。ソースからビルドするのではなく、Dockerfile にインストールします
• エントリーポイントはフレームワークの CLI またはサーバーコマンドです
• 再構成の全手順については、reference/infrastructure-patterns.md のパターン 8 を参照してください
• これらのリポジトリで pip install . を試すと、ソースツリーのコンパイルエラーが発生する場合があるため注意してください

1.6 統合インターフェースを特定する

これは重要です。シミュレートするアクターがエージェントとどのように通信するべきかを特定してください。

次の4種類のインターフェースを確認してください。

HTTP

• チャットエンドポイント
• リクエスト／レスポンスのボディ形式
• セッションまたは会話のフィールド
• JSON または SSE のレスポンス形式

WebSocket

• WS ルート
• メッセージのフレーミング
• セッションの処理

メール

• 受信トレイのアドレス
• ポーリングまたは Webhook のフロー

関数

• エージェントが公開 API の一部としてすでに公開している、クリーンな Python 呼び出し可能関数
• エージェント自身のドキュメントでエントリーポイントとして扱われている、既存の handle_message 形式の関数

CLI やサーバーをラップして関数インターフェースを作り出してはいけません。本番環境のエージェントが CLI のみで動作する場合、統合は CLI 主導です。その点を明示し、適切な Veris チャネルを探すか、プラットフォームの課題として記録してください。関数チャネルが適切なのは、リポジトリに呼び出し可能関数が主要なインターフェースまたはドキュメントに記載されたインターフェースとしてすでに含まれている場合だけです。

ネットワークモードと関数モードの両方が使える場合は、リポジトリの実際の製品インターフェースを使用してください。本番環境で動くのはそのインターフェースであり、テストするのもそのインターフェースです。

見つかった内容をユーザーに正確に伝え、続行する前に最適と思われる統合方法を確認してください。

フェーズ 2 に進みます。

---

フェーズ 2：依存関係とサービス戦略の分析

[Phase 2/7]

ユーザーに次のように伝えてください。「各依存関係を、モック、バンドル、外部、またはスキップに分類しています。」

次を読みます。

• reference/service-mapping.md
• reference/env-var-overrides.md
• reference/bundling-recipes.md

依存関係ごとに、次のいずれかに分類します。

1. Veris でモックする
2. コンテナ内にバンドルする
3. 外部エンドポイントを使用する
4. 完全にスキップする
5. 要相談
6. 実際の外部通信を許可する — エージェントが実際のインターネットに接続する必要があります（例：ウェブ検索、URL スクレイピング、モックのないライブ API）。シミュレーションの実行ごとに結果が不確定になります。

分類ルール

• 判断する前に、必ずソースコードを読みます。サービス名だけから重要性を推測してはいけません。
• スキップ可能と判断した場合は、根拠を示します。
• 重要な場合は、特に Elasticsearch や LocalStack のような大規模サービスについて、バンドルのコストを明示します。
• 依存関係を Veris に適切に対応付けられる場合は、モックサービスを優先します。
• 可能な限り、コードの変更より環境変数によるオーバーライドを優先します。

特殊なケース

Postgres

• Veris の postgres を使うか、外部 DB を使うかを決定します。
• Veris の postgres を使う場合は、スキーマのアーティファクトまたはマイグレーションソースを見つけ、最適なコピー方法を判断します。

LLM プロバイダー

• Veris サービスのエントリーは必要ありません。
• LLM プロキシが対応ドメインを自動的にインターセプトします。

メール

• アクターがメールチャネルを使用する場合、Veris のメールサービスが自動的に注入されることを伝えます。

認証ヘルパー

• Google／Microsoft／Atlassian／Intuit の認証ヘルパーはプラットフォームレベルのヘルパーであり、通常は手動でサービスとして追加する必要はありません。

ウェブ検索とスクレイピング

• エージェントが検索 API（Google、Bing、SerpAPI、Tavily、Brave Search、DuckDuckGo）を呼び出す場合、またはライブ URL を取得する場合、これらはモックできません。
• 「実際の外部通信を許可する」に分類します。
• ユーザーに警告します。ライブインターネットへの呼び出しにより、シミュレーション結果は不確定になります。同じシナリオでも、実行ごとに異なる出力が生成される可能性があります。
• 検索が本当に任意の機能である場合（例：ナレッジベースに回答がないときのフォールバック）、シミュレーションの結果を決定的にするため、環境変数で無効にすることを検討します。

実際のインターネットへの外部通信（一般）

• Veris でモックできない任意の外部エンドポイントへの接続が必要なエージェントもあります（サードパーティサービスへの Webhook、リアルタイムのデータフィード、Veris サービスのないパブリック REST API など）。
• これらも「実際の外部通信を許可する」に分類します。
• Veris コンテナでは、インターセプトされないドメインへのアウトバウンドインターネット接続がデフォルトで許可されています。
• 結果が不確定になるというトレードオフをユーザーに明示します。

チェックポイント

次に進む前に、依存関係の分析内容をユーザーと確認してください。ユーザーが以下を理解している必要があります。

• 何をモックするか
• 何をバンドルするか
• 何を外部に残すか
• 何をスキップするか
• 何について引き続き判断が必要か

承認を待ってから進めてください。

---

フェーズ 3：統合モードとコンテナアーキテクチャを選択する

[Phase 3/7]

ユーザーに次のように伝えてください。「このエージェントを Veris コンテナ内でどのように実行するか、またアクターがどのように通信するかを決めています。」

reference/infrastructure-patterns.md を読んでください。

3.1 チャネル戦略を選択する

以下から 1 つ選択してください。

• HTTP — 製品がすでに HTTP チャット API を提供している場合に推奨
• WebSocket — リアルタイムのステートフルなメッセージングが中核の場合に推奨
• Email — 製品が実際にメールを中心としている場合に推奨
• Function — リポジトリに明確な呼び出し可能なパスがある場合、または単発のリクエスト／レスポンス型エージェントとして扱う場合に推奨

3.2 Function チャネルのルール

Function チャネルを選択する場合：

• 呼び出し可能なパスは、エージェントのリポジトリがすでに公開インターフェースとして提供している必要があります（ドキュメントに記載されている、README で参照されている、またはその他の形で契約の一部となっていること）。
• CLI やサーバーから呼び出し可能なものを作り出すためにラッパーファイルを作成しないでください。リポジトリがすでに呼び出し可能なパスを公開していない場合、Function は不適切なチャネルです。
• veris.yaml では agent.entry_point と agent.port を省略してください。
• 呼び出しが単発かつステートレスの場合、actor.config.MAX_TURNS: 1 を設定してください。

3.3 ネットワークチャネルのルール

HTTP／WS／email を選択する場合：

• 正確なリクエストとレスポンスのマッピングを特定してください。
• 起動コマンドを特定してください。
• 予約されていないポートを選択してください。
• バンドルするインフラや複数のプロセスのために start.sh が必要かどうか判断してください。

3.4 コンテナのレイアウト

以下を判断してください。

• /agent にコピーするもの
• イメージに含めないファイル
• 複数のプロセスをバンドルするために start.sh が必要かどうか（これはコンテナのオーケストレーションであり、エージェントの変更ではありません）

「必要なコード変更は何か」を計画しないでください。エージェントのコード変更はゼロが目標です。環境変数の上書きだけでは不十分で、エージェントを出荷時の状態で実行できない場合は、それを調査結果として報告し、ソースを修正するのではなくエスカレーションしてください。

チェックポイント

以下を説明してください。

• アクターがエージェントとどのように通信するか（エージェントの実際の本番インターフェースを使用）
• エージェントがコンテナ内でどのように起動するか（実際の本番起動コマンドを使用）
• コピーするファイル

エージェント側のコード変更が少しでも必要だと考える場合は、ここでその旨を示して停止してください。既定の答えは、コード変更ゼロです。変更なしでは先に進められない場合、統合手順の問題ではなく、Veris プラットフォームの不足である可能性があります。

事前承認済みの唯一の例外は、クライアントツール型音声エージェント（ElevenLabs Conversational AI、OpenAI Realtime、Gemini Live など）です。評価者がエージェントのツールを確認できるようにするには、agent_tool_call 報告フックが必要です。Core framing exception および reference/voice-channels.md を参照してください。これは想定された変更なので、エスカレーションせずに追加してください。それ以外は、すべてここで停止してください。

承認を待ってから進めてください。

---

フェーズ 4：.veris/veris.yaml を生成する

[Phase 4/7]

ユーザーに次のように伝えてください。「現在推奨されているスキーマで、最終的な Veris 設定を生成しています。」

以下を読んでください。

• reference/veris-yaml-schema.md
• templates/veris-yaml.md

ルール

• persona.modality ではなく、actor.channels を使用します
• reference/service-mapping.md に記載されている正式なサービス名を使用します
• email_address ではなく、agent_inbox を使用します
• 具体的な理由がある場合に限り、actor.config.MAX_TURNS を設定します。通常は、単発関数の統合で使用します
• ユーザーから高度な調整を明示的に求められない限り、*_INTERVAL の設定項目は追加しないでください
• シークレットを veris.yaml に記載しないでください
• 安定した非シークレットのデフォルト値は agent.environment に設定します
• 展開や組み合わせが必要な場合に限り、agent.environment で ${VAR} を使用します。エージェントが実行時環境変数を直接読み取れる場合は、veris env vars set で設定することを優先します

チャネル固有のルール

HTTP / WS / Email

• agent.code_path を含めます
• agent.entry_point を含めます
• agent.port を含めます

Function

• agent.code_path を含めます
• agent.entry_point は省略します
• agent.port は省略します
• actor.channels[0].type: function を設定します
• callable: ... を設定します

チェックポイント

veris.yaml の全体を提示し、各セクションを説明したうえで、作成または最終確定する前に承認を得てください。

---

フェーズ 5：.veris/Dockerfile.sandbox と補助ファイルを生成する

[フェーズ 5/7]

ユーザーに「この統合に必要なイメージのビルド設定と補助ファイルを生成しています。」と伝えます。

次を読みます：

• templates/dockerfile-sandbox.md
• templates/start-sh.md

5.1 Dockerfile のルール

• 次の内容から始めます：

ARG GVISOR_BASE
FROM ${GVISOR_BASE}

• ビルドコンテキストはリポジトリのルートです
• ソースコードの前に依存関係のマニフェストをコピーします
• エージェントが実際に必要とするものだけをコピーします
• WORKDIR /app で終わります
• veris.yaml をイメージに組み込まないでください

5.2 実行時の注意事項

• 現在のベースイメージには、Python、uv、Node.js がすでに含まれています
• リポジトリで本当に必要な場合に限り、追加のランタイムやシステムパッケージをインストールします
• Function チャネルを使用する場合も、エージェントのコードと依存関係は通常どおりパッケージします。ただし、ネットワークサーバーは起動しません

5.3 補助ファイル

必要なものだけを作成します：

• 複数のプロセス（例：エージェントと併せてデータベース）をまとめるための start.sh — これはコンテナオーケストレーションであり、docker-compose.yaml を使用する場合と同じです
• リポジトリにデフォルトの除外ファイルでは対象にならない大きなディレクトリがある場合の .veris/.dockerignore の更新

エージェントを呼び出し可能なものとして公開したり、Veris の actor 呼び出しをエージェント固有の形式に変換したり、その他の方法で actor とエージェントの間に介在したりする Python の「ラッパーモジュール」は作成しないでください。エージェント本来のインターフェースを使用します。

5.4 エージェントのコードを変更しない

エージェントは、本番環境とまったく同じ状態で Veris 上で実行されます。つまり：

• シミュレーションに対応するためにソースコードへパッチを適用しない
• 「シミュレーションモード」フラグや Veris 固有の分岐を追加しない
• エージェントのローカル変更を加えたフォーク版を作成しない

エージェントのソースを変更したくなったら、作業を止めてください。次のいずれかに該当します：

• 環境変数の上書きで表現できる変更なら、その方法で対応します（agent.environment または veris env vars set を使用します）
• エージェント自体の実際の問題なら、修正はお客様の責任です。また、本番環境にも影響します
• Veris が提供された状態のエージェントに対応できないなら、プラットフォームの不足です。エスカレーションしてください

無関係なリファクタリングを行わないのは当然です。

唯一認められているソースへの追加は、音声エージェント向けのクライアントツール報告フックです（コア処理に関する例外 を参照）。これは「コードを変更しない」原則に対する意図的な例外であり、反例ではありません。シミュレーション外では何も行わず、エージェントの動作を変更することもありません。また、トレースに記録されないクライアントツールを採点器が認識できるようにすることだけを目的としています。クライアントツールを使用する音声エージェントには追加してください。他のソースコードの編集に一般化しないでください。

ファイルがそろったら、そのままフェーズ 6 に進みます。

---

フェーズ 6：ランタイム環境変数の設定、検証、プッシュ

[フェーズ 6/7]

ユーザーに次のように伝えます。「プッシュ可能な Veris 環境に整えています。」

読み込むファイル：

• templates/env-vars.md
• phases/troubleshooting.md

6.1 環境変数の計画を立てる

環境変数を次のように分類します。

1. 安定したシークレットではないデフォルト値 → agent.environment に設定します
2. シークレット／環境ごとの値 → veris env vars set で設定します
3. ローカル専用の便宜的な値 → ローカルのスモークテスト用に、ルートの .env またはシェルのエクスポートを任意で使用します

.env.simulation は作成しないでください。

6.2 正確なコマンドを提示する

ユーザーが必要とする veris env vars set コマンドを正確に生成します。

ユーザーが実際の値を提示し、設定を依頼した場合は、代わりにコマンドを実行します。

シェル展開に関する注意点： シェル変数を使って veris env vars set KEY="$VAR" --secret を実行する場合は、最初に元の変数が実際に設定されていることを確認します（printenv VAR または test -n "$VAR"）。空または未設定の変数は、何の警告もなく "" に展開されます。CLI はエラーを出さずに空のシークレットを保存するため、エージェントは実行時に明確な「キーがありません」というメッセージではなく、原因の分かりにくい認証／プロバイダーエラーを返します。

6.3 プッシュの前提条件を検証する

プッシュする前に、以下を確認します。

• veris がインストールされている
• 認証／プロファイルが機能している
• .veris/config.yaml に環境 ID がある
• .veris/veris.yaml が存在する
• .veris/Dockerfile.sandbox が存在する

任意ですが、推奨：

• 明らかな問題を素早く見つけられそうな場合は、ローカルで docker build -f .veris/Dockerfile.sandbox . を実行してスモークテストを行います

6.4 プッシュする

ユーザーの承認を得たら、次を実行します。

veris env push

ユーザーがタグを指定したい場合は、明示的なタグを付けて実行します。

veris env push --tag <tag>

プッシュに失敗した場合：

• 失敗したビルド手順を診断します
• インテグレーションを修正します
• 再試行します

6.5 最終的な要約

以下を要約します。

• 作成または変更したファイル
• 選択したインテグレーションモード
• モック化、バンドル、外部化、またはスキップしたサービス
• 設定した環境変数と、ユーザーに設定を任せた環境変数
• veris env push が成功したかどうか、および作成したタグ

続けて、次のコマンドを提案します。

• veris scenarios create
• veris simulations create

---

フェーズ 7：スモーク検証

[フェーズ 7/7]

ユーザーに次のように伝えます。「インテグレーションがエンドツーエンドで動作することを確認するため、シナリオとシミュレーションを 1 件ずつ実行します。」

7.1 スモークシナリオを作成する

veris scenarios create --num 1

目標は、エージェントの主要なインターフェースをテストする、短いやり取りを 1 件作ることです。

7.2 シミュレーションを 1 件実行する

veris simulations create --scenario-set-id <id>

完了するまで待ちます。

7.3 結果を確認する

シミュレーションで以下を確認します。

1. エージェントが実際の内容を返している — エラーページ、空の本文、例外のトレースバックではない
2. モックサービスが呼び出されている — エージェントが Slack、Salesforce などを呼び出す想定の場合、それらの呼び出しが記録されていることを確認します
3. 起動時にクラッシュしていない — エージェントプロセスが実行中ずっと稼働していた
4. チャネルの契約が正しい — アクターのメッセージがエージェントに届き、想定される形式で応答が返ってきた

7.4 失敗を診断する

スモークテストが失敗した場合：

• エージェントコンテナのログを確認し、起動エラーや不足している環境変数がないか調べます
• actor.channels のリクエスト／レスポンスのマッピングが実際の API 形式と一致していることを確認します
• モックサービスの認証情報と DNS エイリアスが正しいことを確認します
• 該当するフェーズに戻って修正し、再度プッシュします

7.5 完了を報告する

スモークテストに合格した場合、以下を要約します。

• アクターが送信した内容と、エージェントが返した内容
• テストしたサービス
• インテグレーションが完全なシナリオ生成に対応できる状態であることへの確信度

続けて、次のステップとして完全なシナリオ生成（veris scenarios create --num N）とシミュレーションを提案します。

---

実践的な指針

古いひな形より現在の規約を優先する

veris env create が古い形式に見えるプレースホルダーを生成した場合は、このスキルに記載されている現在推奨される形式で上書きします。

関数チャネルの機能を正確に説明する

エージェントが公開インターフェースの一部として呼び出し可能な機能をすでに公開している場合に限り、関数チャネルを使用してください。ネットワーク接続された製品を、単純そうだからという理由だけで関数呼び出しに無理に当てはめないでください。また、エージェントがもともと備えていない機能を作り出すために、ラッパーファイルを作成してはいけません。

ワンショットエージェントの性質を正確に伝える

統合されたエージェントが明らかにワンショット／ステートレスである場合は、actor.config.MAX_TURNS: 1 を設定して、その性質を明示してください。

自動化しなかったことを明確にする

ログイン、シークレット、または環境変数の値について、ユーザーによる操作が引き続き必要な場合は、その旨を明確に伝えてください。目的は可能な限り先へ進むことであり、障害要因を隠すことではありません。