Agent State

Overview

Agents operate in one of two modes: Plan or Execute. This state is persisted across conversation turns and survives LLM context summarization.

The agent state system ensures that agents maintain a consistent operational mode throughout a session, enabling structured reasoning before action execution.

Modes

Plan Mode

In Plan mode, the agent generates plans and reasoning before executing actions. This is the default mode when a new session starts.

Characteristics:

• The agent produces structured plans before taking actions
• Reasoning is explicit and documented
• Actions are validated against the plan
• Useful for complex multi-step tasks

Execute Mode

In Execute mode, the agent executes actions directly without generating intermediate plans.

Characteristics:

• The agent responds and acts immediately
• No intermediate planning step
• Faster for simple, direct tasks
• Useful for conversational interactions

State Persistence

The agent state is stored in the database and persists across:

• Individual conversation turns
• LLM context summarization
• Browser page refreshes

This means the agent remembers its mode even after the conversation context has been compressed.

Session State

Updated in v0.3.19 — mode, plan file, and task tracking have been migrated from Agent State to a dedicated Session State.

Beginning in v0.3.19, each active chat session maintains its own Session State that tracks:

Component	Description
Mode	Whether the agent is in Plan or Execute mode for this session
Plan File	The current plan (if any) stored in the agent’s workspace
Tasks	The current task list being tracked
Namespace	Active workflow namespaces (e.g., kanban task state)

Session State Panel

The Session State is displayed in the chat UI’s right panel with:

• Mode badge — Shows “Plan” or “Execute” at a glance so you always know what mode the agent is in
• Task list — Rendered as formatted markdown for easy reading
• Plan file display — Shows the current plan content if one exists
• Namespace states — Active workflow states (like kanban task tracking) are visible

What Changed

Previously, mode, plan file, and task tracking were part of the Agent State (scoped to the agent itself). Starting in v0.3.19, they are now scoped to the session, meaning:

• Different conversations with the same agent can have different modes
• Plan files are session-specific
• Task tracking is per-session

This change replaced the old “Session Recap” panel with the more informative Session State panel.

Updating the Task List

Agents manage their task list with the update_tasks tool. Each call takes an action:

Action	What it does
set	Replace the entire task list with a structured tasks array
add	Add one atomic task
in_progress	Make one task the sole active task; every other active task returns to pending
done	Mark one task complete
replace	Change a task’s text while keeping its ID and status
update	New in v1.6.0. Change only specific tasks — pass tasks items with id plus a new text and/or status; unlisted tasks are left untouched
remove	Delete a task

update is the surgical option. Before v1.6.0, changing one task’s wording meant replaying the whole list with set. Now the agent only sends what changed:

{
  "action": "update",
  "tasks": [
    { "id": 3, "status": "done" },
    { "id": 5, "text": "Write the migration script" }
  ]
}

Tasks keep their IDs across updates, so statuses and references don’t drift.

Plan File

When an agent is in Plan mode, it can create a plan file that persists across conversation turns. The plan file is stored in the agent’s workspace directory and survives summarization.

Location: agents/<agent_id>/workspace/plan.md

The plan file contains:

• Current task objectives
• Step-by-step plan
• Progress tracking
• Notes and observations

How It Works

1. When a new session starts, the agent begins in Plan mode
2. The agent can transition to Execute mode when appropriate
3. The session state is saved to the database after each turn
4. On session resume, the agent restores its previous mode
5. The plan file (if exists) is loaded into context

Task Complexity Classifier

Introduced in v0.2.6.

The agent runtime includes an automatic task complexity classifier that determines whether a full planning phase is necessary before execution. For trivial or simple tasks, the classifier skips the planning step entirely, speeding up response time.

How It Works

When a user sends a message, the classifier evaluates it before the agent enters Plan mode:

1. Analyze the message for complexity signals (length, technical terms, multi-step indicators, tool requirements)
2. Classify as trivial, simple, or complex
3. Decide whether planning is needed

Classification	Planning	Example
Trivial	Skipped	”What time is it?”, “Hello”
Simple	Skipped	”Tell me a joke”, “Search for evonic on GitHub”
Complex	Full plan generated	”Research competitor pricing, summarize findings, and generate a report”

Benefits

• Faster response times — trivial tasks skip the planning overhead
• Reduced token usage — no unnecessary plan generation
• Smarter behavior — the agent doesn’t over-plan simple requests

Configuration

The classifier is enabled by default. You can disable it per-agent in the General tab by toggling the Task Complexity Classifier setting (task_complexity_classifier: 0).

Task Lifecycle

Introduced in v1.1.2.

The agent runtime enforces a proper task lifecycle to ensure reliable execution and prevent stale state from lingering across sessions. Each task the agent works on goes through a defined lifecycle with enforced transitions.

Lifecycle States

State	Description
Todo	Task is on the board but not yet started
In Progress	Agent has picked up the task and is actively working
Done	Task completed successfully

Enforced Transitions

The tool loop enforces valid transitions between task states. Agents cannot skip steps — for example, a task must be moved to In Progress before it can be marked Done.

Self-Healing on Session Wake

When a session wakes up after a restart or disconnect, the runtime automatically detects and heals stale task state. If an agent had a task in In Progress from a previous session, that stale state is cleaned up so the agent doesn’t pick up abandoned work from an old conversation.

Vault Janitor Scheduling

The Vault Janitor — Evonic’s background cleanup service — receives scheduling controls to manage task lifecycle housekeeping. This includes periodic purging of orphaned task metadata and stale session-task associations.

Live Task Feedback

Task state changes are streamed live to the UI. When an agent transitions a task (e.g., starting work or completing it), the session state panel updates immediately so you can follow along in real time.

Runtime (v1.5.6)

Updated in v1.5.6.

The agent runtime and the session state panel received a set of improvements that make long sessions more predictable and easier to follow.

Request Budget Preflight

Before each LLM request is sent, the runtime plans the request against the model’s context budget. This preflight checks whether the planned payload (messages, tools, and any required tool choice) fits within the model’s context window with a safety margin.

• enforced mode (default) — if a request can’t be reduced to fit the budget, the turn fails with a clear message (“The current request exceeds this model’s safe context budget and cannot be reduced without removing required context”) instead of a cryptic provider error.
• shadow / canary modes — the budget is computed and reported, but not enforced. Useful for observing headroom before turning enforcement on.
• off — preflight is disabled.

The mode is controlled by the REQUEST_BUDGET_MODE environment variable (off, shadow, canary, or enforced), and the safety margin by REQUEST_BUDGET_SAFETY_MARGIN (default 512 tokens).

Active Monitors in the State Panel

The session state panel now lists the session’s active monitors — the background conditions the runtime is watching (for example, a process or a shell predicate). A Monitors row shows the count of active monitors, and clicking it opens a detail modal for each one.

Rendered Markdown Plan Modal

The plan file now opens in a modal instead of being shown as raw text in the panel:

• Preview tab — the plan rendered as Markdown, so it’s readable at a glance.
• Edit tab — an editable view, so you can tweak the plan directly without leaving the chat.

This makes it easier to read and adjust the agent’s plan mid-session.

Example:

You’re watching a long-running task and want to nudge the agent. Open the plan from the state panel, switch to the Edit tab, add a note about a constraint you just discovered, and save — the agent picks it up on its next turn.

Configuration

The agent mode can be influenced by:

• The system prompt (instructions about planning behavior)
• The task complexity classifier (automatic mode selection)
• User preference (explicit mode requests via /plan and /execute)

API Reference

Method	Endpoint	Description
GET	/api/agents/<id>/state	Get current agent state
PUT	/api/agents/<id>/state	Update agent state