Configure AI contract

Declare capabilities, exposed filterable fields, and exposure schema so Role Assistants and Enterprise MCP discover governed actions — not raw vendor fields.

Prerequisites

• Configure business vocabulary with indexed metadata
• Configure business policies when ABAC dimensions apply
• resourceType aligned with catalog tokens

Where it lives

Manifest sections: datasource.capabilities, datasource.exposedAttributes.

Builder MCP

Run aifabrix repair <systemKey> --expose --rbac after capability or exposure edits. Trust metadata: Agent metadata and trust.

How to set

1. Repair vocabulary and exposure before declaring capabilities:

aifabrix repair <systemKey> --expose --rbac --dry-run
aifabrix repair <systemKey> --expose --rbac

2. Declare capabilities with business descriptions (and optional Role Assistant / approval placeholders). Rewrite technical import leftovers into when-to-use language:

{
  "capabilities": [
    {
      "key": "search",
      "description": "Find existing customer records that match the user's question. Use this when the user needs information already stored. Do not use this to create or change customer state; use create or update.",
      "riskLevel": "low",
      "approvalRequired": false
    },
    {
      "key": "update",
      "description": "Change allowed customer attributes under policy. Use this when the user intends to update an identified customer. Do not use this only to inspect records; use search or read.",
      "riskLevel": "high",
      "approvalRequired": true
    }
  ],
  "exposed": {
    "filterable": ["country", "ownerId"],
    "schema": ["externalId", "name", "country", "ownerId"]
  }
}

3. Map RBAC permission names to resourceType:operation — Configure roles and permissions.
4. Align CIP and OpenAPI — enabled capability keys must match Configure data flow operations.
5. Publish MCP — Configure Enterprise MCP after upload.

Defaults and examples

Description quality (technical → business)

OpenAPI/wizard imports often leave vendor operation names and schema jargon. Role Assistants and Enterprise MCP choose tools from description, not from guessing payloads. For each capability:

1. Say when to use the action in business terms
2. Say when not to use it — and which sibling capability to use instead
3. Name follow-on capabilities when success hands work to another action
4. Prefer outcomes (“Find existing customers that match the question”) over leftovers (“create”, internal artifact type names, raw id jargon)
5. Keep key short and stable; put teaching in description

Field and attribute descriptions agents see should also use business outcome language — not vendor column names alone.

How generated catalogs reach Role Assistants: How Role Assistants get capabilities. Concept: Agent metadata and trust.

Example exposure set with placeholders:

{
  "capabilities": [
    {
      "key": "read",
      "description": "Look up customer details the user already knows how to identify. Use this when answering questions about an existing customer. Do not use this to find customers by vague criteria; use search. Do not use this to change customer data; use update.",
      "riskLevel": "low",
      "approvalRequired": false
    },
    {
      "key": "update",
      "description": "Change customer attributes the business allows under policy (for example region or owner). Use this when the user intends to correct or update an identified customer. Do not use this only to inspect records; use read or search. After success, confirm with read if the user needs the updated view.",
      "riskLevel": "high",
      "approvalRequired": true
    }
  ],
  "exposed": {
    "filterable": ["customerRegion"],
    "schema": ["externalId", "name", "customerRegion"]
  }
}

Illustrative contract goals:

• normalized field names only — never raw vendor JSON paths in exposed.schema
• one description per enabled capability for certification trust pillar
• filterable list matches dimension bindings on the same entity
• mutating capabilities declare riskLevel and approvalRequired

Validate

aifabrix repair <systemKey> --expose
aifabrix validate <systemKey>
aifabrix verify-trust <systemKey>
aifabrix verify-operations <systemKey>

Trust failures often trace to missing capability description, missing Role Assistant / approval placeholders on high-risk mutations, or vendor field names in exposed.schema — repair and re-validate before certification. Compare online MCP output with manifest exposed.filterable after upload when debugging Role Assistant query scope.

Common mistakes

Limits

AI contract bands describe what agents may discover — they do not replace RBAC YAML or protection uploads. riskLevel and approvalRequired are Role Assistant / approval placeholders compiled into the trust model; they do not by themselves enforce Decision Engine approval. Enterprise MCP deduplicates tools per business capability; avoid duplicate keys across entities with the same resourceType unless scopes differ by policy. Re-upload after exposure edits; online contract drift breaks Role Assistants. Capability description must teach when-to-use and when-not — trust reviewers and AI selection both depend on that prose. Keep exposed.schema minimal: expose decision-relevant fields agents need, not every vendor attribute copied during import. Re-run verify-trust after changing filterable lists tied to ABAC dimensions.