Agent Harness Engineering 七层架构：把大模型变成可靠 Agent 的工程方法

Model + Harness = Agent

sandbox:
  filesystem:
    mode: workspace-only
    readonly_paths:
      - /etc
      - /usr
  network:
    default: deny
    allowlist:
      - api.github.com
  process:
    timeout_seconds: 120
    max_memory_mb: 2048
  secrets:
    expose:
      - GITHUB_TOKEN_READONLY

{
  "name": "read_file",
  "description": "Read a text file from the workspace.",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Relative file path under the workspace."
      }
    },
    "required": ["path"]
  }
}

orchestration:
  max_steps: 30
  max_tool_calls: 80
  max_cost_usd: 3.00
  stop_when:
    - tests_passed
    - user_goal_satisfied
  retry:
    max_attempts_per_tool: 2
    backoff: exponential

{
  "trace_id": "run_20260607_001",
  "step": 12,
  "event_type": "tool_call",
  "tool": "run_tests",
  "input_summary": "pytest tests/test_parser.py",
  "status": "failed",
  "error_code": "TEST_FAILURE",
  "latency_ms": 8421,
  "tokens_in": 1832,
  "tokens_out": 214,
  "cost_usd": 0.018,
  "policy_decision": "allowed"
}

governance:
  filesystem:
    default: deny
    allow:
      - path: "./src/**"
        actions: ["read", "write"]
      - path: "./tests/**"
        actions: ["read", "write", "execute"]
    deny:
      - path: "./.env"
        actions: ["read", "write"]
  network:
    default: deny
    allow_domains:
      - "api.github.com"
      - "pypi.org"
  commands:
    require_approval:
      - "rm -rf *"
      - "git push *"
      - "curl * | sh"
  secrets:
    no_model_echo: true
  audit:
    record_tool_inputs: true
    record_tool_outputs: "summary"

task:
  type: coding_agent
  goal: "Fix a bug and submit a patch"
  allowed_repositories:
    - "workspace/project"
  success_criteria:
    - "unit_tests_pass"
    - "no_security_policy_violation"
  out_of_scope:
    - "production_deployment"
    - "database_migration"

execution:
  backend: docker
  image: "python:3.12"
  reset_strategy: snapshot
  timeout_seconds: 600
  resource_limits:
    cpu: 2
    memory_mb: 4096

tools:
  registry: mcp
  allowlist:
    - read_file
    - write_file
    - search_code
    - run_tests
    - git_diff
  selection:
    max_visible_tools: 8
    hide_unrelated_tools: true

context:
  max_tokens: 64000
  budget:
    system_instruction: 4000
    task_state: 6000
    retrieved_files: 30000
    tool_observations: 12000
    scratchpad_summary: 8000
  memory:
    session_summary: true
    long_term_write_requires_verification: true

lifecycle:
  pattern: react
  max_steps: 40
  max_retries_per_step: 2
  stop_conditions:
    - "success_criteria_met"
    - "budget_exceeded"
    - "policy_blocked"

observability:
  tracing: true
  metrics:
    - tokens
    - latency
    - tool_errors
    - cost
    - policy_blocks
  export:
    - openTelemetry
    - langfuse

evaluation:
  benchmark: custom_bugfix_suite
  capture:
    - final_result
    - full_trace
    - environment_diff
    - test_output
  failure_taxonomy:
    - planning
    - tool_use
    - context
    - environment
    - safety
  regression:
    add_failed_cases: true

governance:
  approval_required:
    - "network_write"
    - "git_push"
    - "send_email"
  audit_log:
    enabled: true
    retention_days: 180
  policy_on_violation: "stop_and_report"

def run_agent(task):
    sandbox = sandbox_manager.reset(task.environment)
    trace = tracer.start(task.id)

    state = task_state.init(task)
    memory.load_session(task.session_id)

    for step in range(task.max_steps):
        context = context_builder.build(
            task=task,
            state=state,
            memory=memory,
            budget=task.context_budget,
        )

        action = model.next_action(context)

        policy_decision = governance.check_action(action, state)
        trace.record_action(action, policy_decision)

        if policy_decision.requires_approval:
            approved = human_review.request(action)
            if not approved:
                state.add_observation("Action rejected by human reviewer.")
                continue

        if policy_decision.blocked:
            return finish("blocked_by_policy", trace)

        result = tool_runtime.execute(action, sandbox=sandbox)
        trace.record_tool_result(result)

        state.update(result)
        memory.maybe_write(state.verified_facts())

        if evaluator.success(task, state, sandbox):
            return finish("success", trace)

        if budget.exceeded(trace):
            return finish("budget_exceeded", trace)

    return finish("max_steps_reached", trace)

E：让动作安全执行
T：让能力可被可靠调用
C：让模型看到正确上下文
L：让任务持续推进
O：让过程可观测
V：让结果可验证
G：让行为受约束、可审计