Triggering Agents

Agents can be triggered in three ways: manually via API, on a schedule, or in response to events from other services.

Manual trigger

Use the POST /ai/agents/{agent_id}/trigger endpoint to run an agent on demand:

curl -X POST https://api.korastratum.com/ai/api/v1/ai/agents/reconciliation_agent/trigger \
  -H "Authorization: Bearer $KORA_API_KEY" \
  -H "X-Tenant-ID: $KORA_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_data": {
      "date": "2026-04-06",
      "account_type": "clearing"
    }
  }'

The trigger_data object is passed directly to the agent's observe() method. The schema varies by agent type — each agent documents what trigger data it expects.

Response

The response contains the full decision output:

{
  "decision_id": "d4e5f6a7-b8c9-4d0e-a1f2-b3c4d5e6f7a8",
  "decision": "resolve",
  "confidence": 92.5,
  "risk_level": "LOW",
  "reasoning": "3 timing breaks within T+1 tolerance; 1 rounding difference under $0.02",
  "action_taken": false,
  "action_result": null
}

Field	Description
decision_id	Unique identifier for this decision (UUID)
decision	The agent's decision: approve, reject, escalate, resolve, alert, or skip
confidence	Confidence score from 0 to 100
risk_level	Risk classification: LOW, MEDIUM, HIGH, or CRITICAL
reasoning	Human-readable explanation of the decision
action_taken	Whether the agent executed an action (true only in active mode within threshold)
action_result	Result of the action if taken, or null

Manual trigger metadata

When you trigger an agent manually, the platform automatically adds metadata to the trigger data:

• trigger_type: "manual"
• triggered_by: the authenticated user's ID

This metadata is recorded in the decision log for audit purposes.

Scheduled execution

Agents can be configured to run on a schedule via the platform's scheduler service. Common patterns:

Agent	Schedule	Purpose
Reconciliation Agent	Daily at 23:00 UTC	End-of-day reconciliation
Settlement Agent	Daily at 22:00 UTC	EOD settlement batch generation
Treasury Liquidity Agent	Every 4 hours	Liquidity position monitoring
Compliance Monitor Agent	Every 6 hours	Re-screening against updated lists
Corridor Performance Agent	Daily at 06:00 UTC	Daily corridor analytics

Scheduled triggers use trigger_type: "scheduled" in the decision log.

Event-driven activation

Agents can respond to events from other Korastratum services. The platform's event bus routes events to registered agent handlers:

Event	Agent	Action
transaction.completed	Fraud Prevention Agent	Real-time fraud check on new transactions
verification.needs_review	IDV Decision Agent	Auto-review IDV manual review queue
loan.application_submitted	Lending Decision Agent	Pre-screen new loan applications
bill_payment.failed	Bill Pay Recovery Agent	Auto-retry failed bill payments
compliance.case_created	Case Investigation Agent	Auto-investigate new compliance cases
screening.match_found	Match Verification Agent	Verify new screening matches

Event-driven triggers use trigger_type: "event" in the decision log.

Trigger priorities

When multiple triggers fire for the same agent and tenant simultaneously, the platform queues them and processes in order:

1. Manual triggers — highest priority (operator-initiated)
2. Event-driven triggers — medium priority (time-sensitive)
3. Scheduled triggers — lowest priority (can tolerate slight delays)

Disabled agents

If an agent is disabled for a tenant (enabled: false), all triggers are rejected:

• Manual triggers return 400 Bad Request with a message indicating the agent is disabled
• Scheduled triggers are silently skipped
• Event-driven triggers are silently skipped