# Cortex Agent Object Management

Use this reference for Cortex Agent object discovery and mutation through REST.

Official docs:

- <https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-rest-api>

## Endpoints

| Goal | Endpoint |
|---|---|
| List agents | `GET /api/v2/databases/{database}/schemas/{schema}/agents` |
| Describe agent | `GET /api/v2/databases/{database}/schemas/{schema}/agents/{name}` |
| Create agent | `POST /api/v2/databases/{database}/schemas/{schema}/agents` |
| Update agent | `PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}` |
| Delete agent | `DELETE /api/v2/databases/{database}/schemas/{schema}/agents/{name}` |

Useful query parameters:

| Endpoint | Parameters |
|---|---|
| List agents | `like`, `fromName`, `showLimit` |
| Create agent | `createMode`: `errorIfExists`, `orReplace`, or `ifNotExists` |
| Delete agent | `ifExists`: `true` or `false` |

## Read-Only Discovery

For list and describe, summarize the account, role, database, schema, and agent
name. For list pagination, preserve Snowflake `Link` response headers when a
follow-up page is needed. Keep returned specifications narrow; agent specs can
reveal tool names, semantic model references, warehouses, instructions, search
filters, and function identifiers.

## Mutations

Create, update, replace, and delete are confirmation-gated. Before mutating,
summarize:

1. Account URL, role, database, schema, and agent name.
2. HTTP method and endpoint.
3. Create mode or delete `ifExists` behavior, if used.
4. Agent profile, instructions, models, orchestration budget, tools, and
   tool_resources with secrets redacted.
5. Expected effect and rollback path.

Wait for explicit confirmation.

# Cortex Agent Runs

Use this reference for Cortex Agent execution through REST.

Official docs:

- <https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-run>
- <https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-threads>
- <https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-threads-rest-api>

## Run Workflow Essentials

For Cortex Agent run workflows, plan the target endpoint, streaming-output
handling, and AUTOCOMMIT requirements before preparing the execution summary.
Existing agent objects run through
`POST /api/v2/databases/{database}/schemas/{schema}/agents/{name}:run`; ad hoc
agents use `POST /api/v2/cortex/agent:run`. Use `Accept: text/event-stream` for
streaming and track `metadata` events because assistant `message_id` values are
needed for threaded follow-ups. The final streamed `response` event contains the
aggregated agent output. If the agent returns `system_execute_sql` blocks,
preserve query IDs and verify the Snowflake session has `AUTOCOMMIT=TRUE`.

## Endpoints

| Goal | Endpoint |
|---|---|
| Run an existing agent object | `POST /api/v2/databases/{database}/schemas/{schema}/agents/{name}:run` |
| Run an ad hoc agent | `POST /api/v2/cortex/agent:run` |
| Create a thread for threaded runs | `POST /api/v2/cortex/threads` |
| Describe a thread and message history | `GET /api/v2/cortex/threads/{id}` |
| List threads for the current user | `GET /api/v2/cortex/threads` |
| Rename a thread | `POST /api/v2/cortex/threads/{id}` |
| Delete a thread | `DELETE /api/v2/cortex/threads/{id}` |

Snowflake documents thread rename as an update operation that uses `POST
/api/v2/cortex/threads/{id}` with a `thread_name` request body. Do not change it
to `PATCH` unless Snowflake updates the Threads API docs.

Requests to the Cortex Agent REST API time out after 15 minutes.

## Request Shape

Common request fields include:

| Field | Notes |
|---|---|
| `thread_id` | Existing conversation thread ID. If used, also pass `parent_message_id`; do not invent `0` as a thread ID. |
| `parent_message_id` | Parent message ID. Use `0` only for the first message in an existing newly created thread. |
| `messages` | Chronological user and assistant messages. For a first-turn non-threaded call, omit thread fields and include the complete history/current user message here. |
| `stream` | Defaults to streaming. Set `false` for a single JSON response. |
| `tool_choice` | Controls automatic, required, or named tool use. |

Ad hoc runs can also include model, instruction, orchestration, tool, and
tool-resource configuration in the request body.

## Threaded REST Runs

For a threaded REST conversation, create a thread first with
`POST /api/v2/cortex/threads`, then pass the returned `thread_id` to
`agent:run`.

- Starting a newly created thread: pass the returned `thread_id`,
  `parent_message_id: 0`, and exactly one user message.
- Continuing a thread: use the assistant `message_id` from a prior streamed
  `metadata` event, or from `GET /api/v2/cortex/threads/{id}`, as the next
  `parent_message_id`.
- The `parent_message_id` for follow-up requests must be an assistant message
  ID, not a user message ID. If assistant metadata is missing after a failed
  turn, continue from the last successful assistant message ID.
- Non-threaded first turns should omit `thread_id` and `parent_message_id` and
  send the conversation history/current user message in `messages`.
- Do not copy examples that use `thread_id: 0` as a placeholder. Use only a
  real thread ID returned by Snowflake.

## Streaming Handling

Use `Accept: text/event-stream` for streaming responses or `Accept:
application/json` with `stream: false` for non-streaming responses. The final
streamed `response` event contains the aggregated agent output. Clients should
tolerate unknown event types. Track `metadata` events because assistant
`message_id` values are needed for follow-up threaded requests.

## SQL Execution Blocks

Cortex Agents that use Cortex Analyst semantic views may return
`system_execute_sql` tool blocks. A successful block includes a generated SQL
statement, query ID, result set, and final SQL. If the block fails with HTTP 400
from Snowflake SQL API while the generated SQL runs manually, check the caller's
session settings first. SQL-backed agent execution requires an autocommit
Snowflake session; application sessions with `AUTOCOMMIT=FALSE` can cause
`AUTOCOMMIT is expected to be true` errors.

Before running, confirm the query, tools, warehouse-backed resources, budget,
streaming mode, and output destination.

# Cortex Agent SQL DDL

Use this reference when the user wants to manage Cortex Agent objects from a
Snowflake SQL worksheet instead of the REST API.

Official docs:

- <https://docs.snowflake.com/en/sql-reference/sql/create-agent>
- <https://docs.snowflake.com/en/sql-reference/sql/alter-agent>
- <https://docs.snowflake.com/en/sql-reference/sql/describe-agent>
- <https://docs.snowflake.com/en/sql-reference/sql/drop-agent>
- <https://docs.snowflake.com/en/sql-reference/sql/show-agents>

## Commands

| Goal | SQL |
|---|---|
| Create agent | `CREATE AGENT <name> FROM SPECIFICATION $$ ... $$` |
| Replace agent | `CREATE OR REPLACE AGENT <name> FROM SPECIFICATION $$ ... $$` |
| Alter metadata | `ALTER AGENT <name> SET ...` |
| Replace live specification | `ALTER AGENT <name> MODIFY LIVE VERSION SET SPECIFICATION = ...` |
| Describe agent | `DESCRIBE AGENT <name>` |
| Show agents | `SHOW AGENTS` |
| Drop agent | `DROP AGENT <name>` |

Agent specifications use YAML and can include models, orchestration budgets,
instructions, tools, and `tool_resources`. Treat the specification as sensitive
because it can reveal semantic views, Cortex Search services, warehouses,
filters, functions, and instructions.

## Guardrails

Before create, replace, alter, or drop:

1. Confirm database, schema, role, warehouse, and agent name.
2. Confirm the exact SQL command class and whether it replaces or drops an
   existing object.
3. Review the YAML specification with secrets, filters, warehouse details, and
   implementation identifiers redacted as needed.
4. Confirm privileges such as `CREATE AGENT` on the schema and `USAGE` on
   referenced database, schema, table, Cortex Search service, semantic view, and
   agent objects.
5. Wait for explicit confirmation and keep a rollback plan.

Do not use both `OR REPLACE` and `IF NOT EXISTS`; Snowflake documents them as
mutually exclusive for `CREATE AGENT`.

When modifying the live version specification, include the full intended
specification; Snowflake replaces the existing specification, and omitted fields
are removed.

# DATA_AGENT_RUN SQL Wrapper

Use this reference when the user wants to run a Cortex Agent from Snowflake SQL
instead of using the REST API.

Official docs:

- <https://docs.snowflake.com/en/sql-reference/functions/data_agent_run-snowflake-cortex>

`SNOWFLAKE.CORTEX.DATA_AGENT_RUN` is a utility wrapper around the Cortex Agents
Run API. Snowflake recommends the streaming REST API for most application
integrations. The SQL function returns a non-streaming JSON string.

## Session Requirements

Run the wrapper in a Snowflake session with `AUTOCOMMIT=TRUE`. Cortex Agent
tools that execute generated SQL use Snowflake's SQL API internally, and that
API rejects sessions where autocommit is false. In SQLAlchemy or application
frameworks that wrap statements in transactions, check the session parameter
before blaming the semantic view or generated SQL.

```sql
SHOW PARAMETERS LIKE 'AUTOCOMMIT' IN SESSION;
```

If the wrapper response contains a `system_execute_sql` error like HTTP 400,
or error code `391913` with `AUTOCOMMIT is expected to be true`, rerun from an
autocommit Snowflake connector/session or configure the caller to avoid a
transaction around `DATA_AGENT_RUN`.

## First-Turn Pattern

For a one-off or first-turn SQL wrapper call, do not invent a `thread_id`.
Provide the complete message history in `messages`. Only pass `thread_id` and
`parent_message_id` when continuing an existing thread whose IDs were created or
returned by Snowflake.

```sql
SELECT TRY_PARSE_JSON(
  SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
    'MY_DB.MY_SCHEMA.MY_AGENT',
    $${
      "messages": [
        {
          "role": "user",
          "content": [
            { "type": "text", "text": "What are the top product types?" }
          ]
        }
      ]
    }$$
  )
) AS resp;
```

## Threaded Pattern

When using a persisted thread, create the thread first, pass the returned
`thread_id`, and use `parent_message_id: 0` only for the first message in that
existing thread. Snowflake currently documents `thread_id` as an integer; pass
the value exactly as returned by Snowflake.

```sql
SELECT TRY_PARSE_JSON(
  SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
    'MY_DB.MY_SCHEMA.MY_AGENT',
    $${
      "thread_id": 1234,
      "parent_message_id": 0,
      "messages": [
        {
          "role": "user",
          "content": [
            { "type": "text", "text": "What are the top product types?" }
          ]
        }
      ]
    }$$
  )
) AS resp;
```

Before running, confirm the fully qualified agent name, request body, warehouse
and role context, expected data exposure, and result handling plan.