Manage Role Assistant packages

Download, validate, and promote a Role Assistant package — environment settings plus Evidence — without treating the Role Assistant like a vendor Connected System.

Prerequisites

Logged in: aifabrix auth status (or CI app credentials)
The Role Assistant already exists on the dataplane (platform-generated — not hand-built)
You know which environment to promote: dev, tst, or pro

Concept background: How Role Assistants are created. Connected System publish remains separate: Deployment and upload.

Where it lives

Kind	Local folder
Role Assistant package	`role-assistant/<roleKey>/`
Connected System	`integration/<systemKey>/`

Typical package layout:

role-assistant/<roleKey>/
  application.yaml
  <roleKey>-system.yaml
  role-assistant.yaml      # required for settings upload
  evidence/                # Evidence rows; processed on upload
  knowledge/               # optional

Optional lifecycle test cases live under the package when you use aifabrix role-assistant test --case. role-assistant.yaml holds only dev / tst / pro sections (runtime + debug). No secrets in this file. There is no package version — promotion is environment-based with --env.

How to set

Download the Role Assistant into the local package (when you need an online baseline):

aifabrix download <roleKey>

Edit the environment section you will promote in role-assistant.yaml (for example dev.runtime / dev.debug). --env X uses section X only — no merge from other environments.
Validate the package (including settings schema):

aifabrix validate <roleKey>

Promote settings + Evidence to one environment. For Role Assistants, upload and deploy are the same dataplane path (not a separate Miso Connected System deploy):

aifabrix upload <roleKey> --env dev
# same outcome:
aifabrix deploy <roleKey> --env dev

On upload/deploy the CLI applies that environment’s settings, discovers evidence/, then load → validate → certify → production-ready. Required Evidence failure exits non-zero.

Promote ladder when ready:

validate
  → upload --env dev
  → upload --env tst
  → upload --env pro

Optional lifecycle check (portal deep link for operators):

aifabrix role-assistant test <roleKey> --env dev
aifabrix role-assistant test <roleKey> --case smoke

Full test-case authoring: Test Role Assistants.
Evidence and Knowledge authoring: Author Role Assistant Evidence and Author Role Assistant Knowledge.

Defaults and examples

Topic	Default / rule
Environments	`dev`, `tst`, `pro` only
Missing `--env` section	Settings upload fails
Secrets	Not in `role-assistant.yaml` — use secret store / `env.template`
Evidence	Package `evidence/` is the Evidence-first promote path
Standalone Evidence CRUD	Separate Evidence CLI when you need list/get outside upload

Minimal role-assistant.yaml shape (fields vary by deployment — validate against the settings schema):

apiVersion: aifabrix.ai/v1
version: 1.0.0
kind: RoleAssistantSettings
roleKey: sales-representative
dev:
  runtime:
    provider: openai
    model: gpt-5-nano
    temperature: 0.2
    maxLoops: 20
  debug:
    enabled: true
tst:
  runtime:
    provider: openai
    model: gpt-5-nano
    temperature: 0.2
    maxLoops: 20
  debug:
    enabled: false
pro:
  runtime:
    provider: openai
    model: gpt-5-nano
    temperature: 0.1
    maxLoops: 20
  debug:
    enabled: false

Example promote sequence:

aifabrix validate sales-representative
aifabrix upload sales-representative --env dev
aifabrix role-assistant test sales-representative --env dev
aifabrix upload sales-representative --env tst
aifabrix upload sales-representative --env pro

Integrators promote the same local package folder to each environment. Each upload applies only the matching YAML section and re-runs Evidence discovery for local Evidence rows. Do not invent a package version number or a separate Miso Role Assistant deploy pipeline.

Validate

Check	Command / signal
Package + settings schema	`aifabrix validate <roleKey>`
Promote succeeded	Upload exit 0; structured summary for settings + Evidence counts
Lifecycle smoke	`aifabrix role-assistant test <roleKey> --env <env>`
Connected System online tools	Use Connected System `show --online` — not this package path

Common mistakes

Mistake	Fix
Using `integration/<key>/` for a Role Assistant	Use `role-assistant/<roleKey>/` after download
Expecting Miso deploy / package version for Role Assistants	Use `upload`/`deploy` with `--env` only
Putting secrets in `role-assistant.yaml`	Move credentials to the secret store
Ignoring Evidence failures	Fix or remove invalid `evidence/` rows; re-upload
Teaching Connected System `upload --probe` as the Role Assistant path	See Deployment and upload for Connected Systems only

Limits

Role Assistants must already exist on the dataplane (platform-generated). This page does not create assistants from scratch.
Exact CLI flags follow your Builder version — confirm with aifabrix upload --help and Builder Role Assistant package docs. Prefer the package promote model (--env) even when Connected System help text differs.
Connected System certify/upload remains required for Layer A capabilities.

Documentation Index