mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-03 08:06:01 +08:00
127 lines
4.3 KiB
Plaintext
127 lines
4.3 KiB
Plaintext
---
|
|
title: Agent Overview
|
|
sidebarTitle: Overview
|
|
description: How IronClaw's agent runtime processes requests and executes jobs
|
|
---
|
|
|
|
IronClaw's agent runtime is an always-on loop that accepts messages from any channel, classifies intent, and dispatches work as parallel jobs — each independently tracked through a defined state machine.
|
|
|
|
## Agent Loop
|
|
|
|
When a message arrives, the agent loop:
|
|
|
|
1. **Classifies intent** — The router determines whether the message is a new task, a follow-up, a command (undo, compact, clear), or a system event
|
|
2. **Creates a job** — Each unit of work gets its own isolated job context with conversation memory
|
|
3. **Schedules execution** — The scheduler dispatches the job to a worker, respecting the `MAX_PARALLEL_JOBS` limit
|
|
4. **Runs the worker** — The worker performs LLM reasoning, selects tools, and executes in a loop until the job reaches a terminal state
|
|
5. **Returns output** — Results stream back to the originating channel in real time
|
|
|
|
```
|
|
Channel Input
|
|
↓
|
|
[Router] → Classify intent
|
|
↓
|
|
[Scheduler] → Check capacity (MAX_PARALLEL_JOBS)
|
|
↓
|
|
[Worker] → LLM reasoning + tool execution
|
|
↓
|
|
[Safety Layer] → Scan outputs
|
|
↓
|
|
Channel Response
|
|
```
|
|
|
|
## Parallel Jobs
|
|
|
|
Multiple jobs run concurrently. Each job has its own context — memory, tool state, and conversation history — isolated from other jobs.
|
|
|
|
| Setting | Default | Description |
|
|
|---------|---------|-------------|
|
|
| `MAX_PARALLEL_JOBS` | `5` | Maximum concurrent jobs per agent instance |
|
|
|
|
When the limit is reached, new requests queue until a job slot opens. The scheduler uses a priority queue and respects job order within the same session.
|
|
|
|
## Job State Machine
|
|
|
|
Every job moves through a defined set of states:
|
|
|
|
```
|
|
Pending
|
|
↓
|
|
InProgress ──────────────┬──► Completed
|
|
↑ │
|
|
│ (recovery) └──► Failed
|
|
│
|
|
Stuck ────────────────────► Failed (if unrecoverable)
|
|
```
|
|
|
|
| State | Meaning |
|
|
|-------|---------|
|
|
| **Pending** | Created, waiting for a worker slot |
|
|
| **InProgress** | Actively executing |
|
|
| **Completed** | Finished successfully |
|
|
| **Failed** | Terminal failure — no further retries |
|
|
| **Stuck** | No progress detected — recovery attempted |
|
|
|
|
The self-repair system monitors InProgress jobs and transitions stuck ones back to InProgress for recovery. See [Self-Repair](/agents/self-repair) for details.
|
|
|
|
## Session Model
|
|
|
|
IronClaw uses a three-level session hierarchy:
|
|
|
|
| Level | Description |
|
|
|-------|-------------|
|
|
| **Session** | A named context (e.g., a project or topic) |
|
|
| **Thread** | A conversation within a session |
|
|
| **Turn** | A single user message + agent response pair |
|
|
|
|
Each turn is a checkpoint. You can undo the last turn, redo a cancelled turn, or compact old turns to reduce context window pressure.
|
|
|
|
## Undo / Redo
|
|
|
|
The agent tracks every turn with a state checkpoint:
|
|
|
|
```
|
|
undo → Revert to the state before the last turn
|
|
redo → Re-apply the most recently undone turn
|
|
compact → Summarize old turns to free context window space
|
|
clear → Reset the current thread
|
|
```
|
|
|
|
Type these commands directly in any channel — the submission parser intercepts them before they reach the LLM.
|
|
|
|
## Context Window Management
|
|
|
|
As conversations grow, context pressure increases. IronClaw handles this automatically:
|
|
|
|
- **Context monitor** tracks token usage per turn
|
|
- **Compaction** summarizes old turns when pressure is high
|
|
- **Manual compact** is available via the `compact` command
|
|
|
|
## Next Steps
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Jobs & Parallel Execution" icon="layers" href="/agents/jobs">
|
|
State machine details, job tools, and concurrency configuration
|
|
</Card>
|
|
|
|
<Card title="Self-Repair" icon="wrench" href="/agents/self-repair">
|
|
Automatic detection and recovery of stuck jobs
|
|
</Card>
|
|
|
|
<Card title="Skills" icon="puzzle" href="/agents/skills">
|
|
Context-aware prompt extensions that activate automatically
|
|
</Card>
|
|
|
|
<Card title="Routines" icon="clock" href="/agents/routines">
|
|
Scheduled and event-driven automation
|
|
</Card>
|
|
|
|
<Card title="Memory" icon="database" href="/agents/memory">
|
|
Persistent workspace with hybrid search
|
|
</Card>
|
|
|
|
<Card title="Heartbeat" icon="activity" href="/agents/heartbeat">
|
|
Proactive periodic execution
|
|
</Card>
|
|
</CardGroup>
|