feat(tools): add SnowflakeCortexAgentTool for Cortex Agents API (closes #5732)

[devin-ai-integration]

Summary

Closes #5732.

Adds SnowflakeCortexAgentTool, a first-class CrewAI tool that wraps the Snowflake Cortex Agents REST API. A CrewAI agent can hand off a natural language data question to a governed Cortex Agent inside Snowflake instead of writing raw SQL or picking between retrieval (Cortex Search) and text-to-SQL (Cortex Analyst) itself — all of that planning happens inside Snowflake's secure perimeter and only the final answer is returned for downstream steps.

Why this is useful (per the issue):

• Keeps semantic models, RBAC, and governance in Snowflake.
• Gets the quality of Cortex Analyst's text-to-SQL on structured data and Cortex Search's retrieval on unstructured data.
• Lets the Cortex Agent reflect across both tool families and pick the right one — the CrewAI agent simply chooses to delegate when the question is best answered with Snowflake data.

Implementation details:

• New tool at lib/crewai-tools/src/crewai_tools/tools/snowflake_cortex_agent_tool/ with module README.
• Supports both Cortex Agents Run API endpoints:
  • agent object: POST /api/v2/databases/{db}/schemas/{schema}/agents/{name}:run when database, snowflake_schema, and agent_name are all provided.
  • inline: POST /api/v2/cortex/agent:run when tools (and optionally tool_resources, models, instructions, orchestration) are provided.
• Bearer-token auth via auth_token or the SNOWFLAKE_CORTEX_AGENT_TOKEN env var (PAT, OAuth, or JWT). Account from account or SNOWFLAKE_ACCOUNT. Optional host override for private link.
• Sends stream: false and parses the JSON response. Concatenates all content[].text items as the answer; falls back to the full JSON when only tool calls/citations are present so the calling agent still has something useful.
• HTTP errors and requests.RequestException are returned as strings starting with Snowflake Cortex Agent returned HTTP … / Error calling Snowflake Cortex Agent … so the calling agent can react instead of crashing.
• Registered in crewai_tools.__init__ and crewai_tools.tools.__init__. tool.specs.json is regenerated automatically by the existing generate-tool-specs.yml workflow, so it is intentionally not edited in this PR.
• 17 unit tests covering credential validation, URL building (agent object vs inline, host override, env-var fallback), payload shape, success/error paths, and top-level export. All requests calls are mocked — no network access in tests.

Example usage:

from crewai_tools import SnowflakeCortexAgentTool

tool = SnowflakeCortexAgentTool(
    account="myorg-myaccount",
    auth_token="<programmatic-access-token>",
    database="MY_DB",
    snowflake_schema="MY_SCHEMA",
    agent_name="SALES_AGENT",
)

answer = tool.run(query="What was total revenue last quarter, by region?")

Review & Testing Checklist for Human

• Verify the tool actually works against a real Snowflake Cortex Agent (PAT auth, agent-object endpoint). The unit tests fully mock requests.Session.post, so they validate request shape and response handling but not the live API contract.
• Confirm the response parsing covers the response shape your account returns. The implementation extracts content[].text items and joins them with newlines; if your agent emits citations or tool-call items only, the tool falls back to returning the full JSON — check whether you'd prefer a different default.
• Confirm the auth model fits your deployment. The tool uses a single bearer token. If you primarily use Snowflake-driver key-pair JWTs, you may want to pre-mint a JWT and pass it in via auth_token, or extend the tool with a JWT-from-private-key path similar to SnowflakeSearchTool.
• Sanity-check the env var names (SNOWFLAKE_CORTEX_AGENT_TOKEN, SNOWFLAKE_ACCOUNT). I picked SNOWFLAKE_CORTEX_AGENT_TOKEN to avoid colliding with anything the existing SnowflakeSearchTool may use.

Suggested test plan:

1. Create a Snowflake PAT with the SNOWFLAKE.CORTEX_AGENT_USER (or SNOWFLAKE.CORTEX_USER) role granted and a network policy attached.
2. Either (a) create a Cortex Agent object in DB.SCHEMA.NAME referencing a Cortex Analyst semantic model and/or a Cortex Search service, or (b) skip the agent object and use the inline tools=[…] form shown in the README.
3. Instantiate the tool with account, auth_token, and either the database/snowflake_schema/agent_name triple or tools/tool_resources.
4. Call tool.run(query="…") with a representative question and confirm a sensible textual answer comes back.

Notes

• The deprecated crewAIInc/crewAI-tools repo was not touched; per its README this work belongs in lib/crewai-tools/ of the monorepo.
• I did not regenerate lib/crewai-tools/tool.specs.json; the Generate Tool Specifications workflow will commit the regenerated file automatically once this PR is opened. I verified locally that ToolSpecExtractor produces a complete spec for SnowflakeCortexAgentTool (humanized name Snowflake Cortex Agent, single query run param, env vars listed, package_dependencies = ["requests"]).
• No new optional dependency is added — the tool only uses requests, which is already a hard dep of crewai-tools.

Link to Devin session: https://app.devin.ai/sessions/a7c5b5ee33ee431eb39f408d99bb248a

[devin-ai-integration]

Prompt hidden (unlisted session)

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring