Skip to main content
HarnessAgent combines reasoning, tools and context management with workspace, long-term memory, skills, subagents and sandboxes. Start with a working conversation in Quickstart, then add capabilities for your application. ReActAgent provides the reasoning loop, tools, permissions and conversation context APIs. Harness composes these capabilities with additional defaults and integrations. Both support call and streamEvents. Configure a shared HarnessAgent.Builder at startup, build a fresh instance for each direct request, and close it after execution. Stable identity and the same log backend preserve the conversation. See Instance lifecycle for code and the shared-instance option. A session manager retains the Agent for background AgentSession execution.

​
Core working principle

An execution loads the conversation state, builds model input, calls tools as needed and saves its results. Workspace, memory and compaction capabilities take effect during these steps. Applications customize behavior through the builder, tools and middleware.

​
Choose an invocation style

  • Get a reply or invoke an Agent within a workflow: use call(input, ctx).
  • Display live text and tool progress within the current request: use streamEvents(input, ctx).
  • Keep tasks running in the background, with queueing, guidance and interrupted-task continuation: use AgentSession from agent.session(ctx).
Direct calls support ongoing conversations and save state through the default Session Log and checkpoints. AgentSession also handles durable task acceptance, scheduling and pending-action association, so applications do not need to manage execution subscriptions for these operations. Both styles use the same Agent’s model, tools and middleware configuration. See Agent for direct calls and Session operations, events and recovery for background session workflows. Applications with an existing workflow scheduler can continue using direct calls; hosted HTTP integrations use the Service Agent API.

​
Core components

Configure capabilities and use session operations as your application needs them.

​
How state flows

Three layers exist; the framework moves data between them automatically.
  • In-call state — AgentState (conversation context, permission rules, Plan Mode state, tool state) plus RuntimeContext (sessionId, userId, sandbox handle, extras).
  • Cross-call state — Default recovery uses native checkpoints and applicable facts; full history remains and JSONL is exported only on demand. LEGACY use AgentStateStore; files, tasks and sandbox metadata retain their own backends.
  • Long-term memory — accumulated across sessions: memory/YYYY-MM-DD.md is append-only, periodically merged into MEMORY.md by a throttled background job; MEMORY.md loads once per call as reference context, not System instructions.
Three invariants worth remembering:
  • Final requests are rebuilt each reasoning step, but workspace files load per call. Edits to AGENTS.md or MEMORY.md take effect on the next call without restarting.
  • Compaction, memory distillation, and background maintenance are throttled; they don’t run every turn.
  • Core manages persistence: EVENT_LOG commits checkpoints; LEGACY save legacy state. Harness selects the default log backend.

​
Adding your own middleware

To insert custom behaviour without bypassing Harness’s plumbing:
  • Use .middleware(...) — your middleware runs before all Harness built-ins.
  • Read RuntimeContext from the agent for the current call’s identity (userId / sessionId).
  • For workspace I/O, go through harnessAgent.getWorkspaceManager() — it routes correctly under sandbox or remote-store modes. java.nio.Files writes to the host disk and will land in the wrong place outside local mode.
  • Session operations, events and recovery — background tasks, queues, interaction and continuation
  • Recoverable chat example — a complete application from submission to frontend reconnection
  • Workspace — directory layout, instruction and reference sources, tools.json
  • Context & AgentState — AgentState, RuntimeContext, AgentStateStore persistence, multi-user isolation
  • Memory — two-layer memory
  • Context management — build model input, track long-running tasks, summarize history, and offload large results
  • Filesystem — local + shell / shared store / sandbox
  • Sandbox — isolated execution, cross-call recovery, distributed
  • Subagent — declarations, sync/background, streaming forwarding
  • Skill — four-layer composition, self-learning loop
  • Plan Mode — read-only phase + HITL exit
  • Channel — session management, multi-agent routing, streaming SSE

​
Final model input construction

Harness organizes System, conversation, task state and references at the final model-call boundary. Supply dynamic business information through contextSource. See Context management for configuration, defaults and limits.