SnowflakeCortexAgentOperator¶

Use the SnowflakeCortexAgentOperator to execute Snowflake Cortex Agents.

The operator wraps the Snowflake Cortex Agent Run API and executes an existing Cortex Agent. It returns the JSON response payload from the agent, allowing responses to be consumed by downstream Airflow tasks through XCom.

Prerequisite Tasks¶

To use this operator, you must do a few things:

Install the provider package via pip.
pip install 'apache-airflow-providers-snowflake'
Detailed information is available for Installation.
Setup a Snowflake Connection.

Create a Snowflake Cortex Agent. See the Snowflake Cortex Agents documentation.

Using the Operator¶

Use the snowflake_conn_id argument to specify the connection used. If not specified, snowflake_default will be used.

An example usage of the SnowflakeCortexAgentOperator is as follows:

tests/system/snowflake/example_snowflake_cortex_agent.py[source]

run_agent = SnowflakeCortexAgentOperator(
    task_id="run_agent",
    database="DEFAULT_DATABASE",
    schema="DEFAULT_SCHEMA",
    agent_name="default_agent",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "What can you help me with?",
                }
            ],
        }
    ],
)

Note

Parameters passed to the operator take precedence over the corresponding values configured in the Airflow connection metadata, such as database, schema and role.

Authentication¶

SnowflakeCortexAgentHook (and the operator built on it) authenticate according to the connection’s authenticator extra:

OAuth: set authenticator to oauth and configure a refresh token, a client credentials grant, or azure_conn_id, as on the Snowflake connection generally.
PAT (Programmatic Access Token): set authenticator to programmatic_access_token and put the PAT value in the connection’s Password field.
Key-pair JWT: the default when neither of the above is set. Configure private_key_file or private_key_content (optionally with a passphrase in Password), and set Login to the Snowflake user name the key is registered to.

See the Snowflake connection page for the full field reference. A hook instance keeps its resolved key-pair JWT and reuses it within its renewal window instead of signing a new one on every request. This benefits code that calls SnowflakeCortexAgentHook several times on the same instance; the operator makes one request per execute call.