Align Snowflake Cortex Agent hook with the Common AI managed-agent contract

[SameerMesiah97]

Description

This change aligns SnowflakeCortexAgentHook with the BaseManagedAgentHook contract introduced in PR #73532.

The hook now implements resolve_agent(), get_agent_capabilities() and invoke_agent(), allowing Cortex Agents to be consumed through the Common AI managed-agent interface. Invocation delegates to the existing run_agent() method and returns a standardized response containing answer text and the raw Snowflake payload.

Rationale

The common contract allows shared consumers, such as ManagedAgentToolset and failover clients, to invoke Cortex Agents without implementing Snowflake-specific integration logic.

Adopting the contract on the existing hook keeps connection handling, authentication and API invocation in one place.

Tests

Added unit tests verifying that:

• Prompts, timeouts and tool selection reach the HTTP request, and responses preserve answer text and the raw payload.
• The hook remains usable without Common AI and reports the missing dependency for managed-agent methods.
• Valid agent identifiers are normalized without making HTTP requests.
• Malformed agent identifiers are rejected before making HTTP requests.
• Capability reporting returns the supported features without making HTTP requests.
• Message history is converted correctly without modifying the caller’s input.
• Unsupported session IDs are rejected before invocation.
• Reserved and unsupported vendor options are rejected before invocation.
• Terminal HTTP failures are translated into ManagedAgentInvocationError, while other HTTP errors propagate unchanged.
• Connection errors and read timeouts propagate unchanged.
• JSON decoding failures are translated into terminal invocation errors.
• Unexpected top-level response types are rejected.
• Malformed response content is rejected.

Notes

The managed-agent adapter is stateless and supports tool_choice as its only vendor option. Thread management remains available through run_agent().

Common AI support is optional through the Snowflake provider’s common.ai extra. Its minimum dependency is raised to 0.11.0, which introduces BaseManagedAgentHook and has not yet been released. Installing this extra from released packages therefore requires Common AI 0.11.0 to be published.

Documentation

The hook docstring describes the Common AI integration, supported inputs and stateless behaviour.

Backwards Compatibility

The existing Snowflake-specific methods retain their current behaviour. Error translation applies only to the new managed-agent invocation method, and the hook can still be imported and used without Common AI installed.

Users installing the common.ai extra will require Common AI 0.11.0 or later.

Was generative AI tooling used to co-author this PR?

• Yes (please specify the tool below)

Generated-by: [GPT 6.1] following the guidelines