Cortex Agentコード実行ツール¶

Cortex Agentコード実行は、会話中にエージェントがコードを実行できるようにする組み込みツールです。コード実行ツールへのアクセスを有効にすると、エージェントはスクリプトを実行してデータを処理し、計算を実行し、可視化を生成できます。デフォルトでは、コード実行ツールは、現在のエージェントセッションのデータのみにアクセスできるサンドボックスの分離された環境で実行されます。

エージェント仕様で構成することで、コード実行ツールを有効にします。次に、エージェントはオーケストレーション中にユーザーのクエリに基づいてコードを生成し、実行するタイミングを決定します。コード実行ツールは、エージェントスキルの一部としてPythonスクリプトを実行する場合にも使用されます。

コード実行の仕組み¶

エージェントは、他の構成されたツールやスキルと一緒にコード実行を使用します。オーケストレーション中、エージェントはユーザーのクエリを評価し、コードの実行が最良のアプローチであるかどうかを判断します。その場合、エージェントはコード実行ツールを呼び出します。

次にエージェントはコードを生成し、セキュアサンドボックスで実行します。デフォルトでは、コード実行ツール環境は分離されており、セッションに渡されたデータにのみアクセスできます。エージェント仕様で、追加の読み取りまたは書き込み権限を付与できます。

デフォルトのアクセス範囲¶

コード実行ツールのサンドボックスは、単一のセッションで持続します。会話コンテキストで提供されるデータは、操作用のコード実行ツールで使用できるものです。サンドボックスは、セッション内の複数の実行で、インポート、変数、および中間結果を永続化します。

コード実行ツールの有効化¶

Cortex Agentでコード実行ツールを使用するには、エージェントに必要なアクセス制御権限と、コード実行ツールを説明するエージェント仕様セクションの両方が必要です。

Cortex Agentの必要権限¶

Cortex Agentに対する次の権限は、エージェントを構成する機能とクエリを実行する機能の両方に影響します。


権限	に必須です
USAGE	コード実行ツールの使用など、エージェントの呼び出しを許可します
MODIFY	コード実行ツールを有効または構成するためのエージェント仕様の変更
OWNERSHIP	エージェントの構成と使用のフルコントロール

エージェント仕様¶

コード実行ツールのリソースと構成をエージェント仕様に追加することで、コード実行ツールを有効にします。

エージェント仕様の tools セクションに追加するツール定義は次のとおりです。

tools:
  - tool_spec:
    type: code_execution
    name: code_execution

code_execution セクションをエージェント仕様の tool_resources に追加してツールを有効にします。

tool_resources:
  code_execution:

エージェントの仕様形式に関する詳細と、既存のエージェントの仕様を変更する方法については、エージェントの構成と操作をご参照ください。

デフォルトの利用可能なライブラリ¶

コード実行ツールのデフォルトの実行環境はPython 3.12を使用し、Python標準ライブラリが利用可能です。次の追加ライブラリもデフォルトで使用できます。


ライブラリ	バージョン
`numpy`	TKTK
`pandas`	TKTK

Artifactリポジトリを介したライブラリの追加¶

Snowflakeのデフォルトアーティファクトリポジトリを使用して、コード実行ツール環境の PyPI からパッケージを取得できます。artifact_repositories キーを SNOWFLAKE.SNOWPARK.PYPI_SHARED_REPOSITORY のエントリを含むリストとしてエージェント仕様の code_execution リソースに追加します。

tool_resources:
  code_execution:
    artifact_repositories:
      - SNOWFLAKE.SNOWPARK.PYPI_SHARED_REPOSITORY

PyPI リポジトリにアクセスするには、ロール SNOWFLAKE.PYPI_REPOSITORY_USER もCortex Agentの所有者に割り当てる必要があります。

重要

これにより、コード実行ツールは、 PyPI で公開されたパッケージを取得するためにアクセスできるようになります。このレベルのアクセスを付与する場合は注意してください。

外部アクセスの有効化¶

ネットワークルールと外部アクセス統合を作成し、エージェント仕様でコード実行ツールがアクセスできる統合に関する情報を提供することで、インターネット経由でコード実行が外部エンドポイントにアクセスできるようにすることができます。

次の例は、新しいネットワークルール（github_access_rule）および外部アクセス統合（github_integration）を作成し、 github.com および HTTP や HTTPS を介していくつかのサブドメインへのアクセスを許可する方法を示しています。

CREATE OR REPLACE NETWORK RULE github_access_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  VALUE_LIST = ('github.com', 'api.github.com', 'raw.githubusercontent.com');

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION github_integration
  ALLOWED_NETWORK_RULES = (github_access_rule)
  ENABLED = true;

外部アクセス統合を有効にするには、エージェント仕様の code_execution リソースに、コード実行ツールがアクセスできる外部アクセス統合のリストを含む external_access_integrations キーを追加します。次のエージェント仕様スニペットの例は、コード実行ツールに github_integration 外部アクセス統合へのアクセスを与えていることを示しています。

tool_resources:
  code_execution:
    external_access_integrations:
      - github_integration

ネットワークルールと外部アクセス統合のセットアップの詳細については、外部アクセス統合の作成と使用をご参照ください。

既知の制限¶

Cortex Agentコード実行ツールには以下の既知の制限があります。

単一セッションの範囲：デフォルトでは、コード実行ツールは現在のセッションのデータにのみアクセスできます。状態は、セッション間や個別の呼び出し間で共有されることはありません。コード実行ツールによって生成された情報を永続化するには、コード実行ツールが読み取りと書き込みアクセスできる、Snowflake上に独自の永続化ストアが必要です。
アクセスの継承：コード実行ツールは、Cortex Agent所有者のロール権限で動作します。コード実行が有効になっているエージェントの所有者ロールが適切にスコープされていることを確認してください。