Cortex Agent 代码执行工具¶

Cortex Agent 代码执行是一个内置工具，允许代理在对话期间执行代码。在启用对代码执行工具的访问权限后，您的代理可以执行脚本来处理数据、执行计算和生成可视化内容。默认情况下，代码执行工具在沙盒化的隔离环境中运行，该环境只能访问当前代理会话中的数据。

您可以通过在代理规范中配置代码执行工具来启用它。然后，代理在编排期间根据用户的查询决定何时生成和运行代码。当执行作为代理技能一部分的 Python 脚本时，也会使用代码执行工具。

代码执行的工作原理¶

代理会将代码执行与其他已配置的工具和技能一起使用。在编排期间，代理会评估用户的查询，并判断代码执行是否是最佳方法。如果是，代理会调用代码执行工具。

然后，代理会生成代码并在安全的沙盒中执行它。默认情况下，代码执行工具环境是隔离的，只能访问传入会话的数据。可以在代理规范中授予额外的读取或写入权限。

默认访问范围¶

代码执行工具的沙盒在单个会话期间持续存在。对话上下文中提供的数据是代码执行工具可用的操作数据。沙盒会在会话内的多次执行中保留导入、变量和中间结果。

启用代码执行工具¶

要将代码执行工具与 Cortex Agent 一起使用，代理必须同时具有所需的访问控制权限和描述代码执行工具的代理规范部分。

所需的 Cortex Agent 权限¶

以下对 Cortex Agent 的权限会影响您配置和使用查询代理的能力：


权限	适用场景
USAGE	允许调用代理，包括使用代码执行工具
MODIFY	更改代理规范以启用或配置代码执行工具
OWNERSHIP	完全控制代理配置和使用

代理规范¶

您可以通过在代理规范中添加代码执行工具的资源和配置来启用该工具。

需要在代理规范的 tools 部分添加的工具定义如下：

tools:
  - tool_spec:
    type: code_execution
    name: code_execution

通过在代理规范的 tool_resources 中添加 code_execution 部分来启用该工具：

tool_resources:
  code_execution:

有关代理规范格式的完整信息以及如何修改现有代理规范的说明，请参阅 Configure and interact with Agents。

默认可用库¶

代码执行工具的默认执行环境使用 Python 3.12，并且 Python 标准库可用。默认情况下，以下附加库也可用：


库	版本
`numpy`	TKTK
`pandas`	TKTK

通过 Artifact Repository 添加库¶

您可以使用 Snowflake 默认的 Artifact Repository 从代码执行工具环境中的 PyPI 检索包。将 artifact_repositories 键添加到代理规范中的 code_execution 资源中，作为一个包含 SNOWFLAKE.SNOWPARK.PYPI_SHARED_REPOSITORY 条目的列表：

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

要访问 PyPI 存储库，您还必须将 SNOWFLAKE.PYPI_REPOSITORY_USER 角色授予 Cortex Agent 的所有者。

重要

这将赋予代码执行工具检索发布在 PyPI 上的任何包的权限。授予此级别的访问权限时请务必谨慎。

启用外部访问¶

您可以通过创建网络规则和外部访问集成，然后在代理规范中提供代码执行工具有权访问哪些集成的信息，即可支持代码执行工具访问互联网外部端点。

以下示例演示了如何创建新的网络规则 (github_access_rule) 和外部访问集成 (github_integration) ，以允许通过 HTTP 和 HTTPS 访问 github.com 及其部分子域名：

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;

要启用外部访问集成，请将 external_access_integrations 键添加到代理规范中的 code_execution 资源中，其中包含代码执行工具可以访问的外部访问集成列表。以下代理规范片段示例演示了授予代码执行工具对 github_integration 外部访问集成的访问权限：

tool_resources:
  code_execution:
    external_access_integrations:
      - github_integration

有关设置网络规则和外部访问集成的完整详细信息，请参阅创建和使用外部访问集成。

已知限制¶

Cortex Agent 代码执行工具存在以下已知限制：

单会话范围：默认情况下，代码执行工具只能访问当前会话中的数据。状态不会在会话之间或跨不同调用之间共享。若要持久化保存代码执行工具生成的信息，您需要在 Snowflake 上建立专属的持久化存储，并确保该代码执行工具拥有读写权限。
访问继承：代码执行工具使用 Cortex Agent 所有者的角色权限运行。请确保任何启用了代码执行的代理的所有者角色具有适当的范围限定。