Cu SDK Sample Run Agent Skill

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-4.1, GPT-4.1-mini, 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:

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) |

| GPT_4_1_DEPLOYMENT | updateDefaults | Deployment name for gpt-4.1 model (default: gpt-4.1) |

| GPT_4_1_MINI_DEPLOYMENT | updateDefaults | Deployment name for gpt-4.1-mini model (default: gpt-4.1-mini) |

| TEXT_EMBEDDING_3_LARGE_DEPLOYMENT | updateDefaults | Deployment name for text-embedding-3-large model (default: text-embedding-3-large) |

| 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:

# 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:

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

Examples:

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):

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

   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.

• 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

• First-time setup (run once per Foundry resource):

   cd samples/v1/javascript
   node updateDefaults.js

• Analyze a document from URL:

   cd samples/v1/javascript
   node analyzeUrl.js

• Analyze a local PDF file:

   cd samples/v1/javascript
   node analyzeBinary.js

• Extract invoice fields:

   cd samples/v1/javascript
   node analyzeInvoice.js

List Available Samples

.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.

# 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 — Full SDK documentation
• Samples directory — JavaScript sample files
• Product Documentation