Control Layer Overview

Runtime Controls for AI agents

The Control Layer provides Runtime Controls that prevent AI agents from causing harm. Without these controls, agents can spend unlimited money, loop forever, and break production systems.

Why Control Matters

Without proper control mechanisms, AI agents can cause severe operational and financial damage. Agents may accumulate massive API costs by making unlimited calls to expensive services, enter infinite loops that waste computational resources, overwhelm external APIs with excessive requests leading to rate limit violations, make unauthorized changes to critical systems, or consume unbounded memory until systems crash. These scenarios can transform helpful automation into costly failures that require immediate intervention and system shutdowns.

The Control Layer prevents:

Problem	Control	What it does
Unlimited spending	ExecutionLimits	Hard budget cap
API rate exceeded	RateLimiter	Calls per minute
Cascading failures	CircuitBreaker	Stop after N failures
Infinite loops	LoopDetection	Detect and break loops
Unauthorized actions	ToolAccessController	Per-agent permissions
Flip-flopping decisions	DecisionEnforcer	Lock decisions
Transient failures	RetryStrategy	Retry with backoff
Custom violations	RulesEngine	Your own rules
Memory bloat	MemoryStore	Capped storage

Quick Start

from splinter import Splinter

# Basic limits - that's it!
s = Splinter(
    openai_key="sk-...",
    max_budget=5.0,   # Stop at $5
    max_steps=50,     # Stop after 50 calls
)

result = await s.run("agent", "Do the task")
# Guaranteed to stop at $5 or 50 calls, whichever comes first

Control Objects

ExecutionLimits

Budget, step count, and time limits

RateLimiter

Calls per minute per agent or tool

CircuitBreaker

Stop after repeated failures

LoopDetection

Detect and break infinite loops

ToolAccessController

Which agent can use which tools

DecisionEnforcer

Lock decisions to prevent flip-flopping

RetryStrategy

Retry failed calls with exponential backoff

RulesEngine

Custom BLOCK/WARN/LOG rules

MemoryStore

Capped memory with auto-eviction

How Controls are Applied

Combining Controls

Controls compose naturally:

from splinter import Splinter
from splinter.types import ExecutionLimits, LoopDetectionConfig
from splinter.control import RateLimiter, CircuitBreaker, ToolAccessController

# Basic limits
s = Splinter(openai_key="sk-...", max_budget=10.0, max_steps=100)

# Add rate limiting
limiter = RateLimiter()
limiter.set_agent_limit("researcher", calls=20, window_seconds=60)

# Add circuit breaker
breaker = CircuitBreaker(
    breaker_id="openai",
    failure_threshold=5,
    timeout_seconds=60,
)

# Add tool access control
tool_ctrl = ToolAccessController()
tool_ctrl.set_allowed_tools("researcher", ["web_search", "read_file"])
tool_ctrl.set_allowed_tools("writer", ["write_file"])

# All controls work together

Best Practices

Always set budget limits

Even for testing. A runaway agent can cost thousands. Default to $5-10 for development.

Use circuit breakers for external APIs

If an external API is down, stop hammering it. Give it time to recover.

Enable loop detection for autonomous agents

Agents that run without human oversight need loop detection. They will get stuck.

Be specific with tool access

Don’t give all agents access to all tools. Principle of least privilege.