Core Concepts

Understanding these fundamental concepts will help you get the most out of AiQarus.

The TDAO Loop

Every AiQarus agent operates using a structured reasoning loop called TDAO: Think, Decide, Act, Observe.


    ┌─────────────────────────────────────────────────────────┐
    │                                                         │
    │   ┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐
    │   │  THINK  │────▶│ DECIDE  │────▶│   ACT   │────▶│ OBSERVE │
    │   └─────────┘     └─────────┘     └─────────┘     └─────────┘
    │        │               │               │               │
    │        ▼               ▼               ▼               ▼
    │   [Analyze]       [Choose]        [Execute]      [Summarize]
    │                       │
    │                       ├── Complete ──▶ Exit
    │                       ├── Continue ──▶ Loop ─────────────┘
    │                       └── Fail ──────▶ Exit with Error
    │
    └─────────────────────────────────────────────────────────┘

Phase Descriptions

Phase	What Happens	Output
Think	Agent analyzes the current situation, considering the original input and any previous observations	Reasoning trace
Decide	Based on analysis, choose: Continue (with action), Complete (with output), or Fail (with error)	Decision + rationale
Act	Execute the decided action (tool call, API request, etc.)	Action result
Observe	Summarize results to inform the next iteration	Observation summary

Why TDAO Matters

Unlike black-box AI systems, TDAO provides:

Transparency: Every step of reasoning is recorded
Debuggability: When something goes wrong, you can trace exactly where
Auditability: Regulators can review the decision-making process
Reproducibility: Same inputs produce same reasoning paths

Audit Trails & Hash Chaining

Every action in AiQarus creates a trace event that is cryptographically chained to the previous event.

How It Works


Trace 1 ──▶ Trace 2 ──▶ Trace 3 ──▶ Trace 4
   │           │           │           │
   ▼           ▼           ▼           ▼
Hash A ◀── Hash B ◀── Hash C ◀── Hash D
           (includes    (includes    (includes
            Hash A)      Hash B)      Hash C)

Each trace contains:

Event Type: What happened (step_started, tool_executed, decision_made, etc.)
Payload: Full details of the event
Timestamp: When it occurred
Previous Hash: Link to the prior trace
Current Hash: SHA-256 of all trace data + previous hash

Verification

To verify an audit trail:

Load all traces for a run
Recompute each hash from the trace data
Verify each hash matches and chains correctly

If any trace has been modified, the entire chain becomes invalid.

Agent Lifecycle

Agents progress through defined states:


DRAFT ──▶ ACTIVE ──▶ DEPRECATED ──▶ ARCHIVED
  │          │            │
  │          │            └── Still viewable, not runnable
  │          └── Superseded by new version
  └── Editable, not runnable

State	Editable	Runnable	Versionable
Draft	Yes	No	No
Active	No	Yes	Yes
Deprecated	No	No	No
Archived	No	No	No

Once an agent is activated, its definition becomes immutable. This ensures that audit trails always reference the exact configuration that was used.

Multi-Tenancy

AiQarus is designed for enterprise multi-tenancy:


Platform
└── Organization (Tenant)
    └── Project
        └── Agent
            └── Run
                └── Step
                └── Trace

Data Isolation

Every entity has an org_id field
Database queries always filter by organization
No cross-tenant data access is possible
API keys are scoped to organizations

Human-in-the-Loop

Agents can be configured to pause for human approval:

Interactivity Modes

Mode	Behavior	Use Case
Autonomous	Never pause, execute all actions	Low-risk, high-volume
Key Decisions	Pause for high-risk actions only	Standard workflows
Conversational	Frequent checkpoints	Sensitive processes

Decision Points

When an agent encounters a high-risk action, it creates a decision point:


┌─────────────────────────────────────────────┐
│      🛑 APPROVAL REQUIRED                   │
│                                             │
│  Action: Revoke admin access                │
│  Risk Level: HIGH                           │
│                                             │
│  [✓ Approve]  [✗ Deny]  [⚡ Escalate]       │
└─────────────────────────────────────────────┘

Memory System

Agents have access to a 5-level hierarchical memory system:

Level	Scope	Lifespan	Use Case
Working	Single run	Until run completes	Current task context
Short-term	Single agent	Hours to days	Recent task history
Episodic	Single agent	Permanent	Past run experiences
Semantic	Single agent	Permanent	Facts and knowledge
Organizational	All agents	Permanent	Shared company knowledge

Learn more in the Memory System section.