Proposal: Add SnowflakeCortexAgent as a BaseAgent adapter

## 🔴 Required Information

### Is your feature request related to a specific problem?

Snowflake Cortex Agents run their own planner and server-side tools and expose typed SSE events for text, reasoning, tool execution, citations, warnings, tables, charts, suggested queries, thread metadata, and a final aggregated `response`.

ADK currently has no first-party Cortex Agent adapter. The existing documented path uses Snowflake's Managed MCP server (`CORTEX_AGENT_RUN`) through `McpToolset`. That path retains the completed `CallToolResult`, but it represents the result as a single ADK `FunctionResponse`; the original Cortex event boundaries and timing are not exposed as ADK events. `McpToolset` also does not map the Cortex thread, run, and message lifecycle into ADK session state.

Applications therefore cannot progressively render Cortex output, retain its structured tool and citation data as ADK events, or continue a Cortex thread across turns within a persisted ADK session without a custom adapter.

### Describe the Solution You'd Like

Add `SnowflakeCortexAgent`, a provider-specific `BaseAgent` that calls the Cortex Agents REST APIs and converts the typed SSE stream into ADK events. The event-conversion approach follows the existing `AntigravityAgent` precedent for wrapping an external agent runtime.

I propose landing this under `google.adk.labs.snowflake`, following the initial `AntigravityAgent` placement, because the public API and event mapping may still evolve. I can relocate the draft before merge if maintainers prefer `google.adk.integrations.snowflake`.

The initial behavior would be:

* Run as a standalone root agent. Keep a per-agent cursor containing `thread_id`, `parent_message_id`, and the Snowflake resource identity in session state. Only the current `ctx.user_content` is sent because Snowflake owns the remote conversation history.

* Emit text and thinking deltas as `partial=True` events in SSE streaming mode.

* Project server-executed tool activity as ADK `FunctionCall` and `FunctionResponse` events. Function-response payloads are bounded before persistence.

* Retain bounded annotations, warnings, tables, charts, suggested queries, usage, and run metadata on the final event. Suggested queries are collected from Analyst suggestion deltas and from the `response.suggested_queries` event and final content block defined in the [generated Cortex Agent OpenAPI](https://github.com/Snowflake-Labs/sfguide-getting-started-with-cortex-agents/blob/main/cortexagent-run.yaml) and observed during live testing. Progress events are forwarded as non-persisted `partial=True` metadata events.

* Treat the final `response` as authoritative. Commit the cursor only when `status="completed"` and `metadata.assistant_message_id` is valid. `[DONE]` is treated only as an optional compatibility sentinel. `cancelled` and `timed_out` are non-success terminal outcomes and do not produce a completed-turn cursor commit.

* Surface terminal errors without advancing the cursor.

* Add no dependencies beyond the existing `httpx` and Pydantic packages.

If the consumer closes the generator and a `run_id` is known, the adapter closes the upstream stream and can make one best-effort cancel request. Although cancellation can persist partial output and return an `assistant_message_id`, that message is not committed as the next cursor; the next turn intentionally forks from the last successfully completed assistant message. An explicit user-facing cancel and resume API is outside the first PR.

### Impact on your work

This adapter would provide progressive analytics output, structured tool and citation data, and multi-turn continuity through ADK's normal Runner, Event, and Session lifecycle.

### Willingness to contribute

Yes. After creating this issue, I will open a Draft PR containing `Related to #` and then add the PR link here.

---

## 🟡 Recommended Information

### Describe Alternatives You've Considered

* **`McpToolset` plus a callback:** Returns a completed tool result but does not expose Cortex's typed SSE boundaries as ADK events.

* **`AgentTool`:** Currently uses a unary nested-agent result path, so the first PR targets standalone root-agent use.

* **Provider-neutral tool streaming:** Potentially useful, but larger in scope than this provider adapter.

### First PR scope

The Core PR would add:

* `src/google/adk/labs/snowflake/`
* Matching unit tests
* A package README
* `docs/guides/labs/snowflake/snowflake_cortex_agent/index.md`
* An entry in `docs/guides/README.md`
* `contributing/samples/integrations/snowflake_cortex_agent/`

User-facing adk.dev documentation would be proposed separately in the `google/adk-docs` repository.

The initial adapter supports standalone root-agent use only. `AgentTool`, transfer and workflow composition, client-side tools, explicit cancellation and resume APIs, background reconnection, administration APIs, multimodal input, and concurrent turns for the same agent and session are outside the first PR.

Detailed APIs, event tables, authentication, cancellation, truncation, security, test commands, and the masked live trace will be included in the Draft PR description.

### Validation

The draft branch has 150 unit tests using mock SSE streams and `httpx.MockTransport`.

A live test on 2026-09-04 covered thread creation, two-turn continuity, text and thinking deltas, four server-side tool calls, tables, charts, suggested queries, and warnings.

In live testing, a cancel request returned `409 Agent run was already completed` both immediately after closing a foreground stream and after a completed run. The adapter therefore treats this response as a benign best-effort cancellation outcome. Text annotations have not yet been exercised live and are identified as such in the Draft PR.

### Additional Context

* [Cortex Agents Run API](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-run)
* [Use threads with Cortex Agents](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-threads)
* [Snowflake-managed MCP server](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp)
* [Generated Cortex Agent OpenAPI](https://github.com/Snowflake-Labs/sfguide-getting-started-with-cortex-agents/blob/main/cortexagent-run.yaml)
* [AntigravityAgent PR #6040](https://github.com/google/adk-python/pull/6040)
* [AgentTool event propagation issue #3984](https://github.com/google/adk-python/issues/3984)

### Questions for maintainers

1. Is `google.adk.labs.snowflake` the right initial location, or should this land directly under `google.adk.integrations.snowflake`?

2. Is representing Snowflake-executed tool activity as ADK `FunctionCall` and `FunctionResponse` events appropriate for this adapter?