Cortex Agent code execution tool¶

The Cortex Agent code execution is a built-in tool that enables an agent to execute code during a conversation. With access to a code execution tool enabled, your agents can execute scripts to process data, perform calculations, and produce visualizations. By default, the code execution tool runs in a sandboxed, isolated environment that can only access data in the current agent session.

You enable the code execution tool by configuring it in an agent specification. The agent then decides during orchestration when to generate and run code based on the user’s query. The code execution tool is also used when executing Python scripts as part of an agent skill.

How the code execution works¶

The agent uses the code execution alongside other configured tools and skills. During orchestration, the agent evaluates the user’s query and determines whether code execution is the best approach. If so, the agent invokes the code execution tool.

The agent then generates code and executes it in a secure sandbox. By default, the code execution tool environment is isolated and can only access data passed into the session. Additional read or write permissions can be granted in the agent specification.

Default access scope¶

The code execution tool’s sandbox persists for a single session. Data provided in the conversation context is what’s available to the code execution tool for operation. The sandbox persists imports, variables, and intermediate results across multiple executions within the session.

Enabling the code execution tool¶

To use the code execution tool with a Cortex Agent, the agent must have both the required access control permissions and agent specification section describing the code execution tool.

Required Cortex Agent permissions¶

The following permissions on a Cortex Agent affect both your ability to configure and query the agent:


Privilege	Required for
USAGE	Allows invoking the agent, including code execution tool use
MODIFY	Changing an agent specification to enable or configure the code execution tool
OWNERSHIP	Full control over agent configuration and use

Agent specification¶

You enable the code execution tool by adding the resources and configuration for it to an agent specification.

The tool definition to add in the tools section of your agent specification is:

tools:
  - tool_spec:
    type: code_execution
    name: code_execution

Enable the tool by adding a code_execution section to tool_resources in your agent specification:

tool_resources:
  code_execution:

For full information on the agent specification format and instructions on how to modify an existing agent’s specification, see Configure and interact with Agents.

Default available libraries¶

The default execution environment for the code execution tool uses Python 3.12, with the Python standard library available. The following additional libraries are also available by default:


Library	Version
`numpy`	TKTK
`pandas`	TKTK

Adding libraries through Artifact Repository¶

You can use the Snowflake default Artifact Repository to retrieve packages from PyPI in the code execution tool environment. Add the artifact_repositories key to the code_execution resources in your agent specification, as a list containing an entry for SNOWFLAKE.SNOWPARK.PYPI_SHARED_REPOSITORY:

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

To access the PyPI repository, you must also assign the role SNOWFLAKE.PYPI_REPOSITORY_USER to the owner of the Cortex Agent.

Important

This gives the code execution tool access to retrieve any package published on PyPI. Use caution when granting this level of access.

Enabling external access¶

You can enable the code execution to access external endpoints over the internet by creating a network rule and external access integration, and then providing information on which integrations the code execution tool has access to in the agent specification.

The following example demonstrates the creation of a new network rule (github_access_rule) and external access integration (github_integration) allowing access to github.com and some subdomains over HTTP and 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;

To enable external access integrations, add the external_access_integrations key to the code_execution resources in your agent specification, containing a list of external access integrations the code execution tool can access. The following example agent specification snippet demonstrates giving the code execution tool access to the github_integration external access integration:

tool_resources:
  code_execution:
    external_access_integrations:
      - github_integration

For the full details of setting up network rules and external access integrations, see Creating and using an external access integration.

Known limitations¶

Cortex Agent code execution tool is subject to the following known limitations:

Single-session scope: By default, the code execution tool can only access data in the current session. State isn’t shared between sessions or across separate invocations. To persist information produced by the code execution tool, you’ll need your own persistence store on Snowflake that the code execution tool has read and write access to.
Access inheritance: The code execution tool operates with the role privileges of the Cortex Agent owner. Make sure that the owner role of any agent with the code execution enabled is appropriately scoped.