Natural Language Input

AiQarus agents can accept natural language instructions instead of requiring structured form input. This makes agents accessible to non-technical users and reduces friction.

How It Works


┌─────────────────────────────────────────────────────────────────────┐
│  User: "Offboard Sarah Chen from engineering, she's leaving for    │
│         Google next Friday"                                         │
│                                                                      │
│                              │                                       │
│                              ▼                                       │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                  LLM Entity Extraction                       │    │
│  │                                                              │    │
│  │  • employee_name: "Sarah Chen"     confidence: 95%           │    │
│  │  • department: "engineering"       confidence: 85%           │    │
│  │  • departure_type: "competitor"    confidence: 90%           │    │
│  │  • destination: "Google"           confidence: 95%           │    │
│  │  • last_day: "2026-01-17"          confidence: 85%           │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                              │                                       │
│                              ▼                                       │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    User Confirmation                         │    │
│  │                                                              │    │
│  │  Extracted:                                                  │    │
│  │  • Employee: Sarah Chen              ✓ High confidence       │    │
│  │  • Departure: Competitor (Google)    ✓ High confidence       │    │
│  │  • Last Day: January 17, 2026        ○ Review recommended    │    │
│  │                                                              │    │
│  │            [Confirm & Execute]    [Edit]    [Start Over]     │    │
│  └─────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────┘

Enabling NLP Input

Step 1: Define Input Schema

First, define what structured data your agent expects:


{
  "type": "object",
  "properties": {
    "employee_name": {
      "type": "string",
      "description": "Full name of the employee"
    },
    "department": {
      "type": "string",
      "description": "Department the employee works in"
    },
    "departure_type": {
      "type": "string",
      "enum": ["voluntary", "involuntary", "competitor", "retirement"]
    },
    "last_working_day": {
      "type": "string",
      "format": "date"
    }
  },
  "required": ["employee_name", "last_working_day"]
}

Step 2: Configure NLP Settings

In the Agent Builder or via API, enable NLP and configure extraction:


{
  "nlp_enabled": true,
  "nlp_config": {
    "extraction_prompt": "Extract employee offboarding details from the input.",
    "entity_hints": {
      "employee_name": "The name of the person being offboarded",
      "departure_type": "Why they are leaving: voluntary resignation, termination, joining competitor, or retiring"
    },
    "examples": [
      "John is leaving next week",
      "Terminate access for Jane Doe immediately",
      "Marcus is going to a competitor, last day Friday"
    ],
    "clarification_prompts": {
      "last_working_day": "When is their last day?"
    }
  }
}

Confidence Scoring

Each extracted value includes a confidence score (0-100%):

Confidence	Display	Action
90-100%	✓ High confidence	Auto-accept
70-89%	○ Review recommended	Highlight for review
Below 70%	⚠ Low confidence	Require confirmation

Configuring Thresholds


{
  "nlp_config": {
    "confidence_thresholds": {
      "auto_accept": 90,
      "require_review": 70,
      "require_clarification": 50
    }
  }
}

The Confirmation Flow

When NLP extracts values, users see a confirmation screen:


┌─────────────────────────────────────────────────────────────────────┐
│  You said: "Offboard Sarah Chen from engineering..."                │
│                                                                      │
│  We extracted:                                                       │
│                                                                      │
│  Employee Name         Sarah Chen                    ✓ 95%          │
│  Department           Engineering                   ✓ 85%          │
│  Departure Type       Competitor (Google)           ✓ 90%          │
│  Last Working Day     January 17, 2026              ○ 85%  [Edit]  │
│                                                                      │
│  ─────────────────────────────────────────────────────────────────  │
│                                                                      │
│       [✓ Confirm & Execute]        [Start Over]                     │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Users can:

Confirm - Proceed with extracted values
Edit - Modify any extracted value
Start Over - Re-enter the instruction

Handling Ambiguity

When the NLP system detects ambiguity, it asks clarifying questions:


┌─────────────────────────────────────────────────────────────────────┐
│  Input: "Offboard Sarah"                                            │
│                                                                      │
│  ⚠ We need some clarification:                                      │
│                                                                      │
│  Found multiple employees named "Sarah":                            │
│  ○ Sarah Chen (Engineering)                                         │
│  ○ Sarah Miller (Marketing)                                         │
│  ○ Sarah Johnson (Sales)                                            │
│                                                                      │
│  Which Sarah should be offboarded?                                  │
│                                                                      │
│  When is their last working day?                                    │
│  [_______________]                                                  │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Best Practices

Write Good Extraction Prompts

Be specific about field meanings
Provide examples of expected input
Explain edge cases and how to handle them

Provide Entity Hints

Help the LLM understand your domain:


{
  "entity_hints": {
    "risk_level": "How risky is this departure: competitor means high risk, retirement means low risk",
    "access_scope": "What systems does this person have access to"
  }
}

Include Examples

The more examples you provide, the better extraction accuracy:


{
  "examples": [
    "John is resigning, his last day is next Friday",
    "We need to terminate Maria's access immediately - security concern",
    "Bob is retiring at the end of the month after 30 years",
    "Alice is leaving for Microsoft next week"
  ]
}

Set Appropriate Thresholds

High-stakes processes: Require higher confidence, always confirm
Low-stakes processes: Accept lower confidence, auto-proceed

API Usage

Parse natural language input via GraphQL:


mutation ParseInput($agentId: ID!, $input: String!) {
  parseAgentInput(agentId: $agentId, naturalLanguageInput: $input) {
    extracted {
      field
      value
      confidence
    }
    clarifications {
      field
      question
    }
    overallConfidence
  }
}