# Cu Sdk Sample Run

> Run a specific sample for the Azure AI Content Understanding JavaScript SDK. Use when users want to run a particular sample like analyzeUrl.js or analyzeInvoice.js.

- Skill: `azure-azure-sdk-for-js/cu-sdk-sample-run` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add azure-azure-sdk-for-js/cu-sdk-sample-run`
- Raw SKILL.md: https://api.skillmd.com/api/skills/azure-azure-sdk-for-js/cu-sdk-sample-run/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Azure (https://skillmd.com/u/azure-azure-sdk-for-js)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/azure-azure-sdk-for-js/cu-sdk-sample-run

---


# Run a Specific Sample

Run a specific sample from the Azure AI Content Understanding JavaScript SDK.

> **[COPILOT INTERACTION MODEL]:** This skill is designed to be interactive. At each step marked with **[ASK USER]**, pause execution and prompt the user for input or confirmation before proceeding. Do NOT silently skip these prompts. Use the `ask_questions` tool when available.

## Prerequisites

- Node.js >= 20
- **Environment already set up** via the `cu-sdk-setup` skill (SDK tarball installed + `.env` configured)
- For prebuilt analyzers: model deployments configured (run `updateDefaults.js` first — also covered by `cu-sdk-setup`)

> **[ASK USER] Prerequisites check:**
> Before proceeding, verify the user's environment:
>
> 1. "Have you already set up your environment using the **`cu-sdk-setup`** skill (SDK tarball installed + `.env` configured)?" -- If no, hand off to that skill first.
> 2. "Have you run `updateDefaults.js` to configure model defaults?" -- If no and they want to use prebuilt analyzers, guide them to run it first.

## Package Directory

```
sdk/contentunderstanding/ai-content-understanding
```

## Available Samples

JavaScript samples are in `samples/v1/javascript/`.

### Getting Started (Run These First)

#### `updateDefaults` -- Required First!

**One-time setup** - Configures model deployment mappings (gpt-5.2, text-embedding-3-large) for your Microsoft Foundry resource. Must run before using prebuilt analyzers.

#### `analyzeUrl` -- Start Here!

Analyzes content from a URL using `prebuilt-documentSearch`. Works with documents, images, audio, and video.

- Key concepts: URL input, markdown extraction, multi-modal content

#### `analyzeBinary`

Analyzes local PDF/image files using `prebuilt-documentSearch`.

- Key concepts: Binary input, local file reading, page properties

### Document Analysis

#### `analyzeInvoice`

Extracts structured fields from invoices using `prebuilt-invoice`.

- Key concepts: Field extraction (customer name, totals, dates, line items), confidence scores, array fields

#### `analyzeConfigs`

Extracts advanced features: charts, hyperlinks, formulas, annotations.

- Key concepts: Chart.js output, LaTeX formulas, PDF annotations, enhanced analysis options

#### `analyzeReturnRawJson`

Gets raw JSON response for custom processing.

- Key concepts: Raw response access, saving to file, debugging

### Custom Analyzers

#### `createAnalyzer`

Creates custom analyzer with field schema for domain-specific extraction.

- Key concepts: Field types (string, number, date, object, array), extraction methods (extract, generate, classify)

#### `createClassifier`

Creates classifier to categorize documents (Loan_Application, Invoice, Bank_Statement).

- Key concepts: Content categories, segmentation, document routing

### Analyzer Management

#### `getAnalyzer`

Retrieves analyzer details and configuration.

#### `listAnalyzers`

Lists all available analyzers (prebuilt and custom).

#### `updateAnalyzer`

Updates analyzer description and tags.

#### `deleteAnalyzer`

Deletes a custom analyzer.

#### `copyAnalyzer`

Copies analyzer within the same resource.

#### `grantCopyAuth`

Cross-resource copying between different Azure resources/regions.

- Requires additional env vars: `CONTENTUNDERSTANDING_SOURCE_RESOURCE_ID`, `CONTENTUNDERSTANDING_SOURCE_REGION`, `CONTENTUNDERSTANDING_TARGET_ENDPOINT`, `CONTENTUNDERSTANDING_TARGET_RESOURCE_ID`, `CONTENTUNDERSTANDING_TARGET_REGION`
- Uses `CONTENTUNDERSTANDING_ENDPOINT` as the source endpoint

### Result Management

#### `getResultFile`

Retrieves keyframe images from video analysis.

- Key concepts: Operation IDs, extracting generated files

#### `deleteResult`

Deletes analysis results for data cleanup.

- Key concepts: Result retention (24-hour auto-deletion), compliance

## Workflow

### Step 1: Ensure Environment Is Set Up

> **[ASK USER] Environment check:**
> Ask: "Have you already set up your environment (built/installed the SDK tarball and configured `.env` with endpoint and credentials)?"
>
> - If **yes**: Proceed to Step 2 to pick a sample.
> - If **no**: Hand off to the **`cu-sdk-setup`** skill to walk through installation and `.env` configuration, then come back here.

For full environment setup — installing the SDK, creating `.env`, configuring authentication, and running `updateDefaults.js` — see the **`cu-sdk-setup`** skill.

Quick check that setup is complete:

```bash
cd sdk/contentunderstanding/ai-content-understanding
# Verify .env is present in the samples directory
test -f samples/v1/javascript/.env && echo "OK" || echo "Run cu-sdk-setup first"
```

#### Settings by sample

| Setting                             | Required By                       | Description                                                                                                  |
| ----------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `CONTENTUNDERSTANDING_ENDPOINT`     | **All samples**                   | Your Microsoft Foundry resource endpoint URL                                                                 |
| `CONTENTUNDERSTANDING_KEY`          | All samples (optional)            | API key for key-based auth. If empty, `DefaultAzureCredential` is used (recommended -- run `az login` first) |
| `CU_COMPLETION_MODEL`               | updateDefaults (optional)         | Completion model name (default: `gpt-5.2`)                                                                   |
| `CU_COMPLETION_MODEL_MINI`          | updateDefaults (optional)         | Mini completion model name (default: `CU_COMPLETION_MODEL`)                                                  |
| `CU_EMBEDDING_MODEL`                | updateDefaults (optional)         | Embedding model name (default: `text-embedding-3-large`)                                                     |
| `CU_COMPLETION_MODEL_DEPLOYMENT`    | updateDefaults                    | Completion model deployment name (required)                                                                  |
| `CU_COMPLETION_MINI_DEPLOYMENT`     | updateDefaults (optional)         | Mini completion deployment name (default: `CU_COMPLETION_MODEL_DEPLOYMENT`)                                  |
| `CU_EMBEDDING_DEPLOYMENT`           | updateDefaults                    | Embedding model deployment name (required)                                                                   |

| `CONTENTUNDERSTANDING_SOURCE_RESOURCE_ID` | grantCopyAuth | Source ARM resource ID for cross-resource copy |
| `CONTENTUNDERSTANDING_SOURCE_REGION` | grantCopyAuth | Source region (e.g., `eastus`) for cross-resource copy |
| `CONTENTUNDERSTANDING_TARGET_ENDPOINT` | grantCopyAuth | Target Foundry resource endpoint for cross-resource copy |
| `CONTENTUNDERSTANDING_TARGET_RESOURCE_ID` | grantCopyAuth | Target ARM resource ID for cross-resource copy |
| `CONTENTUNDERSTANDING_TARGET_REGION` | grantCopyAuth | Target region (e.g., `westus`) for cross-resource copy |

#### Samples that need a local file

The `analyzeBinary` and `analyzeConfigs` samples require a local document file. The sample includes a default file path to a test PDF. To use your own file, update the `filePath` variable in the sample code.

> **[ASK USER] Local file (if applicable):**
> If the user chose a sample that requires a local file (analyzeBinary, analyzeConfigs), ask:
> "This sample requires a local document file. Would you like to:"
>
> - **Use the default test file** -- The sample has a built-in file path.
> - **Provide your own file** -- You'll need to update the `filePath` variable in the sample code.

#### Setting up grantCopyAuth cross-resource environment

The `grantCopyAuth` sample requires **two separate Microsoft Foundry resources** (source and target).

Add the following to your `.env`:

```bash
# Source is your CONTENTUNDERSTANDING_ENDPOINT (already configured above)
CONTENTUNDERSTANDING_SOURCE_RESOURCE_ID="/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.CognitiveServices/accounts/{sourceAccountName}"
CONTENTUNDERSTANDING_SOURCE_REGION="eastus"
CONTENTUNDERSTANDING_TARGET_ENDPOINT="https://your-target-foundry.services.ai.azure.com/"
CONTENTUNDERSTANDING_TARGET_RESOURCE_ID="/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.CognitiveServices/accounts/{targetAccountName}"
CONTENTUNDERSTANDING_TARGET_REGION="swedencentral"
```

> **[ASK USER] Cross-resource setup (grantCopyAuth only):**
> If the user chose grantCopyAuth, ask:
>
> 1. "Do you have **two separate Microsoft Foundry resources** (source and target) set up?" -- If no, guide them to create a second resource.
> 2. "Your `CONTENTUNDERSTANDING_ENDPOINT` will be used as the **source endpoint**. Please provide the following for your **source** resource:" -- Source ARM Resource ID, Source region
> 3. "Please provide the following for your **target** resource:" -- Target endpoint URL, Target ARM Resource ID, Target region
> 4. Confirm: "Cross-resource copy works with both `DefaultAzureCredential` and API keys. Both resources must have the **Cognitive Services User** role assigned if using `DefaultAzureCredential`. Is this configured?"

### Step 2: Choose and Run the Sample

> **[ASK USER] Which sample?:**
> Ask the user: "Which sample would you like to run?" with options:
>
> - `updateDefaults` -- Configure model defaults (one-time setup, required first)
> - `analyzeUrl` -- Analyze content from a URL (recommended for first-time users)
> - `analyzeBinary` -- Analyze a local PDF/image file
> - `analyzeInvoice` -- Extract structured fields from an invoice
> - `createAnalyzer` -- Create a custom analyzer
> - Other -- Let me see the full list

Run the sample directly with `node` from the samples directory:

```bash
cd samples/v1/javascript
node <sampleName>.js
```

**Examples:**

```bash
cd samples/v1/javascript
node analyzeUrl.js
node analyzeBinary.js
node analyzeInvoice.js
```

> **Note:** Samples use `dotenv/config` to load environment variables from a `.env` file in the **current working directory**.
> The `setup_user_env.sh` script (from `cu-sdk-setup`) automatically copies `.env` from the package root into the samples folder.
> If you update your `.env`, re-run `setup_user_env.sh --verify-only` or manually copy it:
>
> ```bash
> cp sdk/contentunderstanding/ai-content-understanding/.env sdk/contentunderstanding/ai-content-understanding/samples/v1/javascript/.env
> ```
>
> Alternatively, use the `run_sample.sh` convenience script which sources `.env` automatically.
>
> ```bash
> .github/skills/cu-sdk-sample-run/scripts/run_sample.sh analyzeUrl
> ```

### After the Sample Runs — Review Results and Explain the Sample

After the sample completes, the skill **must** do the following for the user (do not skip):

1. **Show the terminal command to re-run this sample directly**, so the user can iterate without the skill. For example:

   ```bash
   cd samples/v1/javascript && node analyzeUrl.js
   # or for TypeScript samples:
   cd samples/v1/typescript && npx tsx src/analyzeUrl.ts
   ```

   Substitute `analyzeUrl` with the sample the user just ran.

2. **Briefly explain the key code concepts** demonstrated in the sample. Tailor the explanation to the specific sample; common concepts include:
   - **Client creation** — how the `ContentUnderstandingClient` is constructed (endpoint + `DefaultAzureCredential` or `AzureKeyCredential`)
   - **Analyzer selection** — which prebuilt (`prebuilt-documentSearch`, `prebuilt-invoice`, etc.) or custom analyzer is used and why
   - **Input type** — URL vs. binary stream vs. local file
   - **Result processing** — how the returned `AnalyzeResult` is traversed (pages, fields, contents)
   - **Content type casting** — e.g., narrowing `AnalyzedContent` to `AnalyzedDocumentContent` / `AnalyzedImageContent` / `AnalyzedAudioContent` / `AnalyzedVideoContent` when needed
   - **Long-running operations** — if the sample uses `getLongRunningPoller` / `pollUntilDone`

> **[ASK USER] Sample result:**
> Ask: "Did the sample run successfully?"
>
> - If yes: present the re-run command and the key-code explanation (above), then ask: "Would you like to run another sample, or are you all set?"
> - If no: help troubleshoot using the Troubleshooting section below. Common issues include missing `.env` configuration, tarball not installed, or model defaults not configured.

> **[ASK USER] Run another?:**
> If the user wants to run another sample, loop back to the "Which sample?" prompt above.

## Quick Reference

### Most Common Samples for New Users

1. **First-time setup** (run once per Foundry resource):

   ```bash
   cd samples/v1/javascript
   node updateDefaults.js
   ```

2. **Analyze a document from URL:**

   ```bash
   cd samples/v1/javascript
   node analyzeUrl.js
   ```

3. **Analyze a local PDF file:**

   ```bash
   cd samples/v1/javascript
   node analyzeBinary.js
   ```

4. **Extract invoice fields:**
   ```bash
   cd samples/v1/javascript
   node analyzeInvoice.js
   ```

### List Available Samples

```bash
.github/skills/cu-sdk-sample-run/scripts/run_sample.sh --list
```

## Scripts

This skill includes a single helper script in the `scripts/` directory.

### `run_sample.sh` — Run a sample (sources `.env` automatically)

A convenience wrapper that sources `.env` from the samples directory (or the package root) and runs the sample. Detects compiled JavaScript first; if only the TypeScript source is available, falls back to `npx tsx`.

```bash
# Run a JavaScript sample by name (with or without .js extension)
.github/skills/cu-sdk-sample-run/scripts/run_sample.sh analyzeUrl
.github/skills/cu-sdk-sample-run/scripts/run_sample.sh analyzeInvoice.js
.github/skills/cu-sdk-sample-run/scripts/run_sample.sh updateDefaults

# List all available samples (both compiled JS and TypeScript sources)
.github/skills/cu-sdk-sample-run/scripts/run_sample.sh --list
```

For environment setup (installing the SDK, building a local tarball, writing `.env`), use the `cu-sdk-setup` skill's `setup_user_env.sh` / `setup_user_env.ps1` script.

## Troubleshooting

| Error                                                             | Solution                                                                                                                              |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `Cannot find module '@azure/ai-content-understanding'`            | Run `setup_user_env.sh` (from `cu-sdk-setup`) to install the package (with automatic local-build fallback) into the samples directory |
| `Missing environment variables` / `CONTENTUNDERSTANDING_ENDPOINT` | Create a `.env` file in the package root with required variables                                                                      |
| `Access denied` or authorization errors                           | Ensure **Cognitive Services User** role is assigned; check API key or run `az login`                                                  |
| `Model deployment not found`                                      | Run `updateDefaults.js` first to configure model mappings                                                                             |
| `File not found` for binary samples                               | Some samples need a local file path; check the `filePath` variable in the sample                                                      |
| `Permission denied` when running scripts                          | Make scripts executable: `chmod +x .github/skills/cu-sdk-sample-run/scripts/*.sh`                                                     |

## Related Skills

- `cu-sdk-setup` — Interactive environment setup (install SDK, configure `.env`, run `updateDefaults.js`). Run this first if your environment is not yet set up.
- `cu-sdk-common-knowledge` — Domain knowledge for Content Understanding concepts

## Additional Resources

- [SDK README](../../../README.md) — Full SDK documentation
- [Samples directory](../../../samples/v1/javascript/) — JavaScript sample files
- [Product Documentation](https://learn.microsoft.com/azure/ai-services/content-understanding/)