Snowflake Cortex Agent (A2A)

The gateway bridges a Snowflake Cortex Agent to the A2A protocol. You register the agent once, and ForceAI signs each call (PAT or key-pair JWT), invokes the Cortex agents/{name}:run REST API, and returns the reply. This guide covers the Snowflake-side setup, the two auth modes, and the registration payload

Prerequisites (Snowflake side)

A deployed Cortex Agent

Create the agent in Snowsight or with CREATE AGENT. Find its fully-qualified name with SHOW AGENTS IN ACCOUNT; you need the database, schema, and agent name

The account URL

Run SELECT SYSTEM$ALLOWLIST(); and take the host of type SNOWFLAKE_DEPLOYMENT_REGIONLESS (or SNOWFLAKE_DEPLOYMENT), then prefix https://. Do not use the bare account-locator host; it returns an HTML “File not found” and the call will fail

Grant the calling role access

Grant the role behind your PAT or key-pair user: USAGE on the database, schema, and agent; USAGE and READ on the semantic-model stage; USAGE on the warehouse; and SELECT on the tables the agent queries

Put the warehouse in the agent spec

The Analyst tool runs SQL using the warehouse named in the agent spec’s tool_resources.<analyst_tool>.execution_environment, not the user’s default warehouse. Set it there or Analyst queries fail

PAT auth also requires a network policy on the user or account that allows the gateway’s egress IP, or Snowflake rejects the token with error 390432. Key-pair JWT auth does not need a network policy, which is why it is the better choice for a hosted gateway

Auth modes

PAT (simplest)
Key-pair JWT (recommended for hosting)

Create a Programmatic Access Token for the calling user. The gateway sends it as Authorization: Bearer <pat> with X-Snowflake-Authorization-Token-Type: PROGRAMMATIC_ACCESS_TOKEN. Requires a network policy covering the gateway IP

Generate an RSA key pair and register the public key: ALTER USER <user> SET RSA_PUBLIC_KEY='<base64 pubkey>'. The gateway mints a short-lived RS256 JWT per call. No network policy needed. Supply the unencrypted PKCS8 private key PEM at registration

Register the agent

curl -X POST https://YOUR_GATEWAY_DOMAIN/v1/agents \
  -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{
    "agent_name": "sales-analyst",
    "agent_card_params": {
      "protocolVersion": "0.3", "name": "Sales Analyst",
      "description": "Snowflake Cortex sales analyst agent",
      "url": "https://myorg-myaccount.snowflakecomputing.com/",
      "capabilities": { "streaming": false },
      "defaultInputModes": ["text"], "defaultOutputModes": ["text"],
      "skills": [{ "id": "analyze", "name": "Analyze", "description": "sales analytics", "tags": ["snowflake"] }]
    },
    "forceai_params": {
      "model": "snowflake_cortex_agents/SALES_ANALYST_AGENT",
      "custom_llm_provider": "snowflake_cortex_agents",
      "snowflake_account_url": "https://myorg-myaccount.snowflakecomputing.com",
      "snowflake_database": "SALES_DB",
      "snowflake_schema": "PUBLIC",
      "snowflake_agent_name": "SALES_ANALYST_AGENT",
      "snowflake_auth_mode": "pat",
      "snowflake_pat": "<PAT>"
    }
  }'

"forceai_params": {
  "model": "snowflake_cortex_agents/SALES_ANALYST_AGENT",
  "custom_llm_provider": "snowflake_cortex_agents",
  "snowflake_account_url": "https://myorg-myaccount.snowflakecomputing.com",
  "snowflake_database": "SALES_DB",
  "snowflake_schema": "PUBLIC",
  "snowflake_agent_name": "SALES_ANALYST_AGENT",
  "snowflake_auth_mode": "keypair_jwt",
  "snowflake_account_locator": "MYORG-MYACCOUNT",
  "snowflake_user": "FORCEAI_SVC",
  "snowflake_private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
}

Or use the dashboard: Agentic -> Agents -> Add New Agent, pick Snowflake Cortex Agents, and fill the same fields

Fields

string

required

The regionless deployment host from SYSTEM$ALLOWLIST(), with https://

string

required

The fully-qualified Cortex agent. snowflake_agent_name also fills the model template snowflake_cortex_agents/{name}

string

default:"pat"

pat or keypair_jwt

string

Required in PAT mode

string

Required in key-pair mode. Private key is an unencrypted PKCS8 PEM

Approve and invoke

# Approve
curl -X POST https://YOUR_GATEWAY_DOMAIN/v1/agents/{agent_id}/approve \
  -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" -d '{"reason":"onboard"}'

# Invoke (reload the gateway first on docker-compose)
curl -X POST https://YOUR_GATEWAY_DOMAIN/v1/a2a/{agent_id}/message/send \
  -H "Authorization: Bearer $AGENT_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"message/send",
       "params":{"message":{"role":"user","parts":[{"kind":"text","text":"Top 5 customers by revenue?"}]}}}'

Troubleshooting

Snowflake error	Cause
`390432`	PAT rejected; add a network policy covering the gateway IP, or use key-pair JWT
`399513`	Missing `USAGE` grants on the database / schema / agent
`399504`	Missing stage grants (`USAGE` + `READ`) on the semantic-model stage
HTML “File not found”	Wrong host; use the regionless deployment host from `SYSTEM$ALLOWLIST()`

Get started

LLM providers

A2A agents

Skills

Knowledge Catalog

Single sign-on

Admin settings

Tools

Snowflake Cortex Agent (A2A)

Prerequisites (Snowflake side)

Auth modes

Register the agent

Fields

Approve and invoke

Troubleshooting

​Prerequisites (Snowflake side)

​Auth modes

​Register the agent

​Fields

​Approve and invoke

​Troubleshooting

Prerequisites (Snowflake side)

Auth modes

Register the agent

Fields

Approve and invoke

Troubleshooting