Skip to main content
A Mandala agent is a versioned workflow definition, not an unrestricted chatbot. Its SKILL.md declares what data it may read, what rules must run, what records it can produce, when a person must approve work, and which controlled actions are available.

​
What is in a skill

Every supported skill uses api_version: mandala.ai/v1 and kind: agent_workflow. The main sections are: See skills/procurement-reorder/SKILL.md and skills/sales-spike-investigator/SKILL.md in the repository for complete examples.

​
Compilation is a safety gate

Mandala resolves every declared capability against the selected workspace. Validation fails when a required capability is missing, not granted, unhealthy, incompatible with the current connector schema, or not approved for model processing. A successful compilation produces an immutable manifest containing:
  • exact connector and capability versions;
  • allowed tools and model-visible fields;
  • a deterministic runtime graph;
  • rules, record projections, approvals, and actions; and
  • source and manifest digests for later explanation.
Unknown fields and undeclared operations are rejected instead of being ignored.

​
Agent lifecycle

Agents move through deliberate states: Each installed version is retained. Rollback restores an earlier version through the same validation and readiness boundaries.

​
Manage agents in the terminal

Start with the guided manager:
The manager can validate a file, install an inactive agent, run a Sandbox test, activate or deactivate it, pause or resume it, list versions, and restore an earlier version. Scripted workflows are also available through the /agent-* commands in the interactive client. A manual run against real cataloged workspace data uses:
The reason and explicit confirmation are required because the run reads real workspace data and persists a reviewable work item.
Activation does not widen permissions. The runtime still checks the compiled binding, current workspace grant, connector health, schema compatibility, actor role, approval, and execution policy at the point of use.

​
Runtime path

A compiled run follows a fixed graph: resolve bindings, load permitted data, validate inputs, retrieve bounded context when enabled, perform model judgment, apply deterministic rules, project records, persist the review, pause for human approval, execute a controlled action if authorized, and audit the outcome. The model can select and explain a candidate. It cannot invent a tool, change a deterministic quantity rule, approve its own work, or read connector credentials.