Configuration

Every agent is configured independently per tenant. Configuration controls operating mode, risk thresholds, enabled status, and custom agent-specific parameters.

Configuration model

Field	Type	Description
mode	shadow | active | disabled	Operating mode for the agent
auto_act_threshold	LOW | MEDIUM | HIGH | CRITICAL	Maximum risk level the agent can act on autonomously (active mode only)
enabled	boolean	Whether the agent is enabled for this tenant
config	object	Custom key-value configuration specific to the agent type

Default configuration

When a tenant first interacts with an agent, the platform applies these defaults:

{
  "mode": "shadow",
  "auto_act_threshold": "LOW",
  "enabled": true,
  "config": {}
}

All agents start in shadow mode with the most conservative risk threshold.

Updating configuration

Use the PUT /ai/agents/{agent_id}/config endpoint to update any combination of fields:

curl -X PUT https://api.korastratum.com/ai/api/v1/ai/agents/fraud_prevention_agent/config \
  -H "Authorization: Bearer $KORA_API_KEY" \
  -H "X-Tenant-ID: $KORA_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "active",
    "auto_act_threshold": "MEDIUM",
    "enabled": true,
    "config": {
      "velocity_window_minutes": 30,
      "max_failed_otps": 5
    }
  }'

You only need to include the fields you want to change. Omitted fields remain unchanged.

Operating modes

Shadow mode

The agent observes real data and makes decisions, but never acts. Decisions are logged for comparison with human outcomes. This is the default and recommended starting mode.

Active mode

The agent acts autonomously on decisions at or below the auto_act_threshold risk level. Decisions above the threshold are escalated to humans via the workflow system.

Disabled mode

The agent is completely turned off for this tenant. It will not run on any trigger (manual, scheduled, or event-driven). Use this to temporarily disable an agent without removing its configuration.

Risk threshold levels

The auto_act_threshold controls the maximum risk level at which the agent can act autonomously:

Level	Description	Typical use
LOW	Only low-risk, high-confidence decisions	Conservative default. Good for initial activation.
MEDIUM	Low and medium-risk decisions	Standard operating level for proven agents.
HIGH	Low, medium, and high-risk decisions	For agents with strong track records.
CRITICAL	All decisions including critical-risk	Not recommended. Use only for fully trusted agents with human oversight.

Custom configuration

The config field accepts an arbitrary JSON object for agent-specific parameters. Each agent type documents its supported configuration keys.

Example for the fraud prevention agent:

{
  "config": {
    "velocity_window_minutes": 30,
    "max_failed_otps": 5,
    "structuring_threshold_amount": 9500,
    "auto_freeze_on_ato": true
  }
}

Example for the reconciliation agent:

{
  "config": {
    "timing_tolerance_hours": 24,
    "rounding_threshold": 0.02,
    "auto_resolve_duplicates": true
  }
}

Per-tenant isolation

Agent configuration is fully isolated per tenant:

• Tenant A can have the fraud agent in active mode while Tenant B has it in shadow mode
• Each tenant's decision history, metrics, and shadow comparison data are independent
• Custom configuration parameters are tenant-specific
• Enabling or disabling an agent for one tenant has no effect on other tenants