Running Agents

Learn how to execute agents manually and configure automated triggers.

Manual Runs

Via UI

Navigate to Agents
Select your agent
Click Run
Provide input (form or natural language)
Click Execute

Via API


mutation RunAgent($input: RunAgentInput!) {
  runAgent(input: {
    agentId: "agent_123"
    input: {
      employee_name: "Sarah Chen"
      department: "Engineering"
    }
  }) {
    id
    status
    createdAt
  }
}

Input Methods

Structured Form

Fill in defined fields:


┌─────────────────────────────────────────────────────────────────────┐
│  Run Agent: Employee Offboarding                                     │
│                                                                      │
│  Employee Name *                                                     │
│  [Sarah Chen                              ]                          │
│                                                                      │
│  Department *                                                        │
│  [Engineering                        ▼]                              │
│                                                                      │
│  Departure Type *                                                    │
│  ○ Voluntary                                                         │
│  ○ Involuntary                                                       │
│  ● Competitor                                                        │
│  ○ Retirement                                                        │
│                                                                      │
│  Last Working Day *                                                  │
│  [2026-01-24                          ]                              │
│                                                                      │
│                                            [Execute]                 │
└─────────────────────────────────────────────────────────────────────┘

Natural Language

Describe what you need:


┌─────────────────────────────────────────────────────────────────────┐
│  Run Agent: Employee Offboarding                                     │
│                                                                      │
│  Describe what you need:                                             │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │ Offboard Sarah Chen from engineering. She's leaving for     │    │
│  │ Google next Friday.                                         │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                      │
│                                            [Parse & Review]          │
└─────────────────────────────────────────────────────────────────────┘

Automated Triggers

Cron Triggers

Schedule recurring runs:


trigger:
  type: cron
  schedule: "0 9 * * MON"  # Every Monday at 9 AM
  timezone: "America/New_York"
  input:
    report_type: "weekly_summary"

Webhook Triggers

Trigger via HTTP:


trigger:
  type: webhook
  url: "https://api.aiqarus.com/webhook/agent_123/abc123token"
  method: POST
  authentication:
    type: bearer_token

Usage:


curl -X POST https://api.aiqarus.com/webhook/agent_123/abc123token \
  -H "Content-Type: application/json" \
  -d '{"employee_name": "Sarah Chen"}'

Event Triggers

React to system events:


trigger:
  type: event
  source: "hr_system"
  event: "employee.departure_announced"
  filter:
    department: ["Engineering", "Product"]

Monitoring Runs

Run Status

Status	Meaning
`pending`	Queued, not started
`running`	Currently executing
`paused`	Waiting for human approval
`completed`	Finished successfully
`failed`	Finished with error
`cancelled`	Manually stopped

Real-time Updates

Subscribe to run updates:


subscription OnRunUpdate($runId: ID!) {
  runUpdated(runId: $runId) {
    id
    status
    currentStep
    progress
  }
}

Cancelling Runs

Via UI

Click the Cancel button on a running agent.

Via API


mutation CancelRun($runId: ID!) {
  cancelRun(runId: $runId) {
    id
    status
    cancelledAt
  }
}