Agent Runtime · 实验事务与决策引擎

# 核心能力

# 1. Experiment 管理

创建 immutable-context Experiment，固定 goal/plan/capability/policy/budget。每个 Experiment 有独立的 branch lineage，所有 Candidate 的修改都发生在这个 immutable context 的派生快照上。Experiment 一旦创建，其 context 不可变——保证了实验的可复现性和审计完整性。

# 2. Candidate 生命周期

proposal 去重 → 筛选 → 分支 → 执行 → 升级 fidelity → 验证 → 选择 → 终止。每个 Candidate 经历完整的状态流转，Runtime 保证状态转换的原子性：从 PROPOSED 到 SELECTED 或 REJECTED 的每一步都有 durable 记录。

# 3. 预算控制

reserve/debit/refund 多维预算账本——时间、步数、资源三维度独立配额。禁止通过 retry 绕过配额：每次 debit 都有唯一 nonce，重复提交被幂等拒绝。预算耗尽时 Experiment 进入 BUDGET_EXHAUSTED 终态。

# 4. 安全提交

只通过 iDB DesignStatePort.commit 对 exact candidate head 发起 CAS（Compare-And-Swap）。如果 head 在 Agent 执行期间已被其他 Candidate 修改，CAS 失败并返回冲突信息——Agent 必须 rebase 后重试。

# 5. Saga 长事务

每步有 durable intent、终态、补偿和 quarantine 机制。如果 Saga 的某一步失败，已执行的步骤按逆序补偿回滚。quarantine 机制将异常 Candidate 隔离到独立域，不影响主 Experiment 的其他分支。

# Agent 调用方式

Agent Runtime 提供三种等价的调用协议——Python SDK 用于 Agent 进程内调用，MCP 用于远程工具服务，Tcl 用于命令行实验管理。

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

# 输入/输出契约

ExperimentRequest

ExperimentResult

CandidateState 枚举

class CandidateState(Enum):
    PROPOSED   = "proposed"     # Agent 提交 proposal，待去重与筛选
    VALIDATED  = "validated"    # 通过 policy 与 capability 校验
    EXECUTING  = "executing"    # 正在 EDA 工具上执行
    EVALUATED  = "evaluated"    # 执行完毕，待评估
    SELECTED   = "selected"     # 被选中为最优解
    REJECTED   = "rejected"     # 评估未通过或被淘汰
    TIMED_OUT  = "timed_out"    # 超过时间/步数预算

# 相关资源