Configure agent metadata and trust

Outcome

When you finish this guide, your Business Entity manifests include the semantic, exposure, and capability descriptions required for the verify-trust certification pillar — and agents can discover safe contracts without admin-only validation dumps.

Prerequisites

Green validate and upload for the system key
Business Entities with fieldMappings, resourceType, and exposed blocks uploaded
Certification ladder understood (operations, trust, governance)
Login and permissions to run certification commands

Where it lives

Artifact	Layer	Purpose
Business Entity JSON	A — Manifest	Semantics, filterable lists, capability descriptions
Platform validation	B — Validation evidence	Trust decision after manifest edits
Published online config	C — Published contract	OpenAPI/MCP after upload
Runtime responses	D — Runtime context	Per-request tracing and policy
Normalized records	E — Record metadata	Business facts after mapping

Trust evaluates uploaded configuration. Local-only JSON does not certify.

Concept narrative (buyer/architect view): Agent metadata and trust.

Five metadata layers (configure view)

What this shows: which manifest fields you edit (layer A), what certification reads (layer B), and what agents may discover at design time (layer C) versus runtime (D–E).

What this is not: a substitute for running verify-trust or fixing governance when protection manifests are incomplete.

Mermaid diagram

Layer	Configure on manifest	Certification signal
A	`capabilities[].description`, `exposed.filterable`, semantic descriptions, `businessOrder`	Input to trust rules
B	Re-run after material edits	`trustDecision` not `notTrusted`
C	Upload + expose repair	`show --online` matches manifest intent
D	Optional `agentExposure.runtimeMeta`	Runtime enrichment only when needed
E	Field mappings + metadata schema	Agents answer from authorized responses

How to set

Capability descriptions — every enabled capability needs a human-readable description. Role Assistants and agents use these for discovery, risk context, and when-to-use / when-not selection. Prefer business outcomes over technical import leftovers — full quality rules: Configure AI contract.

{
  "capabilities": [
    {
      "key": "search",
      "description": "Find existing customer records that match the user's question. Do not use this to create or change customer state; use create or update."
    }
  ]
}

Semantic descriptions (R10) — labelKey, primary key fields, and every name in exposed.filterable need fieldMappings.attributes.<name>.semantic.description.
Filterable list (R3, R5) — declare exposed.filterable as the canonical filter name list. Do not add parallel recommended-filter keys in config.
Business ordering (R11) — when a Connected System has two or more record- or document-storage Business Entities, assign distinct businessOrder values ≥ 1.
Operation semantics — every enabled capability must have a known write shape (core CRUD or integration pipeline shape). Delete-shaped operations must be declared explicitly.
agentExposure — set runtime enrichment only when agents need per-response business blocks without a manifest round-trip:

{
  "agentExposure": {
    "runtimeMeta": true
  }
}

When runtimeMeta is false, runtime responses keep baseline tracing and governance fields only.

Run agent metadata validation after manifest edits (platform API or certification flow). Confirm trustDecision is not notTrusted before production publish.
Run verify-trust as part of the certification ladder:

aifabrix upload <systemKey> --probe
aifabrix upload <systemKey>
aifabrix verify-trust <systemKey>

Full ladder — never treat verify-trust alone as certification:

aifabrix verify-operations <systemKey>
aifabrix verify-trust <systemKey>
aifabrix verify-governance <systemKey> --subject-email scoped-user@example.com
aifabrix lifecycle <systemKey>

Defaults and examples

Readiness checklist summary

Check	Pass criterion
Business ordering	Distinct `businessOrder` when multiple record/document entities
Filterable fields	`exposed.filterable` lists normalized agent-usable names
Semantic descriptions	Label, primary key, and filterable fields have descriptions
Operation semantics	Known shapes for all enabled capabilities
Trust	Latest trust decision is not `notTrusted`
Publish gate	Production publish blocked when `notTrusted` (strict environments)
Protection	Protected entities have validated protection manifests and projected dimensions

Trust outcomes

Outcome	Action
`trusted`	Automate list/get and documented mutators
`usableWithWarnings`	Allow reads with user-visible warnings; confirm before destructive ops
`notTrusted`	Fix manifest or entity mismatch — do not automate
`pending`	Run validation; do not assume trust

Illustrative Business Entity identity checked by trust

{
  "key": "example-crm-customers",
  "displayName": "Customers",
  "systemKey": "example-crm",
  "entityType": "recordStorage",
  "resourceType": "customer",
  "primaryKey": ["externalId"],
  "exposed": {
    "filterable": ["country", "ownerId"]
  }
}

Validate

aifabrix verify-trust <systemKey>
aifabrix lifecycle <systemKey>

Review CLI output and platform certification signals before Role Assistant pilots. Re-run validation when any material config change alters the validation input hash.

Common mistakes

Mistake	Fix
verify-trust only	Run full certification ladder
Missing filterable list	Add `exposed.filterable`; repair manifest drift
Capability without description	Add `description` on every capability
Parallel agent filter keys	Use `exposed.filterable` only
Certify before upload	`upload --probe` then publish first
Guessing semantics from sample JSON	Author layer A descriptions explicitly

Limits

Validation codes, strict publish gates, and certification profiles evolve. Bronze profile success in development does not automatically satisfy production governance — confirm required profile with your platform operator.

Admin validation findings and observed business models are not on public OpenAPI or routine runtime responses. Do not build client logic that depends on those fields.

Trust pillar success with failing governance usually means dimensions or protection manifests are incomplete — re-run subject-scoped verify-governance after protection uploads, not only after integration JSON edits.

Documentation Index