Agent Runtime · Experiment transactions & decision engine

# Core capabilities

# 1. Experiment management

Create immutable-context Experiments with fixed goal/plan/capability/policy/budget. Each Experiment has its own branch lineage; all Candidate changes occur on derived snapshots of that immutable context. Once created, an Experiment's context cannot change—ensuring reproducibility and audit integrity.

# 2. Candidate lifecycle

Proposal dedup → filter → branch → execute → upgrade fidelity → verify → select → terminate. Each Candidate flows through a full state machine; Runtime guarantees atomic transitions—every step from PROPOSED to SELECTED or REJECTED is durably recorded.

# 3. Budget control

Multi-dimensional budget ledger with reserve/debit/refund—time, steps, and resources each have independent quotas. Retries cannot bypass quotas: every debit carries a unique nonce; duplicate submissions are idempotently rejected. When budget is exhausted, the Experiment enters the BUDGET_EXHAUSTED terminal state.

# 4. Safe commit

Commits only via iDB DesignStatePort.commit with CAS (Compare-And-Swap) on the exact candidate head. If the head changed while the Agent was executing, CAS fails and returns conflict info—the Agent must rebase and retry.

# 5. Saga long transactions

Each step has durable intent, terminal state, compensation, and quarantine. If a Saga step fails, completed steps are compensated in reverse order. Quarantine isolates abnormal Candidates in a separate domain without affecting other branches of the main Experiment.

# Agent invocation

Agent Runtime exposes three equivalent invocation protocols—Python SDK for in-process Agent calls, MCP for remote tool services, and Tcl for CLI experiments.

from ieda.runtime import AgentRuntime

rt = AgentRuntime("http://localhost:9100")

# Step 1: Create Experiment with immutable context
exp = rt.create_experiment(
    goal_ref="reduce_congestion_v2",
    plan_ref="local_swap_plan_3",
    capability=["iPL.place", "iSTA.analyze"],
    budget={"time_s": 3600, "steps": 200},
)

# Step 2: Submit Candidate proposal
candidate = exp.submit(
    proposal={
        "action": "iPL.place",
        "params": {"region": "hotspot_A", "effort": "in-design"},
    },
    fidelity="F2",
)

# Step 3: Wait for execution & retrieve result
result = candidate.wait(timeout_s=600)
print(result.state)       # CandidateState.EVALUATED
print(result.evidence)    # {"hpwl_delta": -0.03, "congestion_improved": True}

// Create Experiment
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "runtime.create_experiment",
    "arguments": {
      "goal_ref": "reduce_congestion_v2",
      "plan_ref": "local_swap_plan_3",
      "budget": {"time_s": 3600, "steps": 200}
    }
  }
}

// Response: Experiment created
{
  "experiment_id": "exp_7f3a",
  "branch_lineage": "main/exp-042",
  "budget_ledger": {"time_remaining": 3600, "steps_remaining": 200}
}

# Create Experiment
agent_runtime start -name congestion_fix \
  -goal reduce_congestion_v2 \
  -plan local_swap_plan_3 \
  -budget_time 3600 -budget_steps 200

# Submit Candidate
agent_runtime submit -exp exp_7f3a \
  -action "iPL.place" \
  -region hotspot_A \
  -fidelity F2

# Query result
agent_runtime status -exp exp_7f3a

# Commit selected candidate to iDB
agent_runtime commit -exp exp_7f3a -candidate c42_a

# Input/output contract

ExperimentRequest

ExperimentResult

CandidateState enum

class CandidateState(Enum):
    PROPOSED   = "proposed"     # Agent submitted proposal; pending dedup and filtering
    VALIDATED  = "validated"    # Passed policy and capability validation
    EXECUTING  = "executing"    # Executing on EDA tools
    EVALUATED  = "evaluated"    # Execution complete; pending evaluation
    SELECTED   = "selected"     # Selected as best solution
    REJECTED   = "rejected"     # Failed evaluation or eliminated
    TIMED_OUT  = "timed_out"    # Exceeded time/step budget

# Related resources