Manage Role Assistant packages

Download, validate, and upload a Role Assistant package — environment
settings, candidate Evidence, optional Knowledge, and test cases — 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

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

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

aifabrix download <roleKey>

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

3. Validate the package (including settings schema):

aifabrix validate <roleKey>

4. Upload settings and package artifacts 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 and imports local
Evidence as candidate rows. Import resolves stable identities and reports
pending lifecycle actions; it does not certify or activate Evidence. Required
import failures exit non-zero, and a remote failure may occur after some rows
were imported, so inspect the returned per-row results before retrying.

An authorized human completes Evidence review and promotion separately in
Assistants → Evidence. File approval metadata and --force do not grant
promotion authority.

5. Environment upload ladder when ready. Complete governed Evidence review
   in each target before tests or promotion decisions rely on those rows:

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

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

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 upload the same local package folder to each environment. Each
upload applies only the matching YAML section and re-runs Evidence import
for local rows. Do not invent a package version number or a separate Miso Role
Assistant deploy pipeline.

Validate

Common mistakes

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. Use the package upload model (--env) even when Connected System help text differs.
• Connected System certify/upload remains required for Layer A capabilities.

Related

• How Role Assistants are created
• Evidence Fabrix
• Test Role Assistants
• Author Role Assistant Evidence
• Author Role Assistant Knowledge
• Deployment and upload — Connected Systems
• Operate your first Role Assistant
• Runtime Orchestration MCP
• CLI reference