Call a Snowflake CoWork profile from the Cortex Agents API¶

Call a profile with the Cortex Agents Run API or DATA_AGENT_RUN. It doesn’t need to be attached to the Snowflake CoWork object.

Before you begin¶

• Each agent_router tool needs a tool_resources entry keyed by its tool name. Without that entry, the API returns error 399518. Set subagents: [] in the entry for direct answers without routing, or list the agents to route to, as shown in step 3 of Migrate manually. The same list controls routing in Snowflake CoWork. For how the list affects access, see Choose which agents a profile routes to.
• The calling role needs one of the API access roles for Cortex Agents, plus USAGE on the SNOWFLAKE_INTELLIGENCE database, the SNOWFLAKE_INTELLIGENCE.PROFILES schema, and the profile.

Call the profile¶

Set $SNOWFLAKE_ACCOUNT_BASE_URL to your account URL and $PAT to your programmatic access token. Replace <profile_name> and <role_name>:

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/SNOWFLAKE_INTELLIGENCE/schemas/PROFILES/agents/<profile_name>:run" \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $PAT" \
  --header 'X-Snowflake-Role: <role_name>' \
  --data '{
    "stream": false,
    "messages": [
      { "role": "user", "content": [{ "type": "text", "text": "How many deals closed last quarter?" }] }
    ]
  }'

From SQL:

SELECT TRY_PARSE_JSON(SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
  'SNOWFLAKE_INTELLIGENCE.PROFILES.<profile_name>',
  $${ "messages": [{ "role": "user", "content": [{ "type": "text", "text": "How many deals closed last quarter?" }] }] }$$
)) AS response;

See which agent answered¶

Each time the profile routes the question, the response includes a tool_use item of type agent_router. In its input, subagent_name is the agent that received the question, as in the following trimmed example:

{
  "type": "tool_use",
  "tool_use": {
    "type": "agent_router",
    "input": { "subagent_name": "MY_DB.MY_SCHEMA.SALES_AGENT", "display_name": "Sales" }
  }
}

With orchestration.tool_not_accessible: accept, inaccessible subagents are skipped with warning 399569. With reject, they fail the request. For more information, see Inaccessible tool handling.

Call the profile from an MCP client¶

To reach a profile from an MCP client such as Claude, expose it as a CORTEX_AGENT_RUN tool on an MCP server. The profile is an agent, so you set identifier to its fully qualified name:

CREATE OR REPLACE MCP SERVER <database_name>.<schema_name>.<server_name>
  FROM SPECIFICATION $$
  tools:
    - title: "Company profile"
      name: "company_profile"
      type: "CORTEX_AGENT_RUN"
      identifier: "SNOWFLAKE_INTELLIGENCE.PROFILES.<profile_name>"
      description: "Use this profile for questions about company data."
  $$;

An MCP call has the same requirement as an API call. The profile needs a tool_resources entry with a subagents list, as described earlier on this page. The role that the client connects with needs USAGE on the MCP server and on the profile. For the full list of grants, see Access control.