Add Cortex Agent management methods to SnowflakeCortexAgentHook

[SameerMesiah97]

Description

This change extends SnowflakeCortexAgentHook with support for managing Snowflake Cortex Agent Objects.

The hook now exposes methods to describe, list and delete Cortex Agents using the Snowflake Cortex Agent REST API. To support these endpoints, the internal request helper has been updated to accept optional query parameters while continuing to centralize authentication, request execution and error handling.

Rationale

The existing hook supports executing Cortex Agents through run_agent(), but the Snowflake Cortex Agent REST API also provides endpoints for managing Cortex Agent Objects. Exposing these operations through the hook allows users to inspect and manage agents without needing to invoke the REST API directly.

Adding query parameter support to the shared request helper also provides a reusable foundation for additional Cortex Agent management operations in future enhancements.

Tests

Added unit tests verifying that:

• describe_agent() sends the expected request and returns the API response.
• list_agents() correctly forwards optional query parameters and returns the list of agents.
• delete_agent() issues the expected DELETE request, including both values of the if_exists parameter.
• _request() returns {} for successful empty dict responses.
• Cortex Agent methods raise when Snowflake returns an unexpected top-level response shape.

[SameerMesiah97]

Requesting review for this.

[vikramkoka]

cc: @kaxil
Similar to the other PR conversation

[Dev-iL]

Not a big fan of cast. How do we know for sure that this is not a list of dicts? Is it an API contract, or can it be guessed from the combination of input parameters?

I suggest defining overloads for self._request (e.g. one configuration of inputs that returns a dict and one that returns list[dict]), or if that's impossible, something like

response = self._request(...)
if not isinstance(response, dict):
    raise TypeError(f"Expected a dict response, got { type(response).__name__ }")
return response  # guaranteed to be dict now

...and similarly for the other methods.

[Dev-iL]

Just to clarify, this is what I had in mind for the overloads:

from typing import Literal, overload

# 1. Define the overload signature for "POST"
@overload
def make_request(method: Literal["POST"]) -> dict:
    ...

# 2. Define the overload signature for "GET"
@overload
def make_request(method: Literal["GET"]) -> list[dict]:
    ...

# 3. Define the implementation function
def make_request(method: str) -> dict | list[dict]:
    if method == "POST":
        return {"status": "created"}
    elif method == "GET":
        return [{"status": "item1"}, {"status": "item2"}]
    else:
        raise ValueError(f"Unsupported method: {method}")

# --- Usage Example ---

# Type checker knows `res_post` is a `dict`
res_post = make_request("POST")

# Type checker knows `res_get` is a `list[dict]`
res_get = make_request("GET")

[SameerMesiah97]

The type of the response object is not necessarily determined by the HTTP method. I have followed the spirit of your suggestion by defining overloads for the _request method, which uses a response_type parameter to determine the return type.

[ashb]

Please don't merge this just yet - we are looking at unifying this in to common.ai

[SameerMesiah97]

Please don't merge this just yet - we are looking at unifying this in to common.ai

I appreciate the heads up. But would it not take a substantial amount of time for the maintainers to align on the final abstraction? There is also a possibility we may decide against it. I wonder if we could let these PRs merge whilst that discussion continues.