Kova Core Concepts
From Agent, Workflow, and Swarm to WAL persistence — understand Kova’s core architecture components and design philosophy.
Basic unit of execution: Prompt + Model + Tools + Memory
Orchestrate multiple Agents into an ordered execution pipeline
Multiple Agents collaborate autonomously, communicating directly via the A2A protocol
Write-ahead log + CRC32 checksums, automatic crash recovery
Agent
An Agent is the basic unit of execution, composed of the following elements:
| Element | Description |
|---|---|
| System PromptSystem PromptA system prompt that defines the AI's role, capability boundaries, and behavioral rules. It goes first in the message array. | Defines the Agent’s role, capability boundaries, and behavioral norms |
| Model | The LLM model in use (switchable at runtime) |
| Tools | The set of tools the Agent can invoke |
| Memory | The Agent’s conversation history and persisted state |
Agent Lifecycle
graph LR
Created --> Idle
Idle --> Running
Running --> Completed
Running --> Paused
Running --> Failed
Running --> Recovering
Paused -.resume.-> Running
Recovering -.replay WAL.-> Running| State | Meaning |
|---|---|
| Idle | Agent created, awaiting a task |
| Running | Executing a task |
| Paused | Manually paused, can be resumed |
| Completed | Task finished |
| Failed | Execution failed (retry limit exceeded) |
| Recovering | Detected an incomplete WAL record, recovering automatically |
Agent Decision Loop
graph LR
A[Receive task / previous result] --> B[LLM reasoning<br/>analyze + plan]
B --> C{Tools needed?}
C -->|Yes| D[Invoke tool] --> E[Tool result] --> B
C -->|No| F[Generate final answer] --> G[Return result]Every round is persisted to disk
Workflow
A Workflow orchestrates multiple Agents or steps into an ordered execution pipeline.
Step Types
| Type | Description |
|---|---|
| Agent step | Delegates execution to a specified Agent |
| Conditional branch | Chooses a different path based on the previous step’s result |
| Parallel step | Multiple steps execute simultaneously |
| Wait step | Waits for an external event or human approval |
| Loop step | Repeats execution until a condition is met |
Data Passing
Steps pass data between one another via template variables:
{{input.topic}} → 工作流输入参数
{{steps.research.output}} → "research" 步骤的输出
{{steps.research.metadata}} → "research" 步骤的元数据Error Handling
Each step can be configured with its own error strategy:
| Strategy | Behavior |
|---|---|
retry | Retry N times (default 3, exponential backoff) |
skip | Skip the failed step and continue |
abort | Terminate the entire workflow |
fallback | Switch to a backup step |
SwarmSwarmA swarm-intelligence pattern in which a coordinator assigns tasks to multiple agents that collaborate autonomously, with no predefined fixed workflow.Learn more → (Swarm Intelligence)
Swarm mode lets multiple Agents collaborate autonomously, without a predefined fixed process.
How It Works
graph LR
U[User task] --> C[Coordinator Agent]
C --> S[Decompose subtasks]
S --> R[Research Agent]
S --> D[Coding Agent]
S --> T[Testing Agent]
R --> M[Collect results]
D --> M
T --> M
M --> O[Synthesize output]Agents communicate directly via the A2A (Agent-to-Agent)A2AThe Agent-to-Agent protocol, which lets multiple agents communicate directly, delegate tasks, and exchange information. protocol:
{
"from": "coordinator",
"to": "researcher",
"type": "task_delegate",
"payload": {
"task": "调研 WebAssembly 在服务端的性能基准",
"constraints": {
"max_tokens": 2000,
"deadline": "5min"
}
}
}WALWALWrite-Ahead Log. Every state change is written to the log before it executes, ensuring recovery from the log after a crash.Learn more → (Write-Ahead Log)
The WAL is the core mechanism of Kova’s persistence, drawing on database system design.
Write Flow
graph LR
A[Agent state change] --> B[Serialize + CRC32<br/>compute checksum]
B --> C[Write to WAL file<br/>log first]
C --> D[Perform the actual operation]
D --> E[Mark WAL complete<br/>confirm commit]Recovery Flow
On startup, the WAL is scanned automatically to recover incomplete operations:
- Completed records — skip.
- CRC32 check failure — mark as corrupted and skip.
- Incomplete records — re-execute.
Ring BufferRing BufferA fixed-size circular storage structure. When the write pointer reaches the end it wraps around and overwrites old data; the WAL uses a power-of-2-sized ring buffer.
The WAL uses a power-of-2-sized ring buffer:
- The write pointer wraps around automatically when it reaches the end
- Confirmed old records are overwritten by new ones
- Compaction is triggered when the buffer is full
Sync Modes
| Mode | Description | Performance | Durability |
|---|---|---|---|
normal | The operating system decides when to fsync | High | May lose a few seconds of data |
full | fsync on every write | Low | Zero data loss |
Encryption Options
WAL encryption can be enabled for sensitive scenarios:
| Algorithm | Description |
|---|---|
aes-256-gcm | Standard AES-256 encryption |
sm4 | Chinese national SM4 algorithm |
HMAC integrity verification can also be enabled to prevent tampering with WAL files.
Lock Ordering
Kova internally uses a strict lock-acquisition order to fundamentally eliminate deadlocks:
graph LR
A[Buffer Lock] --> B[Queue Lock] --> C[Transaction Lock]Compile-time deadlock prevention
Tool System
Built-in Tools
| Tool | Function |
|---|---|
web_search | Search the internet |
file_read | Read a file |
file_write | Write a file |
http_request | Send an HTTP request |
shell_exec | Execute a shell command (sandboxed environment) |
db_query | Query a database |
MCP Tools
Connect to external tool services via the Model Context Protocol:
# kova.toml
[[mcp.servers]]
name = "github"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxx" }
[[mcp.servers]]
name = "postgres"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
env = { DATABASE_URL = "postgres://..." }Agents can invoke MCP tools exactly as they would built-in tools.
A2A Protocol
The Agent-to-Agent communication protocol supports:
- Task delegation: One Agent hands a subtask to another
- Information query: Agents exchange information directly
- Result notification: Notify the initiator once a task completes
- Capability discovery: Query what other Agents can do
Feature Tiers
Kova uses Rust feature flags to control compilation scope. A minimal build needs only pure-rust, with layers added as needed: serde (serialization), workflow (workflow orchestration) → agent (Agent engine) → swarm (swarm intelligence), encrypt (encryption) → sm4 (Chinese national cryptography) / wal-hmac (integrity verification), and so on.