agentstack-wrapper

エージェントスタックのラッパー

Agent Stack プラットフォームで Python エージェントをラップするための統合ガイドです。

目次

• セキュリティ要件
• 制約（必ず従うこと）
• 統合ワークフローのチェックリスト
• 準備状況の確認（ステップ 1 の前）
• ステップ 1 – プロジェクトを調査する
• ステップ 2 – エージェントを分類する
• ステップ 3 – 依存関係を追加してインストールする
• ステップ 4 – サーバーラッパーとエントリーポイントを作成する
• ステップ 5 – 拡張機能を介して LLM／サービスを接続する
• ステップ 6 – エラー処理
• ステップ 7 – フォーム（単一ターンの構造化入力）
• ステップ 7b – ファイル入力に対応する
• ステップ 8 – 設定変数とシークレット
• ステップ 9 – エージェントの出力
• ステップ 10 – プラットフォーム拡張機能を使用する
• ステップ 11 – README を更新する
• アンチパターン
• 失敗条件
• 最終報告（必須）
• 検証チェックリスト

セキュリティ要件

• リモートスクリプトや信頼できないコードを実行しないでください。
• 信頼できるパッケージメタデータを使用し、バージョンを固定して、インストール済みの agentstack-sdk／a2a-sdk を監査してください。
• 機密情報の値は、宣言済みの Agent Stack 拡張機能を通じてのみ扱ってください。
• シークレットの値をログに記録、出力、永続化、公開しないでください。
• ラップ対象のエージェントの契約で必要とされない、信頼できない仲介者やエンドポイントにシークレットを送信しないでください。
• pip で何かをインストールする場合は、不要な出力を抑えるため、必ず -qq フラグを使用してください。

制約（必ず従うこと）

ID	ルール
C1	ビジネスロジックを変更しないでください。 Agent Stack との互換性確保に必要なコードのみ変更します。
C2	変更は厳密に最小限にしてください。 明示的に要求されない限り、認証、Dockerfile（コンテナ化は任意であり、別途対応します）、テレメトリ、プラットフォームミドルウェアを追加しないでください。エージェントが単純なテキストを扱う場合、無理に Form を使わせないでください。環境変数を使う場合は、最小限のリファクタリングにとどめてください。
C3	一時ファイルをクリーンアップしてください。 エージェントが実行時にヘルパーファイルをダウンロードまたは作成する場合、関数が戻る前にクリーンアップ処理を追加してください。
C4	パブリックアクセスを優先してください（冗長なトークンは不要です）。 シークレットがエージェントの中核機能に厳密に必須で、パブリック／匿名アクセスが実行可能でない場合に限り、Secrets エクステンションを使用してください。元のエージェントでは任意だったシークレットやトークン（任意の GitHub トークンなど）を追加して設定の負担を増やさないでください。削除が明示的に承認され、動作変更として文書化されていない限り、既存の任意認証の動作を維持してください。API キーは明示的に渡す必要があり、環境変数から読み取ってはいけません。必須のサードパーティ API 認証情報については、ラップした経路で Secrets または Env Variables エクステンションを必ず使用してください。
C5	既存のツール構成を確認してください。 プロジェクトが requirements.txt を使用している場合は、そこに agentstack-sdk~=<VERSION> を追加してください。pyproject.toml を使用している場合は、そこに追加してください。a2a-sdk を追加するのは、プロジェクトがこれを直接管理している場合に限り、選択した agentstack-sdk のバージョンとの互換性を保ってください。uv を無理に導入したり、マニフェストを重複して作成したりしないでください。
C6	インポートの情報源はパッケージを優先してください。 references/dependencies.md で定義されている Inline Package Search スクリプトは、正しいインポートパス、クラス名、型を見つける際に最優先です。ローカルの参照ファイルやオンラインドキュメントを参照する前に、必ずこのスクリプトを実行してインポートを特定してください。インポートを推測したり、インストール済みパッケージと食い違う場合にドキュメントの記載をそのまま信頼したりしないでください。
C7	ドキュメントは二次的な情報源です。 references/ フォルダー内のローカルスキルファイルとオンラインドキュメントは、_動作、ロジック、エクステンションの選択_に関する第一の情報源ですが、インポートパスなどの_正確な実装詳細_については、パッケージの調査より優先度が低くなります。
C8	フォールバックと検証の順序。 インポートについては、まずローカルソースの調査とパッケージの調査を行ってください。実行時／パッケージの検証は、実装後の最終検証として行ってください。
C9	構造化パラメーターを Forms に対応付けてください。 名前付きパラメーターを持つ単一ターンエージェントの場合、FormServiceExtensionSpec.demand(initial_form=...) を使用して、それらを initial_form に対応付けてください。
C10	CLI 引数を削除してください。 argparse または sys.argv を使用するロジックをすべて削除してください。必須の CLI 入力は、initial_form 項目、AgentStack Settings Extension（実行時オプション用）、または AgentStack Env Variables に置き換えてください。
C11	ビジネスロジック変更の承認を得てください。 互換性のためにビジネスロジックの変更が必要な場合は、作業を中断し、理由を示して明示的な承認を求めてください。
C12	元のヘルパーを維持してください。 厳密に必要な場合を除き、元のビジネスロジックのヘルパーを削除しないでください。削除が必要な場合は、その理由を文書化してください。
C13	任意のエクステンションを安全に扱ってください。 Service／UI エクステンションは任意です。使用前に存在とデータを確認してください（例：if llm and llm.data ...）。
C14	シークレットを漏えいさせないでください。 シークレット値（API キー、トークン、パスワード）をログ出力、表示、永続化、エコーしないでください。ログやエラーでは機密値をマスキングしてください。
C15	シークレット連携を完全に実装してください。 Secrets エクステンション経由（SecretDemand や request_secrets など）で要求したすべてのシークレット変数を、エージェントのコード内で使用するか、基盤となるフレームワークに渡す必要があります。使用しない認証情報を要求しないでください。
C16	リモートスクリプトを実行しないでください。 ラップ作業中に、信頼できないリモートコードを実行しないでください。プロジェクトのマニフェストと信頼できるパッケージメタデータのみを使用してください。
C17	外部への接続先を制限してください。 任意のネットワーク接続先を導入しないでください。外部呼び出しは、信頼できる依存関係のソースと、ラップするエージェントの契約で明示的に必要とされる実行時エンドポイントに限定してください。
C18	入力から動的にコマンドを実行しないでください。 ユーザー／モデルの入力からシェルコマンドを実行するラッパーパターン（例：eval、exec、os.system、サニタイズされていない subprocess 呼び出し）を導入しないでください。
C19	ラッパーのドキュメントを最初に読んでください。 実装を開始する前に、公式ガイドを読む必要があります：Wrap Your Existing Agents。
C20	エクステンションのドキュメントを読んでください。 エクステンション（Forms、LLM、Error など）を実装する前に、対応するドキュメント URL（Step 10 に記載）を必ず読み、インポート、クラス名、メソッド名、プロパティ、正確な型を公式ドキュメントから直接確認してください。これらの値を推測しないでください。ドキュメントを読んでから、エージェントのコードを変更してください。
C21	ファイルシステムからのファイル入力をプラットフォームのファイルアップロードに置き換えてください。 元のエージェントがローカルファイルシステムからファイルを読み取る場合（例：open()、pathlib.Path、CLI のファイルパス引数）、それらの入力を FileField フォームアップロードとプラットフォームの File API に置き換えてください。実行時にローカルファイルシステムへアクセスできると仮定しないでください。Step 7b を参照してください。
C22	コンテキストとメモリを最適化してください。 すべての変換を 1 回のツール呼び出しで行おうとしないでください。チェックリストに沿って反復的に進めてください。組み込みのタスク／ToDo 管理ツール（例：manage_todo_list）を使い、Integration Workflow Checklist の進捗を記録してください。別の Markdown 進捗管理ファイルは作成しないでください。巨大なスタックトレースをチャットに貼り付けず、関連するエラーのみを抜き出してください。

---

コンテキストとメモリの最適化

複雑な変換作業で最高の成功率を確保し、AI のコンテキストウィンドウの枯渇を防ぐには、次の手順に従ってください。

1. 段階的に進める：Integration Workflow Checklist に従い、各ステップを順番どおりに厳守して実行してください。組み込みのタスク／ToDo 追跡ツールを使ってチェックリストの項目を反映し、各ステップの完了時にチェックを付けてください。これにより、ファイルを追加作成することなく、進捗を目に見える形で追跡できます。
2. ターミナル出力を最小限にする：デバッグ時は、大量のスタックトレースでコンテキストを圧迫しないようにしてください。大規模なフレームワークログは省き、Exception の行と直後のトレースバックのファイルのみを抽出してください。
3. 対象を絞ってコードを読む：変更されていない SKILL.md などの大きなファイルや大規模なソースコードファイルを、繰り返し読み込まないでください。
4. 追跡用ファイルを作成しないでください：進捗の追跡に task.md、implementation_plan.md、walkthrough.md などの Markdown ファイルや類似の成果物を作成しないでください。進捗状況の唯一の情報源として、組み込みのタスク追跡ツールを使用してください。

情報源の優先順位（必須）

ラッピング作業では、必ず次の優先順位に従ってください。

1. 最優先の情報源（最高優先度）： すべてのインポート、クラス名、型について、インストール済みパッケージ／ランタイムのイントロスペクション（references/dependencies.md の Inline Package Search）を使用します。
2. 第一の情報源（必須の第 2 優先度）： アーキテクチャパターン、拡張機能の選択肢、マッピングロジックについては、references/ フォルダー内にあるスキル提供のローカルファイルを使用します。
3. 第二の情報源： 詳細な API の動作については、このスキルに記載された公式ドキュメントの URL を使用します。
4. 第三の情報源： 動作や統合箇所を対応付けるには、ローカルのプロジェクトソースコードとリポジトリのドキュメント（README/AGENTS）を使用します。
5. 最終ステップ： 実装完了後にランタイム検証（インポート／サーバーチェック）を行います。

ステップ 3 を使用した場合は、ドキュメントに不足していた情報と、なぜ代替手段が必要だったのかを明記してください。

重要なワークフロー要件： 使用を決めたすべての拡張機能（LLM／Forms／Error のステップからのものか、Platform Extensions のものかを問いません）について、必ず次の手順を順番どおりに実行してください。

1. 拡張機能を実装すべきかどうかを判断します。
2. 実装する場合は、以下の拡張機能テーブルに記載されたドキュメント URL を読みます（たとえば、ツールを使ってウェブページを読み取ります）。これは必須であり、コードを編集する前に行ってください。
3. 公式ドキュメントから、正しいインポート、クラス名、メソッド名、プロパティ、正確な型を確認します。
4. ドキュメントを読んだ後に限り、エージェントコードの作成または変更に進みます。インポートを推測したり、古い記憶に頼ったりしないでください。
5. ドキュメントに不足がある、または不明確な場合は、代替手段としてローカル／ランタイムのイントロスペクションを使用し、具体的な不足点を記録します。

---

統合ワークフローのチェックリスト

このチェックリストをコンテキストにコピーし、各項目の完了時にチェックを付けてください。

Task Progress:
- [ ] Readiness Check (before Step 1)
- [ ] Step 1: Study the Project
- [ ] Step 2: Classify the Agent
- [ ] Step 3: Add and Install Dependencies
- [ ] Step 4: Create the Server Wrapper & Entrypoint
- [ ] Step 5: Wire LLM / Services via Extensions (requires reading docs)
- [ ] Step 5a: Set suggested model to match the model used in the original agent
- [ ] Step 6: Implement Error Handling (requires reading docs)
- [ ] Step 7: Map Forms (if applicable) (requires reading docs)
- [ ] Step 7b: Adapt File Inputs (if applicable) (requires reading docs)
- [ ] Step 8: Map Configuration Variables & Secrets (requires reading docs)
- [ ] Step 8a: Credential audit completed (every external API credential source identified; required credentials mapped to Secrets extension)
- [ ] Step 9: Agent Output (requires reading docs)
- [ ] Step 10: Use Platform Extensions (requires reading docs for each chosen extension)
- [ ] Step 11: Update README
- [ ] Finalization Report (required)
- [ ] Verification Checklist (required)

停止ゲート： ステップ 11 の後、完了を報告する前に、最終報告を作成し、検証チェックリストのすべての項目を確認しなければなりません。両方が完了するまで、作業は完了していません。

準備状況の確認（ステップ 1 の前）

• アクティブな環境で、サポート対象の Python インタープリターが選択されています（Python >=3.12 かつ <3.14。インストールされているだけでは不十分です）。
• エージェントのソースコードがローカルで利用可能です。
• プロジェクトの依存関係管理ワークフローが特定されています。

いずれかの項目を満たしていない場合は、作業を中断してユーザーに確認してください。

ステップ 1 – プロジェクトを調査する

変更を加える前に、既存のプロジェクトを詳しく調査し、そのアーキテクチャと要件を理解する必要があります。

README.md または AGENTS.md ファイルがある場合は、エージェントの構造と目的をよりよく理解するため、最初に読んでください。

以下の項目を評価し、記録してください。

• コア機能：エージェントは何をしますか？主な入力と出力は何ですか？
• 依存関係：エージェントはどの外部システム、API、データベースに依存していますか？
• 設定：エージェントはどのように設定しますか（環境変数、設定ファイル、CLI 引数など）？
• ツールとライブラリ：LLM とのやり取りには、主にどのライブラリを使用していますか（LangChain、OpenAI SDK のみなど）？

ステップ 2 – エージェントを分類する

エージェントのコードを読み、分類してください。この分類によって、interaction_mode の値が決まります。

interaction_mode	パターン	判定の目安
single-turn	1 つのリクエスト → 1 つの応答	CLI エントリーポイント、argparse（削除が必要）、主にステートレスなビジネスロジック、コンテキストの永続化も推奨されます
multi-turn	メモリを使用した会話	チャットループ、メッセージ履歴、セッション状態、メモリオブジェクト

この分類によって、以下が決まります。

• context.store() と context.load_history() の使用方法：すべてのエージェントで、入力と応答をデフォルトで永続化します。context.load_history() は multi-turn では必須、single-turn では省略可能です（以前のコンテキストを意図的に動作に含める場合にのみ使用します）。
• 構造化入力（名前付きパラメーターを持つ single-turn）のために initial_form を定義するかどうか

---

ステップ 3 – 依存関係を追加してインストールする

references/dependencies.md を読み、ステップ 3 の手順にすべて従ってください。

---

ステップ 4 – サーバーラッパーとエントリーポイントを作成する

references/wrapper-entrypoint.md を読み、ステップ 4 の手順にすべて従ってください。

---

ステップ 5 – 拡張機能を介して LLM／サービスを接続する

references/llm-services.md を読み、ステップ 5 の手順にすべて従ってください。

LLMServiceExtensionSpec.single_demand() の suggested モデルには、元のエージェントで使用しているものと同じモデルを設定してください。

---

ステップ 6 – エラー処理

ユーザーに表示するエラーには Error 拡張機能を使用してください。通常の AgentMessage でエラーを報告してはいけません。

実装

1. 標準的な報告：エージェント内で例外（ValueError、RuntimeError など）を raise するだけです。プラットフォームが自動的に捕捉してフォーマットします。
2. 詳細設定：UI でスタックトレースを有効にするには、エージェント関数のパラメーターとして error_ext: Annotated[ErrorExtensionServer, ErrorExtensionSpec(params=ErrorExtensionParams(include_stacktrace=True))] を追加します。
3. コンテキストの追加：エラーを raise する前に、診断データを error_ext.context（辞書）に追加できます。このコンテキストは JSON にシリアライズされ、UI に表示されます。
4. 複数のエラー：複数の失敗を同時に報告するには、ExceptionGroup（Python 3.11 以降）を使用します。拡張機能によって、UI にグループとして表示されます。

例

実装例については、公式エラーガイド と チャットエージェントの例 を参照してください。

---

ステップ 7 – フォーム（単一ターンの構造化入力）

元のエージェントが自由形式のテキストだけでなく、名前付きパラメーターを受け付ける場合は、Forms 拡張機能を使用して initial_form にマッピングします。自由形式のテキストを受け付けるエージェントでは、通常のメッセージ入力で十分です。このステップはスキップしてください。

実装ガイド（フィールドの種類、Pydantic モデル、会話中の入力）全体については、references/forms.md をお読みください。

---

ステップ 7b – ファイル入力の適合

元のエージェントがローカルファイルシステムからファイルを読み込む場合、または CLI／関数の引数としてファイルパスを受け付ける場合は、それらの入力をプラットフォームのファイルアップロードに置き換える必要があります。実行時にローカルファイルシステムへアクセスすることはできません。ファイルにプレーンテキストしか含まれていない場合でも、FileField のアップロードを使用してください。ファイル入力をメッセージテキストに平坦化してはいけません。

検出パターン、置換手順、テキスト抽出、会話中のアップロードについては、references/files.md をお読みください。

---

ステップ 8 – 設定変数とシークレット

設定のマッピング、シークレットの処理、アンチパターンについては、references/configuration-variables.md をお読みになり、内容に従ってください。

---

ステップ 9 – エージェントの出力

軌跡出力のルールと実装

軌跡の判断ルールと実装については、references/trajectory.md をお読みになり、内容に従ってください。

最終出力のルール

エージェントまたは LLM からユーザーに返す主要な最終出力は、常に通常の AgentMessage または AgentArtifact として出力する必要があります。

軌跡には、最終回答に至るまでの中間コンテキスト、推論、手順のみを含めてください。最終回答の代わりにはなりません。

コールバックが同期処理のみの場合は、コールバックのデータを取得し、後でメインのエージェントハンドラーから出力してください。

アーティファクト出力のルール

元のエージェントが実行の一部としてファイル（CSV、PDF、画像、構造化データのダンプなど）を生成、処理、または出力する場合は、それらのファイルを AgentArtifact として呼び出し元に返す必要があります。ファイルをローカルディスクに書き込むだけで、「File generated」というテキストメッセージを出力してはいけません。ローカルファイルシステムへの変更はプラットフォームの UI に返されないためです。

プラットフォームの API を使用して、生成したコンテンツを参照する AgentArtifact を構築してください。具体的な実装方法については、AgentArtifact Documentation を参照してください。

---

ステップ 10 – プラットフォーム拡張機能の使用

Annotated 関数パラメーターを介して拡張機能を注入し、プラットフォームレベルの機能でエージェントを強化します。

拡張機能の選択とドキュメントへのリンクについては、references/platform-extensions.md をお読みください。

ステップ 10 の判断と実装では、このリファレンスを必須の入力として扱ってください。

---

ステップ 11 – README の更新

プロジェクトの README.md を更新するか、存在しない場合は新たに作成して、ラップしたエージェントサーバーの実行方法を記載してください。次の内容を含めます。

1. プロジェクトで既に使用しているツールを使って依存関係をインストールします（例：uv pip install -qq -r requirements.txt または pip install -qq -r requirements.txt）。ターミナル出力を簡潔に保つため、必ず -qq フラグを使用してください。
2. 環境設定 — python-dotenv を使用する場合は、必要な .env の形式を記載してください。ただし、エージェントが内部で環境変数の引数を読み取るのではなく、明示的に設定を受け取るようにしてください。
3. 適切なコマンド（例：uv run server.py または python server.py）でサーバーを実行します。
4. デフォルトのアドレス — サーバーはデフォルトで http://127.0.0.1:8000 で起動し、環境変数 HOST と PORT で設定できることを明記してください。

ラップ後には該当しなくなる古い CLI 使用例（argparse ベースのコマンドなど）は削除するか、置き換えてください。

---

アンチパターン

ラッパーの構築とテストを行う際は、次のようなよくある落とし穴を避けてください。

• Message オブジェクトの .text に直接アクセスしないでください。 メッセージの内容はマルチパートです。必ず get_message_text(input) を使用してください（from a2a.utils.message import get_message_text が必要です）。
• ファイルをローカルディスクに保存しないでください。 AgentStack の環境は一時的なものです。生成したファイルはすべてメモリ内で直接インスタンス化し、AgentArtifact(parts=[file.to_file_part()]) として yield してください。正しい File.create() API の使用方法については、ファイルの管理を参照してください。
• エージェントハンドラーに同期関数を使用しないでください。 エージェント関数は yield を使う async def ジェネレーターである必要があります。
• プラットフォームとの連携を抽象化レイヤーの背後に隠さないでください。 動作を監査できるよう、@server.agent(...)、拡張パラメーター、連携コントラクトはメインのエントリーポイントで確認できる状態にしてください。
• 実行時の調査を最初の情報源にしないでください。 agentstack_sdk と a2a の詳細は、まず提供されたドキュメントで確認してください。インストール済み環境の調査は、ドキュメントに記載されたフォールバックとしてのみ使用し、最後にインポートを検証してください。
• 履歴が自動保存されると思い込まないでください。 await context.store(input) と await context.store(response) を明示的に呼び出してください。
• PlatformContextStore がなければ履歴が永続化されると思い込まないでください。 これがない場合、コンテキストの保存先はメモリ内であり、再起動すると失われます。
• 履歴のフィルタリングを忘れないでください。 context.load_history() は Messages と Artifacts を返します。isinstance(message, Message) でフィルタリングしてください。
• 個々のストリーミングチャンクを保存しないでください。 応答全体を蓄積してから、一度だけ保存してください。
• 拡張データを辞書として扱わないでください。 ドット記法を使用してください（例：config.get("api_key") ではなく config.api_key）。
• モデル名に llm_config.identifier を使用しないでください。 代わりに llm_config.api_model を使用してください。
• すべての拡張仕様に .demand() があると思い込まないでください。 .single_demand() を使用するものや、直接インスタンス化するものもあります。必ず確認してください。
• シークレットが事前に設定済み、またはすぐに secret_fulfillments に存在すると思い込まないでください。 single_demand() で要求した場合でも、実行時にシークレットが見つからなければ、await secrets.request_secrets(params=SecretsServiceExtensionParams(...)) を使って明示的にポーリングする必要があります。
• trajectory 拡張で emit() を同期的に呼び出さないでください。 TrajectoryExtensionServer は .emit() をサポートしていません。yield trajectory.trajectory_metadata(title="...", content="...") のように yield して、軌跡のステップを明示的に出力する必要があります。
• 既存の任意認証の経路を、黙って削除しないでください。 元のエージェントが任意のトークン／キーに対応していた場合、承認済みの動作変更が明示的に文書化されていない限り、その任意の動作を維持してください。
• 単一の自由形式の追加質問に Forms を使わないでください。 1 つの自由回答形式の質問には A2A の input-required を使用し、Forms は複数フィールドの構造化された入力に限定してください。
• フォームのフィールド ID とモデルのフィールドを不一致にしないでください。 ID が一致しないと、解析に失敗しても通知されません。
• context.session_id を使用しないでください。 RunContext オブジェクトでは、セッションの識別に context.context_id を使用します。
• プラットフォームオブジェクトの属性を推測しないでください。 FormRender が使うのは items ではなく fields、TextField が使うのは title ではなく label です。
• フォームの null パス処理を省略しないでください。 キャンセルされたフォームや未送信のフォームでは None を処理してください。
• 複数ターンのエージェントで、ターンの振り分けに parse_initial_form(...) の真偽値を使わないでください。 context.load_history() から取得した、永続化済みのセッション状態の有無で振り分けてください。
• アップロードされたファイルの URI が HTTP URL だと思い込まないでください。 PlatformFileUrl を使って agentstack:// URI を解析してください。
• 抽出のポーリングを省略しないでください。 create_extraction() は非同期です。status == 'completed' になるまで get_extraction() をポーリングしてください。

失敗条件

• 最新のドキュメントを取得できない場合は停止し、現在のドキュメントなしでは処理を続行できないことを報告してください。
• ドキュメントに必要な詳細がなく、信頼できるフォールバック情報源もない場合は停止し、阻害要因を明示的に報告してください。

---

最終化レポート（必須）

完了する前に、以下のすべてを提示してください。

1. マッピングの概要： インバウンドマッピング（A2A Message からエージェント入力へのマッピング）、アウトバウンドマッピング（エージェント出力から AgentMessage へのマッピング）、選択したストリーミング方式。
2. 動作変更の一覧： 動作に変更があった場合は、変更ごとに理由と影響を記載してください。
3. ビジネスロジックに関する説明： ビジネスロジックが変更されたかどうかを明記してください。変更された場合は、承認と正当な理由を記載してください。
4. レガシーエンドポイントの互換性に関する結果： 維持、シムで対応、または該当なしのいずれかを明記してください。
5. Dockerfile に関する確認： Dockerfile も追加するかどうか、ユーザーに尋ねてください。ユーザーが希望した場合は、https://github.com/i-am-bee/agentstack-starter/blob/main/Dockerfile の例を確認し、プロジェクト用の Dockerfile を作成してください。プロジェクトで uv を使用していない場合、無理に使用させないでください。
6. テストに関する確認： エージェント機能をテストするかどうか、ユーザーに尋ねてください。希望した場合は、まず1つ目のターミナルでエージェントを起動し、次に別のターミナルで agentstack run AGENT_NAME を実行してください。完了まで長時間かかる場合があるため、run コマンドを中断しないでください。実行に失敗してエラーが発生した場合は、エラーの修正を試みてからテストを再実行してください。重要：このテストを実行するために、新しいファイルやスクリプト（例：pexpect を使用する Python テストスクリプト）を作成しないでください。ターミナルを直接操作する必要があります。 agentstack run は対話形式のフォームを表示します。stdin を使ってプログラムからテストする場合は、プロンプトを進めるために、正確な改行文字を送信してください。
7. 実行に関する確認： エージェントを実行して Web UI にリダイレクトするかどうか、ユーザーに尋ねてください。ユーザーが同意した場合は、エージェントを起動し、ターミナルにエラーがないか監視してください。エラーが発生した場合は、修正を試みてからエージェントを再起動してください。

---

検証チェックリスト（必須）

仕上げの後、以下を確認してください。

コード品質

• すべての import が、実際にインストールされているモジュールを参照している（インポート検証を実行する）
• エージェント関数に、UI に表示される意味のある docstring がある
• エージェントハンドラーが async def で、応答に yield を使用している
• argparse や sys.argv が残っていない
• 明示的な承認がない限り、ビジネスロジックを変更していない（C1/C11）
• 実行時に作成した一時ファイルが削除される（C3）

拡張機能と設定

• ユーザー向けの応答すべてに yield AgentMessage(text=...) を使用している
• API キーやモデル設定に環境変数を使用しておらず、代わりに拡張機能を使用している
• 必須の外部 API ツール（例：Tavily）の認証情報を Secrets 拡張機能から取得し、コンストラクター／クライアントに明示的に渡している
• Secrets 拡張機能から要求するすべてのシークレットが、実際にコード内で使用されているか、基盤となるサービスに渡されている（C15）
• LLM 設定を拡張機能から明示的に渡し、フォールバックチェーンを使用していない
• オプションの拡張機能を使用する前に、その存在／データを確認している（C13）
• エラーを AgentMessage として出力せず、例外を発生させている（Error 拡張機能）
• シークレットをログ出力、表示、または永続化していない（C14）

コンテキストと履歴

• input と response を context.store() で保存している
• コンテキストを永続化／読み込みする場合は、context_store=PlatformContextStore() が設定されている
• マルチターンでは context.load_history() を使用している。シングルターンでの使用は、意図的な場合に限る

フォームとファイル

• 構造化パラメーターを使用するシングルターンの場合、initial_form が定義されている（C9）
• ファイルシステムのファイル入力を FileField フォームアップロードに置き換えている（C21）
• テキスト処理エージェントでは、幅広い MIME タイプを使用し、コンテンツタイプに応じて分岐して抽出している
• ユーザー提供ファイルの読み込みに、ローカルファイルシステムを使用していない

依存関係

• プロジェクトで既に使用している依存関係ファイルに agentstack-sdk~=<VERSION> を追加している（C5）
• 明示的に要求されていない限り、Dockerfile を追加していない（C2）

検証（実際に実行する必要があります）

• サーバーを起動し、/.well-known/agent-card.json を取得して、HTTP 200 と有効な JSON を確認します。出力全体をユーザーに表示してください。
• Dockerfile が必要かどうか、ユーザーに尋ねます。
• agentstack run AGENT_NAME でテストするかどうかをユーザーに尋ね（テストスクリプトは使用せず、ターミナルを直接使います）、エラーがないか確認します。エラーが発生した場合は、修正して成功するまで再テストします。エラーが発生した場合は、ターミナルの出力を確認するよう依頼すれば、修正を試みることを、ユーザーにごく簡潔に伝えます。