Skip to main content

Agent Harness

The Harness is the core of cascadeflow’s runtime intelligence. It wraps agent execution and decides whether a model call should proceed, switch models, remove tools, or stop.

What the Harness Does

At every LLM call or tool execution inside an agent loop, the Harness:
  1. Checks hard constraints: Budget remaining, compliance allowlist, tool-call cap, latency limit, and energy limit.
  2. Scores soft dimensions: Quality, cost, latency, and energy weighted by KPI priorities.
  3. Decides an action: allow, switch_model, deny_tool, or stop.
  4. Records a trace: Action, reason, model, step, cost, and budget state.
In observe mode, decisions are recorded but not enforced. In enforce mode, they shape execution in real time.

HarnessConfig

Harness behavior is configured through one language-specific object.

The Three-Tier API

cascadeflow offers three levels of control. Use the one that fits your needs.

Tier 1: Global Init (Zero-Change)

Best for: first rollout, measuring baseline costs, auditing compliance.

Tier 2: Scoped Run (Block-Level Control)

Best for: per-request budgets, scoped policy, session-level metrics.

Tier 3: Agent Decorator (Per-Agent Policy)

Best for: Attaching policy metadata in multi-agent systems. Use a scoped run() when the policy must be enforced.

Decision Priority

When the Harness evaluates a step, it follows a strict priority order: Hard constraints (budget, compliance) always take priority over soft scoring (KPI weights).

Six Dimensions at a Glance

Observe vs Enforce

Start with observe to validate your policies against real traffic. Switch to enforce when you are confident the rules are correct.
Python API: HarnessConfig | TypeScript API: Harness | Parity notes: Python and TypeScript Parity

Next Step

See how the Harness operates inside multi-step agent loops. Understand the Agent Loop →