> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nimble Native App

> Install Nimble's Snowflake Native Apps — Search and Agents — connect your API key inside Snowflake, and call live web data from SQL.

Nimble ships two Native Apps on the Snowflake Marketplace. Both run inside your account, call live web data from any worksheet, pipeline, or Snowflake Intelligence agent, and read your Nimble API key from a Snowflake Secret you control. They share the same one-time account setup, so connect your key once and use whichever app you install.

## Choose your app

<CardGroup cols={2}>
  <Card title="Nimble Search" icon="magnifying-glass" href="#nimble-search">
    Live web search and AI-synthesized answers. Procedures: `NIMBLE_SEARCH`, `NIMBLE_ANSWER`.
  </Card>

  <Card title="Nimble Agents" icon="robot" href="#nimble-agents">
    Site-specific extraction (Amazon, Google, Walmart, Maps, and hundreds more). Procedures: `NIMBLE_AGENT_RUN`, `LIST_AGENTS`, `DESCRIBE_AGENT`.
  </Card>
</CardGroup>

Both apps install in one click from the Marketplace, ship a guided Streamlit setup screen, and keep your key inside your account — the app reads it from a Snowflake Secret at call time, and only authorized outbound calls reach Nimble.

## Prerequisites

* `ACCOUNTADMIN` role (or a role that can create applications, secrets, network rules, and external access integrations)
* A warehouse to run statements (any size; `XSMALL` is fine)
* A Nimble API key ([sign up free](https://online.nimbleway.com/signup), then copy it from [API keys](https://online.nimbleway.com/settings/api-keys))

## Set up account access

Both apps read your key from a Snowflake **Secret** and reach Nimble through an **External Access Integration**. These are account-level objects shared by either app, so create them once. The per-app sections below just bind to them.

<Steps>
  <Step title="Store your key as a Secret">
    Run this in a worksheet, in any database and schema you own (outside the app). Paste your Nimble API key in place of the placeholder.

    ```sql theme={"system"}
    CREATE DATABASE IF NOT EXISTS nimble_integration;
    CREATE SCHEMA   IF NOT EXISTS nimble_integration.tools;

    CREATE OR REPLACE SECRET nimble_integration.tools.nimble_api_key
      TYPE          = GENERIC_STRING
      SECRET_STRING = 'YOUR_NIMBLE_API_KEY';
    ```
  </Step>

  <Step title="Authorize outbound access to Nimble">
    Create a network rule and an External Access Integration so an app can reach `sdk.nimbleway.com`.

    ```sql theme={"system"}
    CREATE OR REPLACE NETWORK RULE nimble_integration.tools.nimble_api_rule
      MODE       = EGRESS
      TYPE       = HOST_PORT
      VALUE_LIST = ('sdk.nimbleway.com');

    CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION nimble_api_access
      ALLOWED_NETWORK_RULES          = (nimble_integration.tools.nimble_api_rule)
      ALLOWED_AUTHENTICATION_SECRETS = (nimble_integration.tools.nimble_api_key)
      ENABLED                        = TRUE;
    ```
  </Step>
</Steps>

## Nimble Search

Live web search and AI-synthesized answers as stored procedures: ranked web results as a `VARIANT`, or a single sourced answer string.

### Install from Marketplace

Open the [Nimble Search listing on the Snowflake Marketplace](https://app.snowflake.com/marketplace/listing/GZTSZ2BEO2R/nimble-nimble-search).

<Frame caption="The Nimble Search listing on the Snowflake Marketplace">
  <img src="https://mintcdn.com/nimble-f5a8283f/ba1gMWUZbJNSZmCm/images/partnerships/snowflake-native-app-marketplace.png?fit=max&auto=format&n=ba1gMWUZbJNSZmCm&q=85&s=5b72f3fbe73c19f1f94cfe845d46c60f" alt="Nimble Search listing on the Snowflake Marketplace" width="1298" height="198" data-path="images/partnerships/snowflake-native-app-marketplace.png" />
</Frame>

<Steps>
  <Step title="Open the listing">
    In Snowsight, go to **Data Products → Marketplace** and search for **Nimble Search**, or open the [listing](https://app.snowflake.com/marketplace/listing/GZTSZ2BEO2R/nimble-nimble-search) directly.
  </Step>

  <Step title="Get the app">
    Click **Get**. Choose the database name the app installs into (the default is fine) and the role allowed to use it, then confirm. Snowflake installs the application into your account.
  </Step>

  <Step title="Open the setup app">
    From **Data Products → Apps**, open **Nimble Search**. The setup screen lists three steps: connect your API key, approve external access, and create the procedures.

    <Frame caption="The Nimble Search setup app">
      <img src="https://mintcdn.com/nimble-f5a8283f/ba1gMWUZbJNSZmCm/images/partnerships/snowflake-native-app-setup.png?fit=max&auto=format&n=ba1gMWUZbJNSZmCm&q=85&s=2b40debd1d32f978850fe4d022330892" alt="The Nimble Search setup screen with steps to bind the API key, approve external access, and create the procedures" width="624" height="701" data-path="images/partnerships/snowflake-native-app-setup.png" />
    </Frame>
  </Step>
</Steps>

### Connect the app

The Secret and External Access Integration already exist from [Set up account access](#set-up-account-access). Bind both to the app, then create the procedures.

<Steps>
  <Step title="Bind both references in the setup app">
    In the **Nimble Search** setup app:

    * Click **Bind API key secret** and select `nimble_integration.tools.nimble_api_key`.
    * Click **Approve external access** and select `nimble_api_access`.

    Each opens a Snowflake dialog that grants the app scoped access to that one object.
  </Step>

  <Step title="Create the procedures">
    Click **Create / refresh procedures**. This creates `CORE.NIMBLE_SEARCH` and `CORE.NIMBLE_ANSWER` with the references you just bound. When it returns `ok`, the app is ready.
  </Step>
</Steps>

<Note>
  Prefer SQL over the setup screen? See [Set up with SQL](#set-up-with-sql) below for the equivalent statements.
</Note>

### Run it

Replace `nimble_search` with the database name you chose at install if it differs.

#### Get a direct answer

`NIMBLE_ANSWER` returns a single sourced answer string. It is the right shape for a Snowflake Intelligence agent tool.

```sql theme={"system"}
CALL nimble_search.core.nimble_answer('what is the capital of France?');
```

#### Search the web

`NIMBLE_SEARCH` returns a `VARIANT` with `results`, `request_id`, and `total_results`. The arguments are the query, the maximum number of results, and the search depth (`'lite'` or `'deep'`).

```sql theme={"system"}
CALL nimble_search.core.nimble_search('latest AI news', 5, 'lite');
```

#### Flatten results into rows

Run the search, then read its output with `RESULT_SCAN` and `FLATTEN` to get one row per result.

```sql theme={"system"}
CALL nimble_search.core.nimble_search('best espresso machine 2026', 5, 'lite');

SELECT v.value:title::STRING         AS title,
       v.value:url::STRING           AS url,
       v.value:description::STRING   AS description,
       v.value:metadata:position::INT AS position
FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())),
     LATERAL FLATTEN(input => $1:results) v
ORDER BY position;
```

#### Use the answer as a Cortex Agent tool

`CORE.NIMBLE_ANSWER(VARCHAR)` returns a single `STRING`, so it registers cleanly as a Cortex Agent tool. In Snowsight, go to **AI & ML → Agents → your agent → Tools → Add tool** and point it at `nimble_search.core.nimble_answer`. The agent can then pull live web context into its answers.

### Set up with SQL

The setup screen is the fastest path, but every step has a SQL equivalent. After [setting up account access](#set-up-account-access), bind the references and create the procedures directly.

```sql theme={"system"}
CALL nimble_search.config.register_reference(
  'nimble_api_key', 'ADD',
  SYSTEM$REFERENCE('SECRET','NIMBLE_INTEGRATION.TOOLS.NIMBLE_API_KEY','PERSISTENT','READ'));

CALL nimble_search.config.register_reference(
  'nimble_external_access', 'ADD',
  SYSTEM$REFERENCE('EXTERNAL_ACCESS_INTEGRATION','NIMBLE_API_ACCESS','PERSISTENT','USAGE'));

CALL nimble_search.core.create_eai_objects();
```

Both `register_reference` calls return `ok`, and `create_eai_objects` returns `ok` once the procedures exist.

## Nimble Agents

Run [Nimble Web Search Agents](/nimble-sdk/web-tools/extract/template) — site-specific extraction for Amazon, Google, Walmart, Maps, social platforms, and hundreds of community agents — directly from SQL. The app also exposes agent discovery in-warehouse, so you can find agents and inspect their inputs without leaving Snowflake.

### Install from Marketplace

Open the [Nimble Agents listing on the Snowflake Marketplace](https://app.snowflake.com/marketplace/listing/GZTSZ2BEO30/nimble-nimble-web-agents).

<Steps>
  <Step title="Open the listing">
    In Snowsight, go to **Data Products → Marketplace** and search for **Nimble Agents**, or open the [listing](https://app.snowflake.com/marketplace/listing/GZTSZ2BEO30/nimble-nimble-web-agents) directly. Click **Get**.
  </Step>

  <Step title="Grant a warehouse">
    On the app's page, grant it `USAGE` on a warehouse when prompted (or from the setup app). The app needs compute to run its setup screen and procedures.
  </Step>

  <Step title="Open the setup app">
    From **Data Products → Apps**, open **Nimble Agents**. The setup screen covers connecting your API key, approving external access, and creating the procedures.
  </Step>
</Steps>

### Connect the app

The Secret and External Access Integration already exist from [Set up account access](#set-up-account-access). Bind them to the app in order, then create the procedures.

<Steps>
  <Step title="Bind the references in order">
    In the **Nimble Agents** setup app:

    * Click **Bind API key secret** and select `nimble_integration.tools.nimble_api_key`.
    * Then click **Approve external access** (enabled only after the key is bound, so the integration is wired to your secret).
  </Step>

  <Step title="Create the procedures">
    Click **Create / refresh procedures**. When it returns `ok`, the app is ready.
  </Step>
</Steps>

### Discover agents

Nimble's agent catalog is large, so the app exposes discovery directly in SQL — no hunting through docs. Replace `nimble_agents` with the database name you chose at install if it differs.

```sql theme={"system"}
-- Search the catalog (keyword, domain, or vertical)
CALL nimble_agents.core.list_agents('amazon');

-- Flatten the matches into rows
SELECT a.value:name::STRING         AS agent,
       a.value:display_name::STRING AS title,
       a.value:vertical::STRING     AS vertical,
       a.value:description::STRING  AS description
FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())),
     LATERAL FLATTEN(input => $1) a;

-- Inspect one agent's inputs before calling it
CALL nimble_agents.core.describe_agent('amazon_best_sellers');
-- returns input_properties (name, type, required, examples) + output_schema
```

The setup app's **Explore agents** section does the same visually, and links to the [Nimble Agent Gallery](https://online.nimbleway.com/gallery).

### Run an agent

`NIMBLE_AGENT_RUN` returns a `VARIANT` with `status`, `task_id`, `url`, and a `data` payload. There are two forms — short (`agent`, `params`) and full (with optional `country`, `locale`).

```sql theme={"system"}
-- Short form
CALL nimble_agents.core.nimble_agent_run(
  'amazon_best_sellers',
  OBJECT_CONSTRUCT('category', 'appliances'));

-- Full form, with localization
CALL nimble_agents.core.nimble_agent_run(
  'google_search',
  OBJECT_CONSTRUCT('query', 'best espresso machine 2026'),
  'us', 'en-US');

-- Read the parsed payload
SELECT $1:status::STRING  AS status,
       $1:data:parsing    AS parsed
FROM TABLE(RESULT_SCAN(LAST_QUERY_ID()));
```

`agent` is the identifier from `list_agents` (e.g. `google_search`, `amazon_pdp`). `params` is the agent-specific input object — use `describe_agent` to see exactly what each agent expects.

### Handle errors

Every procedure returns a `VARIANT`. On failure — an unknown agent, a missing required parameter, or a transient upstream error — the procedure returns a structured error object instead of raising, so you can branch on it in SQL.

```sql theme={"system"}
CALL nimble_agents.core.describe_agent('does_not_exist');

SELECT $1:status::STRING        AS status,   -- 'error' when the call failed
       $1:error:code::STRING    AS code,     -- e.g. not_found, invalid_input
       $1:error:message::STRING AS message
FROM TABLE(RESULT_SCAN(LAST_QUERY_ID()));
```

Error `code` values: `invalid_input`, `not_found`, `unauthorized`, `rate_limited`, `invalid_request` / `upstream_error`, `timeout`, and `connection_error`.

### Use it from a Cortex Agent

`list_agents`, `describe_agent`, and `nimble_agent_run` register cleanly as Cortex Agent tools, so a Snowflake Intelligence chat can discover the right agent and run it without the user knowing agent names. Wire them in [AI & ML → Agents](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents), pointing each tool at the matching `core` procedure.

## Uninstall

Drop whichever app you installed. Replace the database names if you changed them at install.

```sql theme={"system"}
DROP APPLICATION nimble_search CASCADE;
DROP APPLICATION nimble_agents CASCADE;
```

The Secret, network rule, and External Access Integration you created are not owned by either app and remain in your account.

## Resources

<CardGroup cols={2}>
  <Card title="Nimble Search API" icon="magnifying-glass" href="/nimble-sdk/web-tools/search">
    Request shape, parameters, and response schema behind `NIMBLE_SEARCH`
  </Card>

  <Card title="Nimble Web Search Agents" icon="robot" href="/nimble-sdk/web-tools/extract/template">
    Agent identifiers, parameters, and execution models behind `NIMBLE_AGENT_RUN`
  </Card>

  <Card title="Nimble Agent Gallery" icon="grid" href="https://online.nimbleway.com/gallery">
    Browse every pre-built and community agent
  </Card>

  <Card title="Cortex Agents on Snowflake" icon="robot" href="/integrations/partnerships/snowflake/cortex-agents">
    Wire Nimble tools into a Cortex Agent for Snowflake Intelligence
  </Card>

  <Card title="Snowflake Native Apps" icon="cube" href="https://docs.snowflake.com/en/developer-guide/native-apps/native-apps-about">
    How Snowflake installs and runs apps inside a consumer account
  </Card>

  <Card title="Snowflake External Access Integration" icon="shield-check" href="https://docs.snowflake.com/en/developer-guide/external-network-access/external-network-access-overview">
    How Snowflake gates outbound HTTPS from app procedures
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.