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 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 #<issue-number> 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
• Use threads with Cortex Agents
• Snowflake-managed MCP server
• Generated Cortex Agent OpenAPI
• AntigravityAgent PR #6040
• AgentTool event propagation issue #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?