Personas and prompts

The persona system

Every agent in MagOneAI has a persona that defines its identity and behavior. The persona is the foundation of how your agent reasons, responds, and operates within workflows. A well-crafted persona produces consistent, reliable outputs across thousands of workflow executions.

Persona components

Name

The agent's name appears throughout the MagOneAI interface — in the workflow canvas, execution logs, and activity history. Choose names that clearly communicate the agent's purpose:

Good names:

• "Invoice Data Extractor"
• "Customer Support Router"
• "Compliance Risk Assessor"

Poor names:

• "Agent 1"
• "Helper"
• "AI Assistant"

Clear naming makes workflows self-documenting and easier to maintain.

Role

The role defines the agent's core identity. This is typically a single sentence that establishes what the agent does:

Effective role definitions:

• "You are a financial analyst who evaluates loan applications for credit risk."
• "You are a technical support specialist who troubleshoots API integration issues."
• "You are an HR assistant who answers employee questions about benefits and policies."

Ineffective role definitions:

• "You are a helpful AI assistant." (too generic)
• "You help users with various tasks." (lacks specificity)
• "You are smart and can do many things." (vague and unhelpful)

The role should immediately clarify the agent's domain and purpose.

Instructions

Instructions provide detailed behavioral guidelines. This is where you specify HOW the agent should perform its role:

What to include:

• Step-by-step process the agent should follow
• Expected input format and how to interpret it
• Desired output structure and formatting
• Tone and communication style
• How to handle edge cases and errors
• Examples of desired behavior

Example instruction set:

You review customer support tickets and determine the appropriate department for routing.

Process:
1. Read the ticket description and extract the main issue
2. Identify keywords related to billing, technical issues, or account management
3. Classify the ticket into one category: billing, technical, or account
4. Provide a confidence score (0-1) for your classification
5. If confidence is below 0.7, classify as "general" for human review

Tone: Professional and concise
Output: Return only the structured classification, no explanatory text

Constraints

Constraints define boundaries — what the agent should explicitly NOT do. This is critical for production safety:

Common constraint categories:

• Decision boundaries — "Never approve transactions over $10,000 without human review"
• Information security — "Never share customer PII in logs or outputs"
• Legal/compliance — "Do not provide legal advice or final compliance determinations"
• Tool usage limits — "Do not delete data, only read and create operations allowed"
• Scope limits — "Only analyze the provided document, do not search for additional information"

Example constraint set:

Constraints:
- Never make final approval decisions, always route to human reviewer
- Do not access customer data outside the provided input
- Do not send emails or notifications without explicit instruction
- If you encounter ambiguous requirements, flag for human review rather than guessing
- Never override explicit user instructions with your own judgment

System prompt best practices

The system prompt encompasses the role, instructions, and constraints. Well-written system prompts are the difference between agents that work reliably in production and agents that produce inconsistent, unpredictable outputs.

Be specific about role and boundaries

Specificity produces consistency. Compare these two prompts:

You are a helpful AI assistant. You help users with their questions
and try to be accurate and friendly. Use your knowledge to provide
good answers.

You are a Contract Compliance Analyst specializing in GDPR and data
processing regulations.

Your role is to review contract clauses and identify potential GDPR
compliance risks.

Process:
1. Read the contract clause provided in the input
2. Identify any data processing, storage, or transfer terms
3. Evaluate compliance with GDPR Articles 6, 13, 14, and 28
4. Flag specific risks with article references
5. Suggest compliant alternative language if issues found

Output format:
- compliance_status: "compliant" | "risk_identified" | "non_compliant"
- risk_level: "low" | "medium" | "high"
- issues: array of issue descriptions with GDPR article references
- suggestions: array of suggested revisions

Constraints:
- Only analyze the specific clause provided, do not infer other contract terms
- Never provide final legal determinations, only flag potential risks
- If clause is outside your expertise (non-GDPR), return compliance_status "out_of_scope"

Define expected input format

Tell the agent what to expect as input and how to interpret it:

Input format:
You will receive a JSON object with the following structure:
{
  "document_text": "The full text of the document to analyze",
  "document_type": "contract" | "policy" | "agreement",
  "analysis_focus": "compliance" | "risk" | "general"
}

If document_type is "contract", apply strict compliance standards.
If analysis_focus is "risk", prioritize identifying potential liabilities.

Specify output format and structure

Ambiguous output formats lead to parsing errors in downstream workflow nodes. Be explicit:

Output format:
Return a JSON object with this exact structure:
{
  "is_approved": boolean,
  "confidence": number between 0 and 1,
  "risk_score": number between 0 and 100,
  "issues_found": array of strings,
  "recommendation": "approve" | "reject" | "review_required"
}

Do not include explanatory text outside this JSON structure.
Do not wrap the JSON in markdown code blocks.
Return only valid JSON.

Include examples of desired behavior

Examples are powerful teaching tools for LLMs. Include 1-2 examples in your system prompt:

Example interaction:

Input:
{
  "ticket_text": "I was charged twice for my subscription this month",
  "customer_tier": "premium"
}

Expected output:
{
  "category": "billing",
  "priority": "high",
  "confidence": 0.95,
  "suggested_action": "refund_duplicate_charge"
}

Set explicit constraints

Repeat critical constraints in multiple formats for emphasis:

CRITICAL CONSTRAINTS:
1. NEVER approve transactions over $5,000
2. NEVER share customer email addresses or phone numbers
3. NEVER make changes to production databases
4. ALWAYS flag ambiguous cases for human review

If you are uncertain about any decision, err on the side of caution and
route to human reviewer.

Structured output

MagOneAI runs agents through a DSPy-style structured-execution layer: rather than asking the model for prose and hoping it parses, the platform builds a typed signature from your schema, renders the expected fields into the prompt, parses the reply against them, and retries with a corrective nudge when the model returns something unparseable.

Defining the output schema

Set guardrails.output_schema on the agent to a JSON Schema describing the object you want back:

{
  "guardrails": {
    "output_schema": {
      "type": "object",
      "properties": {
        "decision": {
          "type": "string",
          "enum": ["approved", "denied", "review_required"],
          "description": "Underwriting decision"
        },
        "approved_amount": {
          "type": "number",
          "description": "Approved loan amount, which may differ from the requested amount"
        },
        "confidence": {
          "type": "number",
          "description": "Confidence in the decision, 0.0 to 1.0"
        },
        "risk_score": {
          "type": "integer",
          "description": "Risk score from 0 to 100, higher is riskier"
        },
        "explanation": {
          "type": "string",
          "description": "Brief explanation of the decision"
        },
        "conditions": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Any conditions attached to approval"
        }
      },
      "required": ["decision", "explanation"]
    }
  }
}

Where inputs come from

Agents do not declare an input schema of their own. Input arrives through the workflow: the START node's declared inputs, and the outputs of upstream activities, which chain implicitly. You reference them in the agent's instructions with template variables such as {{input.document_text}} or {{extract.summary}}.

So the contract has two halves in two different places. The inputs are the workflow's shape, defined at the START node. The output is the agent's own, defined by its schema.

How it flows through a workflow

Guardrails and output validation

Guardrails are the programmatic layer that enforces reliability beyond prompt instructions. While personas and prompts guide LLM behavior, guardrails enforce it. In MagOneAI, the enforced guardrail is a single, powerful one: output schema validation.

Output schema validation

Attach a JSON Schema to the agent (guardrails.output_schema). It shapes the agent's output two ways:

• It is rendered into the system prompt as a structured-output contract, so the model produces the fields and types you expect.
• The output is validated against the schema at the workflow's END node, which rejects output that doesn't conform rather than passing malformed data downstream.

Because it is standard JSON Schema, you express constraints with the usual keywords:

• Types — each field matches its declared type (string, number, boolean, array, object)
• Required fields — output is rejected if a required field is missing
• Allowed values — enum restricts a field to a fixed set of options
• Ranges — minimum / maximum bound numeric values

{
  "type": "object",
  "properties": {
    "decision": { "type": "string", "enum": ["approved", "denied", "review_required"] },
    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
    "risk_score": { "type": "integer", "minimum": 0, "maximum": 100 }
  },
  "required": ["decision", "confidence", "risk_score"]
}

Persona iteration and testing

Building effective personas is an iterative process:

Next steps