Secure agents¶

A secure agent is a Cortex Agent whose complete YAML specification is not visible to roles that have only USAGE privilege on the agent. This lets you grant invocation access without granting direct access to potentially business-sensitive configuration through SQL metadata and stage paths. This configuration can include tool definitions, MCP server bindings, orchestration instructions, and other proprietary information. Secure agents follow the same model as secure views, secure functions, and secure procedures in Snowflake.

How secure agents work¶

When you mark an agent as secure, Snowflake applies a visibility rule to every surface that can return the agent specification so only the owner role can view the entire specification. The owner role is considered activated when the agent’s owner role is part of the activated role set for the current session. This matches secure view and secure function semantics: a role with MODIFY or USAGE on a secure agent but without the owner role activated cannot read the specification through any SQL or stage path.

The visibility rule applies to the following surfaces:

Create a secure agent¶

To create a secure agent, include the SECURE modifier or set the SECURE property to TRUE in CREATE AGENT:

CREATE OR REPLACE SECURE AGENT my_sales_agent
  COMMENT = 'Production sales analyst.'
  FROM SPECIFICATION
  $$
  models:
    orchestration: claude-sonnet-4-6
  tools:
    - tool_spec:
        type: "cortex_analyst_text_to_sql"
        name: "RevenueAnalyst"
    - tool_spec:
        type: "cortex_search"
        name: "ProductSearch"
  tool_resources:
    RevenueAnalyst:
      semantic_view: "sales_db.public.revenue_model"
    ProductSearch:
      search_service: "sales_db.public.product_search"
  $$;

Alter the secure status of an existing agent¶

You can mark an existing agent as secure, or remove the secure designation, using ALTER AGENT.

Mark an agent as secure:

ALTER AGENT my_agent SET SECURE = TRUE;

Remove the secure designation:

ALTER AGENT my_agent SET SECURE = FALSE;

REVOKE USAGE ON AGENT my_agent FROM SHARE my_data_share;
REVOKE USAGE ON AGENT my_agent FROM APPLICATION ROLE my_app_role;
ALTER AGENT my_agent SET SECURE = FALSE;

Identify secure agents¶

SHOW AGENTS includes an is_secure column. Secure agents show true in this column.

SHOW AGENTS;

Example output (selected columns):

+-------------------+-----------+-----------+
| name              | owner     | is_secure |
|-------------------+-----------+-----------|
| MY_SALES_AGENT    | SYSADMIN  | true      |
| MY_OTHER_AGENT    | SYSADMIN  | false     |
+-------------------+-----------+-----------+

You can also confirm the secure designation in GET_DDL output. For non-owner sessions, the output includes the SECURE = TRUE property and omits FROM SPECIFICATION and the specification body entirely.

SELECT GET_DDL('CORTEX_AGENT', 'my_sales_agent');

Example output for a non-owner session:

CREATE OR REPLACE AGENT MY_SALES_AGENT
  SECURE = TRUE
  COMMENT = 'Production sales analyst.';

Sharing requirements¶

In accounts where secure agents are required for sharing, only secure agents can be added to shares or exported through Native Apps. Attempting to grant a non-secure agent to a share returns error 093931 (SHARING_UNSECURE_AGENTS_NOT_SUPPORTED).

This requirement exists because sharing multiplies the surfaces through which a specification can be read, including DESCRIBE and GET_DDL in consumer accounts. Marking an agent secure before sharing ensures that spec redaction applies in all consumer contexts.

To share an agent, use the following workflow:

1. Create the agent with the SECURE modifier or SECURE = TRUE property, or run ALTER AGENT <name> SET SECURE = TRUE.
2. Add the agent to the share.
3. If you need to replace the agent definition, preserve the secure designation by using the SECURE modifier or setting SECURE = TRUE. Also specify COPY GRANTS to preserve explicit grants, including grants to shares.

For more information about sharing agents, see Share Cortex Agents.

Security model¶

The following table summarizes what each role can do with a secure agent:

Access control¶

The following privileges are relevant to secure agents. Privilege requirements for invocation and DDL are unchanged from standard agents. The secure designation affects only spec visibility.

Usage notes¶

• Secure agents are consistent with SECURE VIEW, SECURE FUNCTION, and SECURE PROCEDURE semantics. The owner-role check uses the activated role set for the current session, not a static privilege grant.
• Agent invocation via the REST API, DATA_AGENT_RUN (SNOWFLAKE.CORTEX), or tasks is not affected by the secure designation. The specification is loaded with internal system context at runtime.
• DESCRIBE AGENT returns NULL in the agent_spec column for non-owner sessions on secure agents. The agent name, owner, model, and other profile fields remain visible.
• SHOW VERSIONS IN AGENT output depends on the account’s output configuration. When specification output is enabled, non-owner sessions receive an empty agent_spec and a NULL spec_file_path. When specification output is disabled, the output doesn’t include agent_spec, and that setting doesn’t redact spec_file_path.
• Stage reads, including direct downloads of agent_spec.yaml from the agent versioned stage, require the owner role to be activated. A role with only USAGE cannot retrieve the spec file.
• Permanent secure agents support all standard versioning operations (COMMIT, VERSION$N, aliases). Versioning behavior is unchanged; only spec visibility is affected. Temporary agents do not support those operations. See Working with temporary agents.
• Snowflake recommends using the SECURE modifier or setting SECURE = TRUE when granting USAGE on agents whose tool configurations, semantic model references, or orchestration instructions are proprietary.

Error reference¶

Limitations¶

• Partial spec visibility (selectively exposing specific sections of the specification to non-owner roles) is not supported. The specification is either fully visible (owner role activated) or fully redacted.
• The secure designation prevents direct retrieval of the agent specification through metadata surfaces such as DESCRIBE AGENT, GET_DDL, SHOW VERSIONS IN AGENT, and stage reads. It does not guarantee that a user who can invoke the agent cannot use conversational prompts or prompt injection techniques to infer or elicit information about the agent’s instructions, tools, or resources.
• The SECURE modifier and property are supported for Cortex Agent objects only. Snowflake CoWork artifacts and Agent Server objects are out of scope.
• Depending on account sharing controls, you might need to revoke an agent from shares and Native App exports before you can remove its secure designation.
• Replication copies the secure designation. The visibility rules apply in the target account using that account’s activated role context.

Reduce the risk of specification disclosure¶

When you design a secure agent, assume that information available to the model might be disclosed in an agent response. Prompt instructions and filtering can reduce the risk of disclosure, but they cannot eliminate it.

Use the following defense-in-depth practices:

• Don’t include secrets, credentials, or other sensitive values in agent instructions, tool descriptions, or other specification fields.
• Enforce authorization with Snowflake access control, not with agent instructions. Grant the agent and its tools only the privileges required for their intended tasks.
• Consider instructing the agent not to discuss its configuration. Treat this instruction as a mitigation, not as an access control.
• Enable Cortex AI Guardrails to detect and mitigate prompt injection and jailbreak attempts. Guardrails reduce risk but don’t guarantee that specification details cannot be disclosed.
• Monitor agent conversations, traces, and Guardrails activity for attempted or successful disclosure. For more information, see Monitor Cortex Agent requests and Monitor guardrail activity.

Examples¶

Create and verify a secure agent¶

Create a secure agent and confirm the designation appears in SHOW AGENTS and GET_DDL output:

-- Create the secure agent
CREATE OR REPLACE SECURE AGENT my_sales_agent
  COMMENT = 'Production sales analyst.'
  FROM SPECIFICATION
  $$
  models:
    orchestration: claude-sonnet-4-6
  tools:
    - tool_spec:
        type: "cortex_analyst_text_to_sql"
        name: "RevenueAnalyst"
  tool_resources:
    RevenueAnalyst:
      semantic_view: "sales_db.public.revenue_model"
  $$;

-- Verify is_secure = true
SHOW AGENTS LIKE 'my_sales_agent';

-- Confirm GET_DDL shows SECURE = TRUE
SELECT GET_DDL('CORTEX_AGENT', 'my_sales_agent');

Grant invocation access without spec visibility¶

Grant a role the ability to invoke the agent without granting direct access to the specification through metadata surfaces:

-- Grant invocation access to an analyst role
GRANT USAGE ON AGENT my_sales_agent TO ROLE analyst_role;

-- The analyst_role can invoke the agent but cannot read the spec:
-- DESCRIBE AGENT my_sales_agent  ->  agent_spec is NULL
-- GET_DDL(...)                   ->  specification omitted from output

Convert an existing agent to secure and add it to a share¶

Mark an existing agent secure, then add it to a share:

-- Step 1: Mark the agent secure
ALTER AGENT my_agent SET SECURE = TRUE;

-- Step 2: Add to a share
GRANT USAGE ON AGENT my_agent TO SHARE my_data_share;