Agents — Flow & Functionality

In MatrixAI, an agent is a small, specialised component that does exactly one thing. There is no large agent that controls everything: instead, several agents work in sequence, each with a specific responsibility and bounded permissions.

There are three types of agents in the system:

When you write a prompt like "classify emails as spam, normal or urgent", MatrixAI executes this pipeline:

Human prompt
    |
PromptAgent (deterministic) or LLMProposalAgent (with external AI)
    |
.semantic — a structured draft of the model
    |
PromptSupervisor — can a real model be built from this?
    |
ArchitectAgent — converts the plan into .mxai
    |
MathematicalAgent — translates if/then rules to mathematics
    |
PlannerVerifier — validates the complete plan
    |
.mxai — the final declarative model
    |
Parser — converts .mxai to IR (internal representation)
    |
VerifierAgent — validates the IR
    |
SafetyAgent — checks no real actions exist without sandbox
    |
PythonBackendCompiler — compiles the model to executable Python
    |
Runtime / Training / API / Auditing

A simple analogy

Think of building a bridge. The agents would be: PromptAgent is the architect who interprets the client's brief. ArchitectAgent draws the blueprints. MathematicalAgent does the structural calculations. PlannerVerifier and VerifierAgent are the technical inspectors who check the plans meet regulations. SafetyAgent is the safety inspection that certifies the bridge won't collapse. AuditorAgent explains to the client what decisions were made and why. No architect can approve their own blueprints.

File: matrixai/agents/prompt.py

The PromptAgent converts your natural language description into the first structured artefact: a .semantic file. It does this without calling any external LLM. It is completely deterministic: the same prompt always produces the same result.

What it does exactly

Available templates

Example output

# Input prompt:
"A system that classifies incoming emails as urgent, normal or spam,
using the subject, sender and confidence score"

# .semantic produced:
PROJECT EmailClassifier
INTENT classify incoming emails
MODE classification
ENTITY Email
FIELDS subject, sender, confidence_score
GOAL classify_incoming_email
ACTION send_response IF urgency > 0.85

File: matrixai/agents/llm_proposal.py

The LLMProposalAgent allows using an external language model to generate richer .semantic proposals adapted to complex domains.

Available providers

Configuration with an external LLM

MATRIXAI_LLM_API_KEY=your_api_key
MATRIXAI_LLM_MODEL=gpt-4o
MATRIXAI_LLM_ENDPOINT=https://api.openai.com/v1
MATRIXAI_LLM_PROVIDER_NAME=openai
MATRIXAI_LLM_CANDIDATES=3
MATRIXAI_LLM_TEMPERATURE=0.7
MATRIXAI_LLM_TIMEOUT=30
MATRIXAI_LLM_MAX_RETRIES=2
MATRIXAI_LLM_TOKEN_BUDGET=2000

# Or load from a .env file:
MATRIXAI_LLM_ENV_FILE=.env.llm

Call traceability

Every LLM call is recorded in an LLMCallTrace with: provider, model, endpoint, prompt hash, attempt number, latency, HTTP status, tokens consumed and error if any.

File: matrixai/agents/prompt_supervisor.py

The PromptSupervisor is the most important agent in the system. Its job is one: decide whether a proposal can become a real MatrixAI model. It is completely deterministic, regardless of whether the proposal came from PromptAgent or an external LLM.

The 7 acceptance checks

Run in order. If a blocking check fails, the process stops and the proposal is rejected with a clear message.

Check 1: architect_plan
  Can ArchitectAgent convert the .semantic into a plan?

Check 2: planner_verifier
  Does the plan comply with structural and goal rules?

Check 3: mathematical_rules_resolved
  Have all if/then rules been translated to mathematical expressions?

Check 4: parser
  Can the generated .mxai be parsed to canonical IR?

Check 5: verifier_agent
  Does the IR comply with graph, action, auditing and type checks?

Check 6: safety_agent
  Do actions respect the simulate_only sandbox?

Check 7: python_compiler
  Can the Python backend compile the programme?

Response when all checks pass

{
  "accepted": true,
  "semantic_text": "...",
  "plan": {},
  "mxai": "PROGRAM EmailClassifier ...",
  "compiled_python": "...",
  "checks": [
    { "name": "architect_plan", "passed": true },
    { "name": "planner_verifier", "passed": true }
  ]
}

Response when a check fails

{
  "accepted": false,
  "checks": [
    { "name": "architect_plan", "passed": true },
    { "name": "mathematical_rules_resolved", "passed": false,
      "error": "Rule 'if priority > 0.5 or urgency > 0.8' unresolved" }
  ]
}

File: matrixai/agents/architect.py

The ArchitectAgent takes the accepted .semantic and converts it into a structured SemanticPlan and the final .mxai file.

What it reads from the .semantic

What it generates per mode

File: matrixai/agents/architect.py (included in the same module)

The GoalTranslator converts business goals written in natural language (the GOAL blocks from the .semantic) into concrete, verifiable rules that PlannerVerifier can check.

Practical example

If your prompt says "minimise false alarms", the GoalTranslator generates the rule: "the threshold for triggering any action must be ≥ 0.85". PlannerVerifier then checks the model actually has that threshold. If not, the proposal is rejected before becoming a .mxai. This is what it means for MatrixAI to be declarative in a strong sense: you describe the goals, and the system verifies the model meets them.

File: matrixai/agents/mathematical.py

The MathematicalAgent converts "if X then Y" conditional rules into continuous mathematical expressions. Discrete rules are not differentiable (they cannot be used in training) and are not auditable in the same way.

Why convert rules to mathematics?

A rule like if risk > 0.8 then alert has a sharp jump at exactly 0.8 — from "no alert" to "alert". This creates problems during training (the gradient is zero almost everywhere) and in auditing. The solution is sigmoid(20 * (risk - 0.8)): a continuous function that behaves similarly but with a smooth transition around the threshold.

{
  "check": "mathematical_rules_resolved",
  "passed": false,
  "error": "Rule 'if patient.history matches pattern X' unresolved — text pattern not supported"
}

File: matrixai/agents/planner_verifier.py

The PlannerVerifier validates the SemanticPlan before the .mxai is emitted. It is the first formal verifier in the pipeline.

File: matrixai/agents/verifier.py

The VerifierAgent validates the IR (internal representation) of the already-parsed model. It works directly on the MatrixAIProgram object — after the .mxai has been parsed.

The acyclic graph check

A graph with cycles would mean circular dependencies (A depends on B, B depends on A), which would make execution infinite or undefined. MatrixAI always rejects these.

File: matrixai/agents/safety.py

The SafetyAgent is the last verifier before compiling the model. Its responsibility is ensuring the model cannot execute real actions without an explicit permissions contract.

The MVP contract: simulate_only

What if you need real actions?

Real actions require: (1) an explicit .mxact contract file, (2) the --allow-real-actions flag on the server, (3) the env variable MATRIXAI_ALLOW_REAL_ACTIONS=true, and (4) an HMAC signing key to trace every action. SafetyAgent only blocks accidental arrival at that flow.

Security messages

"Action 'send_email' has executor_kind=real but POLICY is not real_with_approval"
"Action 'update_db' calls 'database.write' outside the simulated.* space"

File: matrixai/agents/auditor.py

The AuditorAgent does not validate or generate models. Its job is to convert the result of an execution into an explanation anyone can understand.

What it explains

• If no action was triggered: why not, what values were evaluated, which threshold was not reached
• If an action was active: what value triggered it, from which source, with which threshold
• If an action was inactive: which condition was not met and by how much
• That the execution was simulated: explicit text that no real effect occurred
• Which nodes were evaluated: the complete trace of the data through the graph

Example output

Evaluation result:

The model classified this email as "urgent" with a probability of 0.94.

Factors that influenced the classification:
- The sender score (0.95) exceeded the confidence threshold (0.85)
- The email subject activated urgency signals with intensity 0.91

Proposed action: send_priority_response
- Status: SIMULATED — no real email has been sent
- Activation threshold: 0.85
- Observed value: 0.94 (threshold exceeded)

Nodes evaluated: Email → EmailScoring → UrgencyClassifier → Categorical → Action

File: matrixai/agents/optimizer.py

The OptimizerAgent analyses the model and suggests improvements. It only suggests: it does not modify the model on its own. The decision to apply or not apply an optimisation always belongs to the user.

Example report

OptimizationReport for EmailClassifier:

[SUGGESTION] merge_linear_activation
  Node: UrgencyClassifier -> sigmoid_threshold
  softmax_linear + sigmoid_threshold can be merged
  Expected impact: ~15% reduction in inference time

[SUGGESTION] simplify_graph
  Current nodes: 9 (recommended maximum: 7)
  Review whether 'IntermediateScore' and 'NormalizedScore' can be merged

No changes applied. All suggestions are informative.

Once PromptSupervisor accepts the proposal, the .mxai moves to the next layer. The agents are no longer present — their work is done.

.mxai accepted
    |
Interpreted runtime — runs the model without compiling, for quick tests
    |
PythonBackendCompiler — compiles to pure Python for autonomous execution
    |
DifferentiablePythonCompiler — trainable version of the model
    |
BackendContractAnalyzer — analyses portability to different backends
    |
Training (P4/P5) — adjusts parameters from real data
    |
HTTP Server (P6) — serves the model as REST API
    |
Studio (P6.5) — visual interface to explore the model

The 7 PromptSupervisor checks

Environment variables for external LLM

CLI

# Basic: print the generated .mxai
matrixai prompt "classify emails as spam, normal or urgent"

# Save the .mxai
matrixai prompt "classify emails as spam, normal or urgent" -o email.mxai

# See the intermediate .semantic the PromptAgent built
matrixai prompt "classify emails as spam, normal or urgent" --semantic

# Read description from a file
cat my_description.txt | matrixai prompt - -o model.mxai

# Full JSON output (includes .semantic, .mxai, trace and checks)
matrixai prompt "classify emails as spam, normal or urgent" --json

# If the generated model isn't what you expected:
matrixai prompt "my description" --semantic -o draft.semantic
# ... edit draft.semantic ...
matrixai supervise-prompt "my description" --proposal draft.semantic

REST API (Studio — port 8080)

curl -X POST http://localhost:8080/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"prompt": "classify emails as spam, normal or urgent"}'

# Response:
# { "ok": true, "semantic_text": "...", "mxai": "PROGRAM EmailClassifier ...",
#   "pipeline_stages": [
#     { "name": "prompt_agent", "ok": true },
#     { "name": "architect",    "ok": true },
#     { "name": "verifier",     "ok": true },
#     { "name": "safety",       "ok": true },
#     { "name": "compiler",     "ok": true }
#   ],
#   "supervision_source": "deterministic" }

Environment variables

export MATRIXAI_LLM_API_KEY=your_api_key
export MATRIXAI_LLM_MODEL=gpt-4o
export MATRIXAI_LLM_ENDPOINT=https://api.openai.com/v1
export MATRIXAI_LLM_PROVIDER_NAME=openai
export MATRIXAI_LLM_CANDIDATES=3
export MATRIXAI_LLM_TEMPERATURE=0.7
export MATRIXAI_LLM_TIMEOUT=30
export MATRIXAI_LLM_TOKEN_BUDGET=2000

CLI

# With external LLM (requires env vars)
matrixai propose "mortgage risk assessment system" \
  --provider chat-completions-compatible \
  --max-candidates 3

# Deterministic mode (uses PromptAgent as stand-in, no LLM)
matrixai propose "mortgage risk assessment system" \
  --provider deterministic \
  --max-candidates 2

# Include compiled Python in the output
matrixai propose "..." --provider chat-completions-compatible \
  --json --include-compiled

Check which mode is active

curl http://localhost:8080/api/studio/status
# { "ok": true, "llm_mode": { "active": true, "provider": "openai", "model": "gpt-4o" } }
# If "active": false → server is using DeterministicLLMProposalProvider (PromptAgent fallback)

CLI

# Supervise a previously generated (or hand-edited) .semantic
matrixai supervise-prompt "original model description" \
  --proposal my_model.semantic

# Full supervision report with all checks
matrixai supervise-prompt "original description" \
  --proposal my_model.semantic --json

# Parse supervisor results programmatically
matrixai prompt "classify emails" --json | python3 -c "
import json, sys
data = json.load(sys.stdin)
print('Accepted:', data.get('accepted', 'N/A'))
for check in data.get('checks', []):
    state = '✓' if check['passed'] else '✗'
    print(f'  {state} {check["name"]}')
    if not check['passed']:
        print(f'    ERROR: {check.get("error", "")}')
"

REST API — reading pipeline_stages

# When a check fails, subsequent ones appear as "skipped": true
# { "ok": false, "pipeline_stages": [
#     { "name": "architect_plan",              "ok": true  },
#     { "name": "planner_verifier",            "ok": true  },
#     { "name": "mathematical_rules_resolved", "ok": false,
#       "error": "Rule 'if category matches pattern X' unresolved" },
#     { "name": "parser",          "ok": false, "skipped": true },
#     { "name": "verifier_agent",  "ok": false, "skipped": true }
#   ] }

# Convert an existing .semantic to .mxai
matrixai architect my_model.semantic -o my_model.mxai

# Typical flow: generate .semantic first, then architect
matrixai prompt "assess patient fall risk" --semantic -o risk.semantic
matrixai architect risk.semantic -o fall_risk.mxai

# Studio: run executive on an existing .mxai
curl -X POST http://localhost:8080/api/studio/run-executive \
  -H "Content-Type: application/json" \
  -d '{
    "mxai": "PROGRAM RiskAssessment ...",
    "input_json": "{"age": 75, "balance_score": 0.3}",
    "mxai_name": "RiskAssessment"
  }'

# Translate from a rules file
matrixai mathematize business_rules.txt

# Single rule from stdin
echo "if risk > 0.8 then alert" | matrixai mathematize -

# Multiple rules
cat << 'EOF' | matrixai mathematize -
if default_history > 0.6 then reject
if income < 15000 and debt > 0.5 then review
if credit_score > 0.7 or collateral > 100000 then approve
classify application into approved, review, rejected
EOF

# JSON output
matrixai mathematize rules.txt --json

# Expected output (example):
# if risk > 0.75 then protocol
#   -> sigmoid(20 * (risk - 0.75))   [kind: sigmoid_threshold]
#
# if age > 80 and balance < 0.4 then urgent
#   -> sigmoid(20*(age-80)) * sigmoid(20*(0.4-balance))   [kind: sigmoid_and]

# Validate a .semantic before architecting
matrixai validate-plan my_model.semantic

# With JSON output
matrixai validate-plan my_model.semantic --json

# Full pre-generation validation flow:
matrixai prompt "my description" --semantic -o draft.semantic
matrixai validate-plan draft.semantic        # validate the plan
matrixai architect draft.semantic -o model.mxai
matrixai validate model.mxai                 # validate the final .mxai

# Parse errors programmatically:
matrixai validate-plan my_model.semantic --json | python3 -c "
import json, sys
result = json.load(sys.stdin)
if result.get('ok'):
    print('Valid plan')
else:
    for error in result.get('errors', []):   print(f'  ERROR: {error}')
    for warning in result.get('warnings', []): print(f'  WARN:  {warning}')
"

# Validate the .mxai (runs VerifierAgent on the IR)
matrixai validate email_classifier.mxai

# Lint: errors + warnings (more detailed than validate)
matrixai lint email_classifier.mxai

# Strict lint for CI/CD (fails on any warning)
matrixai lint email_classifier.mxai --strict

# View the IR the VerifierAgent validates
matrixai parse email_classifier.mxai

# Type-check (P2 type system)
matrixai typecheck email_classifier.mxai

# CI integration example:
# - name: Validate model
#   run: |
#     matrixai validate email_classifier.mxai
#     matrixai lint email_classifier.mxai --strict
#     matrixai typecheck email_classifier.mxai

# View model permissions and sandbox status
matrixai permissions email_classifier.mxai

# Output (safely sandboxed):
# Actions declared:
#   - send_reply
#     Policy:    simulate_only ✓
#     Call:      simulated.email.send ✓
#     Sandbox:   OK — no real permissions required

# Output (violation):
# ERROR: Action 'update_database'
#   Policy:  real_execution ✗ — requires sandbox or .mxact contract
#   Call:    database.write ✗ — outside simulated.* space

# Real actions (requires explicit contract + env var)
matrixai validate-actions contract.mxact email_classifier.mxai
matrixai dry-run-action contract.mxact email_classifier.mxai \
  --contract-name SendReply \
  --input '{"subject": "URGENT", "urgency_score": 0.92}'
matrixai execute-action contract.mxact email_classifier.mxai \
  --contract-name SendReply --allow-real-actions \
  --signing-key $MATRIXAI_ACTION_SIGNING_KEY \
  --input '{"subject": "URGENT", "urgency_score": 0.92}'

Production API — real action execution

curl -X POST http://localhost:8000/execute-action \
  -H "Authorization: Bearer $MATRIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_name": "SendReply",
    "input_data": { "subject": "URGENT", "urgency_score": 0.92 },
    "model_hash": "mxai_20d8ce3f...",
    "parameter_set_id": "v1.0_best"
  }'

CLI

# Run the model — output already includes AuditorAgent explanation
matrixai run email_classifier.mxai \
  --params runs/v1/params.best.json \
  --input '{"subject": "URGENT: system down", "sender_score": 0.95, "body_length": 90}'

# Classification: urgent (probability: 0.94)
# Factors: sender_score (0.95) exceeded threshold 0.85
# Action: send_priority_response — SIMULATED (no real email sent)
# Nodes: Email -> EmailScoring -> UrgencyClassifier -> Categorical -> Action

# Read factors from JSON output:
matrixai run email_classifier.mxai \
  --params runs/v1/params.best.json --input input.json --json | python3 -c "
import json, sys
result = json.load(sys.stdin)
print('Result:', result.get('result'))
for factor in result.get('influential_factors', []):
    print(f'  - {factor}')
"

REST API

# Studio — executive analysis of an existing model
curl -X POST http://localhost:8080/api/studio/run-executive \
  -H "Content-Type: application/json" \
  -d '{
    "mxai": "PROGRAM EmailClassifier ...",
    "input_json": "{"subject": "URGENT: system down", "sender_score": 0.95}",
    "mxai_name": "EmailClassifier"
  }'
# Returns: { "executive_result": { "decision": "urgent", "confidence": 0.94,
#   "action_status": "SIMULATED", "explanation": "...", "influential_factors": [...] } }

# Studio — simulate a guided case
curl -X POST http://localhost:8080/api/studio/simulate \
  -H "Content-Type: application/json" \
  -d '{ "case_id": "fall-risk",
        "input_values": { "age": 78, "balance_score": 0.28, "previous_falls": 2 } }'

# Production — prediction with traceability
curl -X POST http://localhost:8000/predict \
  -H "Authorization: Bearer $MATRIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"age": 78, "balance_score": 0.28, "previous_falls": 2}'

# View optimization suggestions for a model
matrixai optimize email_classifier.mxai

# [SUGGESTION] merge_linear_activation
#   Node: UrgencyClassifier -> sigmoid_threshold
#   softmax_linear + sigmoid_threshold can be merged
#   Expected impact: ~15% reduction in inference time
#
# [SUGGESTION] prune_isolated_nodes
#   Node: TempScore declared but not connected to GRAPH

# JSON output for scripting
matrixai optimize email_classifier.mxai --json | python3 -c "
import json, sys
data = json.load(sys.stdin)
suggestions = data.get('suggestions', [])
if not suggestions:
    print('No optimization suggestions')
else:
    for s in suggestions:
        print(f'  [{s["kind"]}] {s["description"]}')
"

# Via Studio API (suggestions appear in /api/analyze response)
curl -X POST http://localhost:8080/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"mxai_text": "PROGRAM EmailClassifier ..."}'

Description in text
        |
        |-- CLI: matrixai prompt "description"
        |-- CLI: matrixai propose "description" --provider chat-completions-compatible
        |-- API: POST /api/analyze  { "prompt": "description" }
        |
        v
   PromptAgent / LLMProposalAgent (generates .semantic)
        |
        |-- Inspect:  matrixai prompt "..." --semantic
        |-- Edit+supervise: matrixai supervise-prompt "..." --proposal draft.semantic
        |
        v
   PromptSupervisor (check 1: architect_plan)
        v
   ArchitectAgent (generates SemanticPlan + .mxai)
        |-- Direct: matrixai architect draft.semantic -o model.mxai
        v
   MathematicalAgent (check 3: mathematical_rules_resolved)
        |-- Direct: matrixai mathematize rules.txt
        |-- stdin:  echo "if x > 0.8 then alert" | matrixai mathematize -
        v
   PlannerVerifier (check 2: planner_verifier)
        |-- Direct: matrixai validate-plan draft.semantic
        v
   Parser (check 4: parser)
        |-- Inspect IR: matrixai parse model.mxai
        v
   VerifierAgent (check 5: verifier_agent)
        |-- Direct:   matrixai validate model.mxai
        |-- Detailed: matrixai lint model.mxai
        |-- Types:    matrixai typecheck model.mxai
        v
   SafetyAgent (check 6: safety_agent)
        |-- Inspect: matrixai permissions model.mxai
        |-- Dry-run: matrixai dry-run-action contract.mxact model.mxai ...
        v
   PythonBackendCompiler (check 7: python_compiler)
        |-- Compile:      matrixai compile model.mxai -o compiled.py
        |-- Portability:  matrixai backend-report model.mxai
        v
   .mxai ACCEPTED
        |
        +-- Single run (AuditorAgent):  matrixai run model.mxai --input in.json --params p.json
        |   API production:             POST /predict
        |   API Studio:                 POST /api/studio/run-executive
        |
        +-- Optimisation (OptimizerAgent): matrixai optimize model.mxai
        |
        +-- Training:  matrixai train model.mxai --training contract.mxtrain -o runs/v1/
        |
        +-- Serving:   matrixai serve model.mxai --params runs/v1/params.best.json --api-key KEY
        |
        +-- Studio:    matrixai studio --open

Full diagnostic script

#!/bin/bash
# diagnostics.sh <model.mxai>
MODEL=$1
echo "=== Pipeline diagnostics: $MODEL ==="

echo "1. Structural validation:"
matrixai validate "$MODEL" && echo "   OK" || echo "   FAIL"

echo "2. Lint (errors + warnings):"
matrixai lint "$MODEL" --json | python3 -c "
import json, sys
data = json.load(sys.stdin)
errors   = [d for d in data.get('diagnostics', []) if d.get('severity') == 'error']
warnings = [d for d in data.get('diagnostics', []) if d.get('severity') == 'warning']
print(f'   Errors: {len(errors)}, Warnings: {len(warnings)}')
for e in errors: print(f'   ERROR: {e.get("message")}')
"
echo "3. Type check:"
matrixai typecheck "$MODEL" && echo "   OK" || echo "   FAIL"

echo "4. Safety permissions:"
matrixai permissions "$MODEL" --json | python3 -c "
import json, sys; data = json.load(sys.stdin)
print(f'   Status: {data.get("safety_status", "unknown")}')
"
echo "5. Backend compatibility:"
matrixai backend-report "$MODEL" --json | python3 -c "
import json, sys; data = json.load(sys.stdin)
print(f'   differentiable_python: {data.get("compatible", "unknown")}')
for b in data.get('blocking_issues', []): print(f'   BLOCKER: {b}')
"
echo "6. Optimization suggestions:"
matrixai optimize "$MODEL" --json | python3 -c "
import json, sys; data = json.load(sys.stdin)
for s in data.get('suggestions', []): print(f'   -> {s.get("kind")}: {s.get("description")}')
" || echo "   None"
echo "=== Done ==="

# Usage:
chmod +x diagnostics.sh
./diagnostics.sh email_classifier.mxai