🔴 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
Questions for maintainers
-
Is google.adk.labs.snowflake the right initial location, or should this land directly under google.adk.integrations.snowflake?
-
Is representing Snowflake-executed tool activity as ADK FunctionCall and FunctionResponse events appropriate for this 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) throughMcpToolset. That path retains the completedCallToolResult, but it represents the result as a single ADKFunctionResponse; the original Cortex event boundaries and timing are not exposed as ADK events.McpToolsetalso 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-specificBaseAgentthat calls the Cortex Agents REST APIs and converts the typed SSE stream into ADK events. The event-conversion approach follows the existingAntigravityAgentprecedent for wrapping an external agent runtime.I propose landing this under
google.adk.labs.snowflake, following the initialAntigravityAgentplacement, because the public API and event mapping may still evolve. I can relocate the draft before merge if maintainers prefergoogle.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 currentctx.user_contentis sent because Snowflake owns the remote conversation history.Emit text and thinking deltas as
partial=Trueevents in SSE streaming mode.Project server-executed tool activity as ADK
FunctionCallandFunctionResponseevents. 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_queriesevent and final content block defined in the generated Cortex Agent OpenAPI and observed during live testing. Progress events are forwarded as non-persistedpartial=Truemetadata events.Treat the final
responseas authoritative. Commit the cursor only whenstatus="completed"andmetadata.assistant_message_idis valid.[DONE]is treated only as an optional compatibility sentinel.cancelledandtimed_outare 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
httpxand Pydantic packages.If the consumer closes the generator and a
run_idis known, the adapter closes the upstream stream and can make one best-effort cancel request. Although cancellation can persist partial output and return anassistant_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
McpToolsetplus 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/docs/guides/labs/snowflake/snowflake_cortex_agent/index.mddocs/guides/README.mdcontributing/samples/integrations/snowflake_cortex_agent/User-facing adk.dev documentation would be proposed separately in the
google/adk-docsrepository.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 completedboth 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
Questions for maintainers
Is
google.adk.labs.snowflakethe right initial location, or should this land directly undergoogle.adk.integrations.snowflake?Is representing Snowflake-executed tool activity as ADK
FunctionCallandFunctionResponseevents appropriate for this adapter?