ActShield 接入指南

返回工作空间
# ActShield v0.9：接入客户自己的 Agent

本版从固定退款流程转为通用 Agent 风险管理基础版本。客户保留自己的模型、工具和编排。注册工具及业务策略后，在接入的输入、上下文、输出与执行节点进行评估。

当前可交付范围：Agent 配置风险检查、通用事件采集、参数结构校验、权限检查、业务字段约束、有限内容模式、调用次数/上报费用控制、可选模型语义评估、独立审批、单次执行许可、执行端回执和风险事件处理。

## 1. 网页接入流程

1. 管理员登录后通过“成员管理”生成一次性邀请。试用成员和审批人使用各自账号。管理员不是审批人，不能自行批准自己的业务动作。
2. 打开“Agent 管理 → 接入 Agent”，填写名称、实际模型、框架和业务目的。
3. 登记实际工具：工具名称、用途、副作用类型、逐项权限、参数结构。工具无需由 ActShield 后端预先编码。
4. 设置允许权限和约束。先使用观察模式验证上报，再用独立执行端落实执行控制。
5. 生成 Agent 凭证，交给现有 Agent。凭证仅显示一次。它不能消费执行许可、上报执行回执或审批。
6. 由管理员另行生成执行端凭证，只交给持有业务凭证的执行服务。Agent 不应接触此凭证。
7. 在“运行与风险”查看事件、评估依据、审批和回执；审批人登录自己的账号批准待审批动作。

可以只使用 HTTP API，不必采用 Python SDK。SDK 是薄封装，不依赖模型供应商或 Agent 框架。

## 2. 信任边界与实际覆盖

- 观察接入：记录已提交的事件，给出建议，不签发许可，不能声称阻止了外部执行。
- Agent 内 SDK：合作式接入。若 Agent 能直接访问业务凭证或业务接口，仍可绕过包装函数。
- 独立执行端：在真正执行前，使用执行端专用凭证向平台消费许可，校验工具、参数、运行和事件身份。业务凭证应只存在于该执行端，并通过网络和业务系统权限限制其他调用路径。
- 平台并不会远程证明客户已完成上述隔离。界面显示“有事件上报”“有执行端回执”，不显示“所有路径已保护”。

当前是一个共享试用工作空间，不是企业多租户产品。普通成员仅管理自己的 Agent；管理员和审批人可看到工作空间内的 Agent 和事件。旧退款订单仍为共享沙盒。

## 3. API 合同

浏览器/工作空间身份（Cookie 或原有管理员/审批人服务器凭证）：

- POST /platform/agents：创建登记，参数结构见 examples/agent-registration.json。
- GET /platform/agents：可见 Agent、配置风险、接入状态和执行端回执计数。
- PUT /platform/agents/{id}：更新配置；必须带 If-Match: 当前 revision，防止覆盖他人的修改。更新后旧许可失效。
- PATCH /platform/agents/{id}/state：{"paused":true}；暂停/恢复均使旧许可失效，不能撤回已经开始的业务动作。
- POST /platform/agents/{id}/keys/agent：生成或轮换 Agent 凭证。
- POST /platform/agents/{id}/keys/executor：仅管理员生成或轮换执行端凭证。
- DELETE 同一 keys 路径：撤销指定凭证。
- POST /platform/agents/{id}/preview：仅确定性试算，不保存事件、不调用模型、不签发许可。
- GET /platform/decisions：最近 100 条，可按 agent_id 筛选，最多 200。
- POST /platform/decisions/{id}/approve：独立审批人批准本次动作。
- PATCH /platform/decisions/{id}/incident：标记 open/resolved/false_positive，必须填写 note。不会修改授权。
- GET /platform/decisions/{id}/evidence：导出事件与审批/执行记录及一致性校验和。

Agent 凭证（Authorization: Bearer as_agent_...）：

POST /v1/runtime/events

    {
      "event_id":"customer-event-0001",
      "run_id":"customer-run-001",
      "kind":"tool_call",
      "tool":"document.archive",
      "arguments":{"document_id":"DOC-1","folder":"finance"},
      "purpose":"归档用户明确指定的文档"
    }

kind 支持 input/context/output/tool_call/usage。文本放在 content，费用尝试可放 reported_cost_usd。只有 tool_call 接受 tool 和 arguments。

使用同一 event_id 重试相同事件会返回同一决策，不会再次调用评估模型；同一 event_id 对应不同内容会返回 409。模型请求与数据库之间不提供跨进程事务，极端并发重复请求可能产生多次评估费用，但只持久化一条事件；调用尝试受服务器配额限制。

- GET /v1/runtime/decisions/{id}：查询本 Agent 的决策。
- POST /v1/runtime/decisions/{id}/permit：仅执行控制模式的 allowed/approved 工具动作可申请许可。有效期 5 分钟；重新申请会废止前一次尚未消费的许可。

执行端凭证（Authorization: Bearer as_exec_...）：

POST /v1/executor/consume

    {"permit":"许可原文","event_id":"customer-event-0001","run_id":"customer-run-001",
     "tool":"document.archive","arguments":{"document_id":"DOC-1","folder":"finance"}}

平台在事务内校验 Agent 暂停状态、当前配置和凭证版本、账号状态、审批人状态、参数哈希、许可有效期及运行中后续风险事件。许可只能成功消费一次。校验失败或平台不可用时，执行端不得调用业务函数。

POST /v1/executor/receipt

    {"decision_id":"dec_...","status":"succeeded","result_digest":"64位SHA256",
     "summary":"业务接口返回成功"}

status 支持 succeeded/failed/unknown。Agent 凭证无权上报回执。重复提交完全相同的回执可重放，不同内容返回 409。记录为执行端上报，不构成独立第三方证明。

许可消费成功以后，业务操作与回执上报之间仍可能断连或崩溃。系统不会把这种情况标记为成功，也不会自动再次调用业务函数。120 秒未收到回执显示 outcome_unknown，必须核对业务系统。平台保证的是每个许可最多成功消费一次，不能据此宣称任意业务操作 exactly-once。真实业务仍应使用自己的幂等键、事务或对账。

Agent、工具名、schema 或策略变更后需要新的事件重新评估。平台不会自动识别客户未上报的工具变更。运行编号和费用是客户上报值；换 run_id 绕开单运行限额需要在执行端/业务系统另设稳定身份及总额控制。

## 4. SDK 接入

sdk/actshield.py 仅使用 Python 标准库。把 Client 接入已有 Agent 的工具分发边界：

    from actshield import Client, ApprovalRequired, Blocked
    client = Client("https://app.actshield.cn", agent_token)
    # 先上报输入、检索内容和输出。需要执行控制时，不得忽略返回的风险建议。
    d = client.event(event_id="input-event-001",run_id=run_id,kind="input",content=user_input)
    client.require_safe_context(d)
    request = client.prepare(event_id=event_id,run_id=run_id,tool=tool_name,arguments=arguments)
    # 交给独立执行端，而不是在这里直接执行业务函数。

ApprovalRequired 异常中包含 decision。等待独立审批后，以原 event_id/run_id/tool/arguments 调用 client.resume(decision_id, ...) 获取许可。Blocked 时终止，不能换 event_id、换运行编号或拆分参数来绕过。

独立执行端使用 Executor：

    from actshield import Executor
    executor = Executor(platform_url, executor_token, {"my.actual.tool": business_callable})
    result = executor.invoke(request)

工具注册表位于客户执行端；控制平台不导入客户 Python 代码，也不接受任意执行 URL。

## 5. 三进程接入样例

examples/agent-registration.json 是通用登记示例。先在网页填写等价的工具定义与策略，或用工作空间身份 POST /platform/agents。它定义 document.archive，不需要修改治理后端。

在执行端自己的环境中配置 ACTSHIELD_URL 与 ACTSHIELD_EXECUTOR_TOKEN，然后运行：

    python3 examples/customer_executor.py

此脚本只监听 127.0.0.1:8300，拥有一个独立的 customer-ledger.db。它是本地接入验证样例，不是可直接公网暴露的企业连接器。部署到其他主机时必须实现调用方认证、TLS、网络隔离和业务权限校验。

另一个终端/Agent 环境只配置 ACTSHIELD_URL 与 ACTSHIELD_AGENT_TOKEN：

    python3 examples/external_agent.py --tool document.archive \
      --arguments '{"document_id":"DOC-1","folder":"finance"}' \
      --event-id external-event-0001 --run-id external-run-0001

首次将返回待审批决策。审批人登录网页批准后，保持参数不变，加 --resume dec_... 再运行。可以将 CLI 参数替换成客户真实模型生成的工具调用；模型和编排无需改成内置退款 Agent。

样例不调用模型、不消耗模型额度，用于验证接入及执行控制。自动化 tests/external_process.py 会启动三个独立进程，验证审批前无业务写入、审批后有独立账本记录、重复请求未重复执行。

## 6. 检测方式与边界

- 配置检查：仅检查登记的工具、权限、副作用和接入模式。不是源码/依赖/SBOM/主机扫描，也不是 Agent 的全面安全认证。
- schema：支持 type/object/properties/required/additionalProperties/items/enum/minimum/maximum/minLength/maxLength/minItems/maxItems/description 的有界子集。拒绝远程 $ref、正则和可执行表达式，深度最多 6。object 必须禁止额外字段。
- 权限：工具所需权限必须逐项在允许权限中，不隐式展开通配符。
- 业务约束：字段路径的上下限、枚举、前缀和 HTTPS 主机限制。缺字段或无法比较时拒绝。这不替代业务系统的实时资源归属、余额等校验。
- 内容模式：覆盖少量中英文指令覆盖、疑似凭证和破坏性命令模式。可以误报，也不能检测所有提示注入、编码/混淆攻击或数据泄漏。结构化敏感字段与部分凭证模式在记录中脱敏，不是完整 DLP。
- 行为：单运行调用次数、客户上报费用、每 Agent 事件频率。均不等同于供应商账单或不可伪造的运行身份。
- 语义评估：每 Agent 主动启用后，将登记信息、当前事件和同运行最近三个文本事件发送到管理员配置的模型。请求不带工具，不赋予执行权。仅接受 low/medium/high 及简短依据；高风险拒绝，中风险需审批；异常/超时/格式不合法需审批。模型的低风险意见不能覆盖规则拒绝。模型可能被误导，不是形式化安全证明。

共享模型调用默认每账号每天 30 次尝试、每分钟 5 次，聊天和语义评估共用，失败也计数；UTC 零点重置。服务器 .env 中 MODEL_DAILY_REQUEST_LIMIT / MODEL_MINUTE_REQUEST_LIMIT 可调整，随后重新创建控制服务。该限额是请求次数，不是费用承诺。

## 7. 设计参考

风险分类与信任边界参考以下公开一手资料，不代表通过认证或完整实现这些标准：
- OWASP Excessive Agency：https://genai.owasp.org/llmrisk/llm062025-excessive-agency/
- OWASP Securing Agentic Applications Guide：https://genai.owasp.org/resource/securing-agentic-applications-guide-1-0/
- MCP authorization security considerations：https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/basic/authorization.mdx

v0.9 的 HTTP 事件协议不是 MCP transport，不宣称已实现 MCP/OAuth 或所有 Agent 框架的自动接入。

配置修改会撤销该 Agent 的执行端凭证；管理员需审核新配置并重新签发，避免配置所有者在已有业务权限下自行弱化策略。已开始的业务操作仍需核对实际结果。