このガイドでは、OpenAPI 3.0 ドキュメントをエージェントツールに変換する方法を学ぶできます。agentengine agent create-tool コマンドを使用して、ドキュメントをコネクタファイルにコンパイルします。エージェントをビルドすると、Atlas Agent Engine がそれらのファイルからコネクタを作成し、エージェントが OpenAPI エージェントツールを呼び出せるようにします。
注意
agentengine agent create-tool コマンドは実験的です。フラグ、出力形式、生成されるファイル形式は予告なく変更される場合があります。
このタスクについて
agentengine agent create-tool コマンドは、指定したフォルダーに2つのファイルを生成します。
tool_defs.yaml: OpenAPIドキュメントからコマンドがコンパイルするツールのカタログ。カタログには、ツール名、入力スキーマ、および各操作のHTTPメソッドとパスが含まれます。tool.yaml：カタログをAPIエンドポイントとなる接続されたデバイスおよび認証情報にバインドし、エージェントが公開するツールを選択するオーサリングファイル。このコマンドは、このファイルをスキャフォールディングします。カタログを再生成しても、コマンドはファイルへの編集を上書きしません。
エージェントがコネクタツールを呼び出すと、そのツールは分離されたTool Podで実行されます。この呼び出しは、他のツールと同様に、Orchestration エンジンの承認ゲートを経由します。認証情報の値が生成されたファイルに書き込まれることはなく、ファイルは代わりにワークスペースシークレットの名前を参照します。
コマンドには、次の入力のうちの1つだけを渡す必要があります。
--spec: OpenAPI 3.0 ドキュメントをカタログにコンパイルし、存在しない場合はtool.yamlファイルをスキャフォールディングします。値には、ローカルファイルまたは HTTPS URL を指定できます。--tool-defs: 既存のローカルカタログ用にtool.yamlファイルのみをスキャフォールドします。このコマンドはカタログを書き換えません。--config:source.specフィールドを宣言するtool.yamlファイルから、ローカルで所有されているカタログを再生成します。
すべてのフラグを表示するには、agentengine_create-tool CLI ドキュメントを参照してください。
始める前に
始める前に、以下のリソースがあることを確認してください。
手順
コネクタファイルを生成します。
エージェントのプロジェクトディレクトリから、コネクタ名と --spec フラグを指定して agentengine agent create-tool コマンドを実行します。次の例では、仕様を connectors/orders フォルダーにコンパイルし、Bearer token認証を構成します。
agentengine agent create-tool orders \ --spec <openapi-document-url-or-path> \ --out-dir connectors/orders \ --auth bearerこのコマンドは、コネクタにちなんでBearer tokenのワークスペースシークレットに名前を付けます。ordersコネクタの場合、シークレット名はORDERS_TOKENです。--authフラグを省略した場合、コマンドはドキュメントが宣言するセキュリティスキームからtool.yamlファイルにauthブロックを生成します。
このコマンドは、ドキュメント内の最初のテンプレート化されていないサーバーをベースURLとして使用します。ドキュメントでサーバーが宣言されていない場合、または別のエンドポイントとなる接続されたデバイスを呼び出す場合は、コマンドに --base-url フラグを追加します。
ドキュメントにジェネレーターが表現できない操作が含まれている場合、コマンドは失敗し、その操作の名前が出力されます。代わりにそれらの操作を除外するには、コマンドに --skip-unsupported フラグを追加します。このコマンドは、スキップされたすべての操作を出力し、カタログにレコードします。
tool.yaml ファイルを検討する。
connectors/orders/tool.yaml ファイルを開きます。ファイルの上部にあるコメントには、エージェントが宣言する必要があるエンドポイントとなる接続されたデバイスの宛先と認証情報のシークレットが記載されています。
エージェントが呼び出せるツールを制限するには、expose.allowフィールドに特定のツール名をリストします。このリストを省略すると、エージェントは生成されたすべてのツールを呼び出すことができます。次の例は、1つのツールを公開するtool.yamlファイルを示しています。
name: orderstool_defs: tool_defs.yamlsource: type: openapi base_url: https://api.example.comexpose: allow: [orders_getOrder]auth: bearer: ORDERS_TOKENAPI認証情報をワークスペースシークレットとして保存します。
tool.yaml ファイルの auth ブロックが参照する名前でシークレットを作成します。この例では、シークレット名は ORDERS_TOKEN です。シークレットを保存する方法を学ぶには、「クラウドシークレットのプロビジョニング」を参照してください。
ツールサンドボックスにシークレットとAPIへのアクセス権を付与します。
tool.yaml ファイルの先頭にあるコメントは要件のみを報告するものであり、権限を付与するものではありません。agent.yaml ファイルで、シークレットを sandboxes.tool.secrets フィールドに追加し、API ホスト名を sandboxes.tool.network.egress フィールドに追加します。他のツールですでに使用しているシークレットと宛先を保持します。次の例では、ORDERS_TOKEN シークレットと api.example.com ホストを追加します。
sandboxes: tool: secrets: - ORDERS_TOKEN network: egress_mode: allow_list egress: - fqdn: api.example.com ports: [443]tool.yaml ファイルのベース URL のホスト名とポートで api.example.com と 443 を置き換えます。詳細については、「エージェント YAML スキーマ」および「Manage Network Egress Policies」を参照してください。
エージェントをビルドするして配置する。
通常通りエージェントをビルドするして配置するします。ビルドするによって、tool.yamlファイルとtool_defs.yamlファイルからコネクタが作成されます。詳細については、「エージェントイメージをビルドする」を参照してください。
行動と限界
生成されたコネクタツールの次の動作と制限事項を確認してください。
tool.yamlファイルのベース URL は、すべての操作に適用されます。ジェネレーターは、OpenAPI ドキュメントのパスレベルおよび操作レベルのserversエントリを無視します。ジェネレーターはローカルファイルを読み取ります。CLIは、プラットフォームの転送ポリシーに基づき、URLで指定されたドキュメントをダウンロードします。
ジェネレーターは、Bearer token、API キー、および HTTP Basic 認証をサポートしています。以下は生成境界外です。
OAuthトークンの取得と更新
インタラクティブまたはセッションログイン
リクエストごとの署名
mTLSのみの認証
マルチパートファイルアップロード
コネクタは、200,000 デコード済みバイトを超えるレスポンスを切り捨て、切り捨てられたものとしてマークします。
各ツールの呼び出しは、30秒後にタイムアウトします。
詳細
OpenAPIツールについてさらに学ぶには、以下のドキュメントをご覧ください。
agentengine_create-tool