Core Concepts
Understanding the building blocks of ViksaAI.
Multi-Tenant Architecture
ViksaAI uses a hierarchical multi-tenant structure to organize users, resources, and access control.
Account
The top-level billing entity. Each account has one owner and can contain multiple organizations.
Organization
A workspace within an account. Each org has its own members, roles, and resources.
Project
Work happens inside a project: one chat context, one set of linked agents, mappings, and settings for that goal.
Example: A company "Acme Corp" (account) might have two organizations: "Production" and "Development", each with their own set of agents and users.
Agents
Agents are specialized, reusable units of automation written in Python. Each agent has defined inputs, outputs, and one or more endpoints.
Cloud
Managed runtime on the platform— the default path. No worker install required for most teams.
Secure
Run on your Chrona workers— for private networks, on-prem data, and environments you fully control. Configure queues and keys in the agent editor.
See Agent types and Chrona Workers for setup details.
Agent Components
| Component | Description |
|---|---|
| Inputs | Parameters the agent accepts (name, type, description) |
| Outputs | Data the agent returns after execution |
| Endpoints | Callable functions within the agent |
| Files | Python modules that contain the agent's code |
| Requirements | Python dependencies (e.g. requirements.txt) installed at build time |
| Auth & credentials | Declared auth methods and vault-backed secrets, read in code via ViksaAuth (guide) |
| AI guidelines | Optional hints for the executor on how to combine endpoints for this agent |
Execution
ViksaAI does not use pre-defined workflows. When you give a goal (in chat, via webhook, or on a schedule), the Agent Executor runs a Think→Act→Observe loop: it thinks about the current state, acts (runs a task or asks you), observes the result, and repeats until the goal is done or paused for your input.
The executor decides at runtime which agents to call and in what order. It can ask for clarification or request approval for sensitive endpoints; when you respond, execution resumes from where it left off.
Key terms
Iteration: one Think→Act→Observe cycle. Mappings: context (e.g. mapping_id → payload) passed into the executor for resolving inputs. Resume state: snapshot used to continue after you answer or approve.
Executions
An execution is a single run of the executor (from chat, trigger, or schedule). It tracks iterations, task results, status, and timing. For triggers and schedules, execution records are stored so you can review history and logs.
Statuses
Chat Interface
The chat interface is your primary way to run execution. Describe your goal in plain English; the executor runs with your project's agents and mappings.
How it works:
- You type a goal in natural language
- The executor thinks and may run one or more agent tasks
- It may ask you a question or request approval for a sensitive action
- You reply or approve; execution resumes until the goal is done
- Results are summarized in the chat
Mappings
Mappings are context you attach to a project (e.g. mapping_id → JSON payload). The executor uses them to resolve agent inputs and follow guidelines, so the same natural-language goal can be applied with different context per project or environment.
Schedules
Schedules run execution at specific times or intervals (cron or recurring). The same Think→Act→Observe engine runs; results are stored for later review.
One-Time
Execute once at a specific date/time
Recurring
Execute at fixed intervals (e.g., every hour)
Cron
Complex schedules using cron expressions