Quickstart

This guide walks through enabling an AI agent, triggering it manually, and reviewing its decisions using the REST API.

Prerequisites

• A Korastratum account (sign up)
• Your API key (starts with test_ for sandbox)
• Your Tenant ID (UUID from your dashboard)

Step 1: List available agents

Fetch the full catalog of registered agents to find the one you want to enable.

cURL

curl https://api.korastratum.com/ai/api/v1/ai/agents \
  -H "Authorization: Bearer $KORA_API_KEY" \
  -H "X-Tenant-ID: $KORA_TENANT_ID"

Python

import requests
import os

response = requests.get(
    "https://api.korastratum.com/ai/api/v1/ai/agents",
    headers={
        "Authorization": f"Bearer {os.environ['KORA_API_KEY']}",
        "X-Tenant-ID": os.environ["KORA_TENANT_ID"],
    },
)

agents = response.json()
for agent in agents["agents"]:
    print(f"{agent['agent_id']} ({agent['tier']}) — {agent['description']}")

Node.js

const response = await fetch("https://api.korastratum.com/ai/api/v1/ai/agents", {
  headers: {
    "Authorization": `Bearer ${process.env.KORA_API_KEY}`,
    "X-Tenant-ID": process.env.KORA_TENANT_ID,
  },
});

const { agents } = await response.json();
agents.forEach(a => console.log(`${a.agent_id} (${a.tier}) — ${a.description}`));

Response:

{
  "agents": [
    {
      "agent_id": "reconciliation_agent",
      "tier": "core",
      "product": "gl",
      "description": "Analyzes reconciliation breaks and auto-resolves simple ones (timing, rounding, duplicates)"
    },
    {
      "agent_id": "fraud_prevention_agent",
      "tier": "ml",
      "product": "fraud",
      "description": "Real-time fraud pattern detection (ATO, structuring, velocity breach) with autonomous freeze/OTP/flag response"
    }
  ],
  "total": 22
}

Step 2: Check agent status

Before configuring an agent, check its current status for your tenant.

cURL

curl https://api.korastratum.com/ai/api/v1/ai/agents/reconciliation_agent/status \
  -H "Authorization: Bearer $KORA_API_KEY" \
  -H "X-Tenant-ID: $KORA_TENANT_ID"

Python

response = requests.get(
    "https://api.korastratum.com/ai/api/v1/ai/agents/reconciliation_agent/status",
    headers={
        "Authorization": f"Bearer {os.environ['KORA_API_KEY']}",
        "X-Tenant-ID": os.environ["KORA_TENANT_ID"],
    },
)

status = response.json()
print(f"Mode: {status['mode']}, Enabled: {status['enabled']}")

Response:

{
  "agent_id": "reconciliation_agent",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "registered": true,
  "mode": "shadow",
  "auto_act_threshold": "LOW",
  "enabled": true,
  "last_run": null,
  "total_runs": 0
}

New agents default to shadow mode with a LOW auto-act threshold.

Step 3: Configure the agent

Enable the agent and set its operating mode. Start with shadow mode to observe decisions before activating.

cURL

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

Python

response = requests.put(
    "https://api.korastratum.com/ai/api/v1/ai/agents/reconciliation_agent/config",
    headers={
        "Authorization": f"Bearer {os.environ['KORA_API_KEY']}",
        "X-Tenant-ID": os.environ["KORA_TENANT_ID"],
    },
    json={
        "mode": "shadow",
        "auto_act_threshold": "MEDIUM",
        "enabled": True,
    },
)

print(response.json())  # {"status": "updated", "agent_id": "reconciliation_agent", ...}

Step 4: Trigger the agent manually

Run the agent on demand with custom trigger data. In shadow mode, the agent observes and decides but does not act.

cURL

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"
    }
  }'

Python

response = requests.post(
    "https://api.korastratum.com/ai/api/v1/ai/agents/reconciliation_agent/trigger",
    headers={
        "Authorization": f"Bearer {os.environ['KORA_API_KEY']}",
        "X-Tenant-ID": os.environ["KORA_TENANT_ID"],
    },
    json={
        "trigger_data": {
            "date": "2026-04-06",
            "account_type": "clearing",
        }
    },
)

decision = response.json()
print(f"Decision: {decision['decision']} (confidence: {decision['confidence']}%)")

Response:

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

Since the agent is in shadow mode, action_taken is false. The decision is logged for comparison with human outcomes.

Step 5: Review decisions

Fetch the decision history to see how the agent performed.

cURL

curl "https://api.korastratum.com/ai/api/v1/ai/agents/reconciliation_agent/decisions?limit=10" \
  -H "Authorization: Bearer $KORA_API_KEY" \
  -H "X-Tenant-ID: $KORA_TENANT_ID"

Python

response = requests.get(
    "https://api.korastratum.com/ai/api/v1/ai/agents/reconciliation_agent/decisions",
    headers={
        "Authorization": f"Bearer {os.environ['KORA_API_KEY']}",
        "X-Tenant-ID": os.environ["KORA_TENANT_ID"],
    },
    params={"limit": 10},
)

data = response.json()
for d in data["decisions"]:
    print(f"{d['created_at']} — {d['decision']} ({d['confidence']}%) agreed={d['human_agreed']}")

What's next

• Shadow Mode — Understand the 2-week observation period and activation thresholds
• Configuration — Fine-tune agent mode, risk thresholds, and custom parameters
• Triggering Agents — Manual triggers, scheduled execution, and event-driven activation
• Decisions & Audit — Decision logging, human comparison, and compliance reporting