AI Agents & EntiHub

EntiHub is built so people and AI agents use the same governed surface: UI, REST API, and entihub CLI. Agents get predictable commands, machine-readable --json output, and the same permissions, approvals, audit trail, and anomaly workflow as human stewards.

This tutorial matches the AI agent workflow video: intro slides, then five hands-on use cases using the sample Customers CSV.

Walkthrough video

Hands-on: an AI agent creates a Customers entity from CSV, loads data, searches, checks the audit trail, and triages anomalies — same governance as a human steward.

Watch on YouTube · CLI & AI on entihub.com

What you will learn

1. Prepare an entity — from a business file to validated YAML, create, and deploy.
2. Load data — bulk CSV import into the entity.
3. Search — find entities and records across MDM.
4. Audit trail — inspect admin audit and entity change history.
5. Anomalies — run detection, triage duplicates and outliers, update status.

Sample data

Use customers-sample.csv from the product repository under video/ai/samples/ (31 B2B rows, US/GB/IE/CA). It includes:

Case	Customer codes	Purpose
Fuzzy duplicate	CUST-014, CUST-027	Same tax ID, similar Acme Trading names
Multi-source duplicate	CUST-008, CUST-031	Same Nordic Pack contact, different codes
Numeric outlier	CUST-019	MidMarket credit_limit = 2,500,000

Suggested entity prompt for an agent:

Create a Customers master entity from this CSV: business key customer_code, similarity on name / email / vat_id, anomaly detection for duplicates and credit_limit outliers.

Introduction (video slides)

Governed MDM for agents — agents call EntiHub; they do not maintain a parallel copy of master data.

Identity & permissions — an agent can authenticate on its own with an API key or service principal (permissions defined on the Permissions page, including entity access and row-level security), or run under a user account via interactive login (entihub login). In all cases, rights are explicit — scoped like a steward, not a superuser. See Access Keys.

Demo flow — Customers entity from CSV → load → search → audit → anomalies.

Re-render workflow slides from the repo: node ai/workflow/render.mjs (from video/).

Use case 1 — Prepare the entity

An agent (or steward assisted by an agent) turns the business file into entity YAML:

• Columns and validations aligned with CSV headers.
• similarity on name, email, vat_id for steward “similar records” checks.
• anomalyDetection (Enterprise): duplicate thresholds, columnOutliers on credit_limit.

CLI loop:

entihub entities validate --file customers.yaml --json
entihub entities create --file customers.yaml --json
entihub entities deploy customers --json

Deep reference: Setup Entity (similarity, anomalyDetection, deploy).

Use case 2 — Load data

Import the sample CSV after deploy:

entihub entities data bulk-csv customers --file customers-sample.csv --json

If the entity uses approvalRequired, rows may enter the approval queue — use approval commands before treating data as published.

UI equivalent: Import / Export Entity Data.

Use case 3 — Search entities and data

Agents should discover before mutating:

entihub search entities --q customers --json
entihub search data --q Acme --entity customers --json
entihub entities data list customers --filter "segment eq 'MidMarket'" --take 10 --json

For duplicate investigation:

entihub entities data similar customers --file suspect-row.json --json

Use case 4 — Audit trail

Correlate automation with steward accountability:

entihub audit --entity customers --json
entihub changes --entity customers --json

Guides: Audit Trail, record history in Entities.

Use case 5 — Analyze and resolve anomalies

Anomaly rules must be configured in entity YAML. Then:

entihub anomalies run customers --json
entihub anomalies list --entity customers --status new --json
entihub anomalies get <id> --json
entihub anomalies set-status <id> --file status-update.json --json

Example status-update.json:

{
  "status": "in_progress",
  "comment": "Reviewing Acme duplicate pair CUST-014 / CUST-027"
}

Workflow states: new → in_progress → resolved or ignored. For duplicate-type anomalies, use Open deduplicate in the UI or steward-approved merge — see Anomalies.

Analytics context: Entity Analytics.

Sample agent skill

Install the block below as your agent’s skill file (for Cursor: .cursor/skills/entihub/SKILL.md). It summarizes CLI flows for entity prep, data load, search, audit, and anomalies.

entihub-agent-skill.sample.md

---
name: entihub-mdm
description: >-
  Operate EntiHub MDM via the entihub CLI and REST API: create and deploy
  entities, load CSV data, search, audit changes, and triage anomalies. Use when
  automating master data, building AI agents on EntiHub, or answering questions
  about governed entity lifecycle.
disable-model-invocation: true
---

# EntiHub MDM agent

You work **inside** EntiHub governance — same permissions, approvals, and audit as human stewards. Prefer the **entihub CLI** with **`--json`** on every command.

## Before you start

1. Confirm config: `entihub config show --json` and `entihub whoami --json`.
2. Use an **API key** or **service principal** scoped to the entity — never bypass approvals.
3. Parse JSON stdout; check HTTP status in CLI JSON envelope when present.
4. For tutorials, sample CSV: **Customers** (`customers-sample.csv`) with seeded duplicate pairs and one `credit_limit` outlier.

## Authentication

- Interactive (human): `entihub login`
- Automation: `entihub config set --base-url https://<host>` plus `--api-key` on commands or env as documented for the deployment.
- Verify: `entihub health --json`

## Entity preparation (from business file)

Typical loop when the user provides CSV or a business description:

1. Draft entity YAML (columns, validations, `similarity`, `anomalyDetection` for duplicates and `columnOutliers` on numeric fields).
2. `entihub entities validate --file <entity.yaml> --json` — fix all errors before create.
3. `entihub entities create --file <entity.yaml> --json`
4. `entihub entities deploy <name> --json`
5. Optional: `entihub entities deploy-preview <name> --json` before production deploy.

Business key and uniqueness must match the source file (e.g. `customer_code`).

## Load data

- CSV bulk: `entihub entities data bulk-csv <name> --file <file.csv> --json`
- JSON bulk: `entihub entities data bulk <name> --file <rows.json> --json`
- If **approvalRequired** is true, new rows may sit in pending state — use approval commands; do not assume immediate publish.

## Search entities and data

- Find models: `entihub search entities --q <text> --json`
- Find records: `entihub search data --q <text> [--entity <name>] --json`
- Grid-style query: `entihub entities data list <name> [--filter expr] [--sort col] [--skip N] [--take N] --json`
- Similar records helper: `entihub entities data similar <name> --file <row.json> --json`

## Audit trail and change log

- Admin audit events: `entihub audit [--entity <name>] [--user email] [--action type] --json`
- Entity change stream: `entihub changes [--entity <name>] [--after-id N] --json`
- When explaining impact to a steward, cite audit/changes output — do not invent history.

## Anomalies (Enterprise)

Requires `anomalyDetection` in entity YAML.

1. Run detection: `entihub anomalies run <name> --json`
2. List open items: `entihub anomalies list [--entity <name>] [--status new|in_progress|resolved|ignored] --json`
3. Detail: `entihub anomalies get <id> --json`
4. Update workflow state: `entihub anomalies set-status <id> --file status.json --json`  
   Body example: `{ "status": "in_progress", "comment": "Reviewing Acme duplicate pair" }`

For duplicate/similar anomalies, use **similar** + steward UI deduplicate when merge is required — propose merge plan; human approves destructive merges.

## Human-in-the-loop

- Do **not** delete or merge golden records without explicit user confirmation when policy requires it.
- Respect `approvalRequired` and permission denials — surface CLI errors verbatim.
- After approved publishes, mention webhooks if the user cares about downstream sync.

## Raw API escape hatch

When no named command exists:

`entihub api <METHOD> <path> [--file body.json] --json`

Paths use the same `/api/v1` contract as the web app (see OpenAPI on the deployment).

## Related documentation

- [CLI](../UserGuide/CLI/)
- [Setup Entity](../UserGuide/SetupEntity/) — similarity & anomalyDetection
- [Anomalies](../UserGuide/Anomalies/)
- [Audit Trail](../UserGuide/AuditTrail/)

Suggested reading

• CLI
• Use Cases — AI Agent Identity Registry, Corporate Vocabulary, Decision Governance
• Video Tutorials