# Connecting Databricks Genie Agents to Treasure AI CDP

[Databricks Genie Agents](https://docs.databricks.com/aws/en/genie-agents/) let business users ask natural-language questions about data in Databricks. By connecting a Genie Agent to the Treasure AI CDP API through Unity Catalog functions, business users can inspect parent segments, child segments, and journeys directly from Databricks, without leaving Databricks or seeing a Treasure AI API key.

In this integration pattern, the model, the API key, and every API call stay inside Databricks. Genie's AI usage and the SQL warehouse time are billed by Databricks. Treasure AI serves standard CDP REST API calls, so no Treasure AI Credits are used.

This guide is for the Databricks administrator who sets up the agent. To connect business users to Treasure AI Studio agents and Actions instead, see [Connecting Databricks Genie One to Treasure AI Studio](/products/headless/databricks-genie-one).

## How the Integration Works

When a business user asks a question in the Genie Agent, Genie writes SQL against the view `td_parent_segments_v` or calls one of the `td_*` table functions. Each table function runs the Python function `td_cdp_fetch` on the agent's serverless SQL warehouse. `td_cdp_fetch` sends an HTTPS `GET` request to the Treasure AI CDP API with the Treasure AI API key and returns JSON, which the table functions turn into rows. Genie then writes the answer.

| Databricks Object  | Name  | Purpose  |
|  --- | --- | --- |
| **Workspace preview** | Enable networking for isolated workloads in serverless SQL warehouses | Lets Python functions on serverless SQL warehouses make outbound HTTPS calls |
| **Catalog** | `treasure_ai` | Holds the two schemas below |
| **Schema** | `treasure_ai.genie` | Holds the functions and the view that Genie users can run |
| **Schema** | `treasure_ai.secrets` | Holds only the API key. Genie users get no access to it |
| **Secret** | `treasure_ai.secrets.td_api_key` | Stores the Treasure AI API key so that users never see it |
| **Python function** | `td_cdp_fetch` | Calls the CDP API and returns a JSON array |
| **SQL table functions** | `td_parent_segments`, `td_segments`, `td_journeys` | Turn the JSON into rows that Genie can filter, sort, and chart |
| **View** | `td_parent_segments_v` | The Genie Agent's table source. Every query calls Treasure AI live |
| **Account group** | `GENIE_USERS` (your group name) | The business users who can use the agent |
| **Genie Agent** | `Treasure AI CDP` | The agent that business users chat with |


## Prerequisites

- **Databricks workspace**: Unity Catalog, Genie Agents, and a serverless SQL warehouse. This guide uses `EMEA Starter Warehouse`; use your own.
- **Databricks permissions**: `CREATE CATALOG` on the metastore, and a workspace administrator who can turn on a workspace preview in Phase 1, Step 2.
- **Dedicated Treasure AI user**: A Treasure AI user that can see only the parent segments the Genie Agent should answer about. Every Genie user acts as this one user.
- **Account group**: A Databricks account group that holds the business users who will use the agent. This guide calls it `GENIE_USERS`.
- **Regional CDP API host**: The CDP API host for your Treasure AI region:


| Region  | `CDP_HOST` URL  |
|  --- | --- |
| **US (AWS us-east-1)** | `https://api-cdp.treasuredata.com` |
| **EU (eu01)** | `https://api-cdp.eu01.treasuredata.com` |
| **Japan (ap01)** | `https://api-cdp.treasuredata.co.jp` |
| **Asia Pacific (ap02)** | `https://api-cdp.ap02.treasuredata.com` |


## Phase 1: Configure Treasure AI API Access in Databricks

In this phase, you generate a Treasure AI API key, store it in a Unity Catalog secret, and create the functions and the view that call the CDP API. Run the SQL in Steps 4 to 9 in one SQL worksheet.

### Step 1: Generate a Treasure AI Master API Key

1. Sign in to the [Treasure AI Console](/tools/td-console/log-in-to-td-console) as the dedicated Treasure AI user.
2. Navigate to **My Settings → API Keys** and select **Add API Key** (see [Getting Your API Keys](/products/my-settings/getting-your-api-keys)).
3. Select **Master Key** as the key type, save the key, and copy the value (`<account_id>/<hex_secret>`).


Scope the dedicated user and rotate the key regularly
The Treasure AI CDP API requires a Master Key to read parent segments, segments, and journeys. A write-only key can't read data. A Master Key can perform every operation that its user is allowed to perform, so always issue it under a dedicated Treasure AI user whose access is limited to the parent segments the Genie Agent should answer about. Store it only in the Unity Catalog secret, and rotate it on a regular schedule.

### Step 2: Allow Outbound Networking from Serverless SQL Warehouses

Python functions on serverless SQL warehouses can't reach the internet until a workspace administrator turns on a preview. Turn it on first, because it can take up to 15 minutes to apply.

1. Open the user menu in the upper right and select **Previews**.
2. Find **Enable networking for isolated workloads in serverless SQL warehouses**. It is off by default.
3. Switch it **On**. A confirmation says that the preview has been enabled.


The preview lets functions on serverless SQL warehouses call any host. If the workspace has a serverless egress policy, it must allow the CDP API host for your region.

### Step 3: Open a SQL Worksheet

Select **+ New → Query** to open a new SQL editor tab. In the warehouse selector, pick your serverless SQL warehouse, for example `EMEA Starter Warehouse`.

### Step 4: Create the Catalog and Schemas

In the worksheet, run:

```sql
-- Needs CREATE CATALOG on the metastore. If your metastore has no default
-- storage, add: MANAGED LOCATION 's3://<bucket>/<path>'
CREATE CATALOG IF NOT EXISTS treasure_ai;

-- Holds the functions and view that Genie users can run.
CREATE SCHEMA IF NOT EXISTS treasure_ai.genie;

-- Holds only the API key. Never grant Genie users anything on this schema.
CREATE SCHEMA IF NOT EXISTS treasure_ai.secrets;
```

The `treasure_ai` catalog appears in **Catalog**, with the `genie` and `secrets` schemas inside it.

### Step 5: Store the API Key as a Unity Catalog Secret

Create the secret in the UI so that the key never appears in SQL or in the query history.

1. In **Catalog**, open `treasure_ai` → `secrets`, and select **Create → Secret**.
2. Enter `td_api_key` as the **Secret name**, and paste the Master API key from Step 1 as the **Secret value**.
3. Under **Choose catalog and schema**, select `treasure_ai` and `secrets`, and select **Create**.


### Step 6: Create the Function That Calls Treasure AI

`td_cdp_fetch` is a Python function with three read-only actions:

| Action  | Input  | Treasure AI API Calls  |
|  --- | --- | --- |
| `list_parent_segments` | None | `GET /entities/parent_segments` |
| `list_segments` | `parent_segment_id` | `GET /audiences/{id}/segments` |
| `list_journeys` | `parent_segment_id` | `GET /audiences/{id}/folders`, then `GET /entities/journeys?folder_id=…` for each folder |


Treasure AI lists journeys per folder, so `list_journeys` reads the parent segment's folders first and removes duplicates by journey ID.

The CDP API accepts only the `Authorization: TD1 <key>` header. A Unity Catalog HTTP connection with `http_request()` sends `Bearer <token>`, which the CDP API rejects with HTTP `401`, so this function builds the header in Python instead. The `SECRETS` clause lets the function read the key with its owner's rights. Callers need only `EXECUTE` and never see the key. The function's owner needs `READ SECRET` on the secret.

Before you run the statement, set `CDP_HOST` to the CDP API host for your region from [Prerequisites](#prerequisites).

```sql
CREATE OR REPLACE FUNCTION treasure_ai.genie.td_cdp_fetch(
  action STRING,
  parent_segment_id STRING
)
RETURNS STRING
COMMENT 'Read-only call to the Treasure AI CDP API. Returns a JSON array. Used by the td_* table functions.'
LANGUAGE PYTHON
HANDLER 'main'
SECRETS (treasure_ai.secrets.td_api_key)
ENVIRONMENT (environment_version = '6')
AS $$
import json
import re
import urllib.error
import urllib.request

from databricks.secrets import get

CDP_HOST = "https://api-cdp.treasuredata.com"
TIMEOUT_SECONDS = 30

HTTP_HINTS = {
    401: "API key rejected (wrong key, wrong region, or a write-only key)",
    403: "the Treasure user behind the API key lacks permission",
    404: "not found (check the parent segment id)",
}


def _get(path):
    key = get(catalog="treasure_ai", schema="secrets", key="td_api_key")
    req = urllib.request.Request(
        CDP_HOST + path,
        headers={"Authorization": "TD1 " + key, "Accept": "application/json"},
    )
    try:
        with urllib.request.urlopen(req, timeout=TIMEOUT_SECONDS) as resp:
            return json.load(resp)
    except urllib.error.HTTPError as e:
        raise RuntimeError(
            f"Treasure API HTTP {e.code}: {HTTP_HINTS.get(e.code, 'request failed')}"
        ) from None


def _parent_id(parent_segment_id):
    pid = (parent_segment_id or "").strip()
    if not re.fullmatch(r"\d+", pid):
        raise ValueError("parent_segment_id must be a number. Look it up in td_parent_segments_v first.")
    return pid


def _list_parent_segments(_parent_segment_id):
    return [
        {
            "parent_segment_id": str(r.get("id")),
            "name": a.get("name"),
            "description": a.get("description"),
            "population": a.get("population"),
            "updated_at": a.get("updatedAt"),
        }
        for r in _get("/entities/parent_segments").get("data") or []
        for a in [r.get("attributes") or {}]
    ]


def _list_segments(parent_segment_id):
    pid = _parent_id(parent_segment_id)
    return [
        {
            "segment_id": str(r.get("id")),
            "name": r.get("name"),
            "description": r.get("description"),
            "population": r.get("population"),
            "kind": r.get("kind"),
            "updated_at": r.get("updatedAt"),
        }
        for r in _get("/audiences/" + pid + "/segments")
    ]


def _list_journeys(parent_segment_id):
    pid = _parent_id(parent_segment_id)
    results = {}
    for folder in _get("/audiences/" + pid + "/folders"):
        body = _get("/entities/journeys?folder_id=" + str(folder.get("id")))
        for item in body.get("data") or []:
            a = item.get("attributes") or {}
            results[item.get("id")] = {
                "journey_id": item.get("id"),
                "name": a.get("name"),
                "state": a.get("state"),
                "paused": a.get("paused"),
                "parent_segment_id": a.get("audienceId"),
                "launched_at": a.get("launchedAt"),
                "updated_at": a.get("updatedAt"),
            }
    return list(results.values())


ACTIONS = {
    "list_parent_segments": _list_parent_segments,
    "list_segments": _list_segments,
    "list_journeys": _list_journeys,
}


def main(action, parent_segment_id):
    action = (action or "").strip().lower()
    if action not in ACTIONS:
        raise ValueError("Unknown action. Use one of: " + ", ".join(ACTIONS))
    return json.dumps(ACTIONS[action](parent_segment_id))
$$;
```

### Step 7: Create the Table Functions and the View

Python functions return a single value, so these SQL table functions turn the JSON into rows. Genie Agents need at least one table or view as a source, so the view wraps the parent segment list. Every query on the view calls Treasure AI live, and nothing is copied into Databricks.

```sql
CREATE OR REPLACE FUNCTION treasure_ai.genie.td_parent_segments()
RETURNS TABLE (
  parent_segment_id STRING,
  name STRING,
  description STRING,
  population BIGINT COMMENT 'Number of customer profiles. NULL means the size has not been calculated yet.',
  updated_at TIMESTAMP
)
COMMENT 'Live list of Treasure AI parent segments (audiences).'
RETURN
  SELECT p.parent_segment_id, p.name, p.description, p.population,
         try_cast(p.updated_at AS TIMESTAMP) AS updated_at
  FROM (
    SELECT explode(from_json(
      treasure_ai.genie.td_cdp_fetch('list_parent_segments', NULL),
      'ARRAY<STRUCT<parent_segment_id: STRING, name: STRING, description: STRING, population: BIGINT, updated_at: STRING>>'
    )) AS p
  );

CREATE OR REPLACE FUNCTION treasure_ai.genie.td_segments(
  parent_segment_id STRING COMMENT 'Numeric parent_segment_id from td_parent_segments_v'
)
RETURNS TABLE (
  segment_id STRING,
  name STRING,
  description STRING,
  population BIGINT COMMENT 'Number of customer profiles. NULL means the size has not been calculated yet.',
  kind INT,
  updated_at TIMESTAMP
)
COMMENT 'Live list of the segments inside one Treasure AI parent segment.'
RETURN
  SELECT s.segment_id, s.name, s.description, s.population, s.kind,
         try_cast(s.updated_at AS TIMESTAMP) AS updated_at
  FROM (
    SELECT explode(from_json(
      treasure_ai.genie.td_cdp_fetch('list_segments', td_segments.parent_segment_id),
      'ARRAY<STRUCT<segment_id: STRING, name: STRING, description: STRING, population: BIGINT, kind: INT, updated_at: STRING>>'
    )) AS s
  );

CREATE OR REPLACE FUNCTION treasure_ai.genie.td_journeys(
  parent_segment_id STRING COMMENT 'Numeric parent_segment_id from td_parent_segments_v'
)
RETURNS TABLE (
  journey_id STRING,
  name STRING,
  state STRING,
  paused BOOLEAN,
  parent_segment_id STRING,
  launched_at TIMESTAMP,
  updated_at TIMESTAMP
)
COMMENT 'Live list of the journeys built on one Treasure AI parent segment.'
RETURN
  SELECT j.journey_id, j.name, j.state, j.paused, j.parent_segment_id,
         try_cast(j.launched_at AS TIMESTAMP) AS launched_at,
         try_cast(j.updated_at AS TIMESTAMP) AS updated_at
  FROM (
    SELECT explode(from_json(
      treasure_ai.genie.td_cdp_fetch('list_journeys', td_journeys.parent_segment_id),
      'ARRAY<STRUCT<journey_id: STRING, name: STRING, state: STRING, paused: BOOLEAN, parent_segment_id: STRING, launched_at: STRING, updated_at: STRING>>'
    )) AS j
  );

CREATE OR REPLACE VIEW treasure_ai.genie.td_parent_segments_v
COMMENT 'Live list of Treasure AI parent segments (audiences). population = number of customer profiles.'
AS SELECT * FROM treasure_ai.genie.td_parent_segments();
```

### Step 8: Test the Functions

Run each query on its own. In the second and third queries, use a `parent_segment_id` from the first result.

```sql
SELECT * FROM treasure_ai.genie.td_parent_segments_v ORDER BY population DESC NULLS LAST LIMIT 10;

SELECT * FROM treasure_ai.genie.td_segments('<parent_segment_id>');
SELECT * FROM treasure_ai.genie.td_journeys('<parent_segment_id>');
```

Each query returns live rows from Treasure AI. The journeys query makes one API call per folder, so it can take several seconds.

### Step 9: Grant Access to Your Users

Replace `GENIE_USERS` with your users' account group. Nothing is granted on `treasure_ai.secrets`, so users can't read the key.

```sql
GRANT USE CATALOG ON CATALOG treasure_ai TO `GENIE_USERS`;
GRANT USE SCHEMA, EXECUTE, SELECT ON SCHEMA treasure_ai.genie TO `GENIE_USERS`;
```

Users also need **CAN USE** on the agent's SQL warehouse.

## Phase 2: Create and Configure the Genie Agent

### Step 1: Create the Genie Agent

1. In the navigation menu, select **Genie Agents**, and then select **+ New**. You can also use **+ New → Genie Agent**.
2. When Genie asks **What should your Genie agent do?**, type a short description, such as `Treasure AI CDP`, and select **+ Select tables manually**.
3. In **Connect your data**, open `treasure_ai` → `genie`, select `td_parent_segments_v`, and select **Create manually**.


1. The agent opens with a generated name and a **Genie Suggested Description** on the **About** tab. Select **Accept**, or select **Edit** to change it first. The description appears under the agent's name, where users see it when they open the agent.


### Step 2: Add the SQL Functions

1. Open **Configure → Sources**. The view `td_parent_segments_v` is already listed.
2. Select **Add → SQL function**.


1. In **Add SQL Functions**, choose the catalog `treasure_ai` and the schema `genie`, pick a function, and select **Save**. Repeat for each of the four functions below.


| Function  | What Genie Uses It For  |
|  --- | --- |
| `td_journeys` | The journeys of one parent segment |
| `td_segments` | The segments inside one parent segment |
| `td_parent_segments` | The live parent segment list |
| `td_cdp_fetch` | The function that the three table functions call. Without it as a source, the agent reports that its access doesn't include the underlying data function |


### Step 3: Add the Instructions

Open **Configure → Instructions**, paste the following text into **General Instructions**, and select **Save**.

```text
Answer questions about Treasure AI parent segments
(also called audiences), the segments inside them, and journeys.
- Parent segments are in td_parent_segments_v.
- For the segments inside a parent segment, first look up its
  parent_segment_id in td_parent_segments_v by name, then call
  td_segments(parent_segment_id).
- For journeys, look up the parent_segment_id the same way, then call
  td_journeys(parent_segment_id).
- population is the number of customer profiles. Show it with
  thousands separators. NULL means the size hasn't been calculated yet.
- Never guess ids or numbers. If a name matches more than one parent
  segment, ask the user which one they mean.
```

### Step 4: Add an Example Query (Optional)

Open **Configure → Examples**, add a SQL query example, and enter the question `Which parent segments are the largest?` with this SQL:

```sql
SELECT name, population
FROM treasure_ai.genie.td_parent_segments_v
ORDER BY population DESC NULLS LAST
```

Select **Preview** to check the result, and then select **Save**.

### Step 5: Set the Name and the Warehouse

On the **About** tab, select the pencil next to **About this agent**. In **Edit agent details**, set **Name** to `Treasure AI CDP`, and set **Default warehouse** to the serverless SQL warehouse that you tested in Phase 1, Step 8. Genie runs every query, and every Treasure AI API call, on this warehouse.

### Step 6: Share the Agent

1. Select **Share** in the upper right. In **Sharing: Treasure AI CDP**, enter the account group that you granted access to in Phase 1, Step 9.
2. The permission defaults to **Can Manage**. Change it to **Can Run**, so that users can chat with the agent but not change it, and select **Add**.


## Phase 3: Query Treasure AI from the Genie Agent

Business users open **Genie Agents**, select **Treasure AI CDP**, keep **Agent** selected under the question box, and ask a question, for example *Show me the journeys for the [SC Demo] Retail - 2026 parent segment*. To check an answer, compare its IDs and populations with the results from Phase 1, Step 8. **Thought process** shows the SQL and the function calls behind the answer.

Use **Agent** mode for these questions. `td_cdp_fetch` is not a table function, so **Chat** mode can't call it.

## Security, Costs, and Limits

- **Billing and credit usage**: Genie's AI usage is billed by Databricks. Every question runs SQL, and every Treasure AI API call, on the agent's default SQL warehouse. A small serverless warehouse with a short auto-stop keeps this low. Treasure AI serves standard CDP API calls, so no Treasure AI Credits are used.
- **Credential isolation**: The Treasure AI API key is stored in a Unity Catalog secret in its own schema. Only `td_cdp_fetch` reads it, through its `SECRETS` clause, and users get no grants on that schema. To rotate the key, update the secret's value in **Catalog → treasure_ai → secrets → td_api_key**.
- **Shared Treasure AI identity**: Every Genie user acts as the one Treasure AI user behind the key, so keep that user's access narrow.
- **Outbound network access**: The preview in Phase 1, Step 2 opens outbound access for serverless SQL warehouse workloads. Where you can, use a serverless egress policy that allows only the CDP API host.
- **Read-only metadata scope**: The function sends only `GET` requests to fixed paths for three actions, so Genie can't change anything in Treasure AI. It returns high-level metadata such as ID, name, population, and dates. It doesn't query individual customer profiles, change audience rules, or trigger journeys.
- **No item cap or paging**: Each action returns everything that the API sends back in one response. Very large accounts may need paging or filtering before production use.
- **HTTP timeout**: Each Treasure AI API call has a 30-second timeout (`TIMEOUT_SECONDS = 30`). `list_journeys` makes one call per folder, so a parent segment with many folders takes longer.


## Troubleshooting

| Symptom  | Likely Cause  | Fix  |
|  --- | --- | --- |
| `Treasure API HTTP 401` | Wrong API key, wrong regional host, or a write-only API key | Use a **Master Key** (see [Getting Your API Keys](/products/my-settings/getting-your-api-keys)), and make sure that `CDP_HOST` matches your region |
| `Treasure API HTTP 403` | The dedicated Treasure AI user lacks permission | Give the dedicated Treasure AI user access to the parent segments |
| Connection or DNS error in Phase 1, Step 8 | Outbound networking is off or blocked | Turn on the preview in Phase 1, Step 2 and wait up to 15 minutes. Check that any serverless egress policy allows the CDP API host |
| Error about the secret when creating `td_cdp_fetch` | The function's owner can't read the secret | Give the owner `READ SECRET` on `treasure_ai.secrets.td_api_key` |
| The agent says that its access doesn't include the underlying data function | `td_cdp_fetch` isn't a source of the agent | Add `td_cdp_fetch` in Phase 2, Step 2 |
| Users get a permission error | Their group lacks a grant | Run the grants in Phase 1, Step 9 again, and check **CAN USE** on the warehouse |
| Users can't find the agent | The agent isn't shared with them | Share it as in Phase 2, Step 6 |
| The agent answers without calling the functions | The instructions are too vague, or **Chat** mode is selected | Tighten the instructions in Phase 2, Step 3, and ask in **Agent** mode |
| `population` is empty | Treasure AI hasn't calculated that segment's size yet | Wait for the segment to run in Treasure AI |


## Next Steps

- [Connecting Databricks Genie One to Treasure AI Studio](/products/headless/databricks-genie-one) — run Treasure AI Studio agents and Actions from Genie One with each user's own Studio permissions
- [Databricks Genie Code](/getting-started/ai/databricks-genie-code) — connect the Databricks Genie Code CLI to Treasure AI
- [Snowflake CoWork](/getting-started/ai/snowflake-cowork) — the same read-only CDP pattern for Snowflake CoWork
- [Composable Audience Studio on Databricks](/products/customer-data-platform/composable-cdp/audience-studio/databricks) — build segments directly on Databricks tables with Zero-Copy
- [Open Catalog Access for Databricks](/products/customer-data-platform/open-catalog-access/databricks-integration) — query CDP tables in Apache Iceberg format from Databricks