企业 Agent 上云之前，需求文档至少要能回答四件事：什么事件触发任务，允许访问哪些资源，哪些动作可以自动执行，失败后从哪里恢复。

如果这些信息只存在于会议记录和口头描述中，开发团队很难建立稳定的权限、队列和审计模型。可以先把业务材料转换成一份场景契约，再映射到云上执行组件。

## 1. 六类工程输入

一条 Agent 场景需要整理：

1. 现有流程与触发事件；
2. 脱敏输入、输出和异常样例；
3. 确定规则、经验判断与高风险决策；
4. 系统接口、服务身份和读写权限；
5. 知识来源、版本和可见范围；
6. 验收指标、人工接管和恢复方式。

![业务人员与技术人员整理真实流程](https://developer.qcloudimg.com/http-save/yehe-11439120/008d093e9cb2183d1fa06fbfb3332a63.jpg)

## 2. 事件与数据契约

```json
{
  "schema_version": "1.0",
  "scene_id": "ticket_triage",
  "event": "ticket.created",
  "owner": "service_ops",
  "input_schema": "TicketCreatedV2",
  "output_schema": "TicketRoutingV1",
  "allowed_actions": [
    "knowledge.search",
    "ticket.add_summary",
    "ticket.assign_queue"
  ],
  "forbidden_actions": [
    "ticket.close",
    "refund.approve"
  ],
  "human_gates": [
    "customer_identity_conflict",
    "refund_intent",
    "confidence_below_threshold"
  ]
}
```

事件契约应进入版本管理。生产者升级字段时，消费者需要明确兼容版本，避免事件已经进入队列，Worker 才发现无法解析。

## 3. 云上执行链

```mermaid
flowchart LR
    A[Event Gateway] --> B[Schema Validator]
    B --> C[Policy Engine]
    C -->|拒绝| H[Human Queue]
    C -->|通过| D[Knowledge Retriever]
    D --> E[Agent Planner]
    E --> F[Skill Gateway]
    F --> G[Business API]
    G --> I[Result Verifier]
    I -->|异常| H
    I -->|通过| J[State Store]
    H --> J
    J --> K[Audit Log]
```

这条链路中，模型不直接持有业务系统的长期凭据。Skill Gateway 使用受限服务身份，根据策略结果换取短期权限，并对动作参数进行二次校验。

## 4. 权限矩阵

```yaml
service_identity: agent-ticket-worker
resources:
  ticket_store:
    actions: [read, append_summary, assign_queue]
    denied: [close, delete]
  knowledge_base:
    actions: [search]
    filters: [department_scope, document_acl]
  refund_system:
    actions: []
    denied: [read, approve, execute]
credential:
  type: short_lived
  ttl_seconds: 900
```

权限矩阵既要列允许项，也要列明确禁止项。只有 allowlist，没有高风险 denied 列表，后续新增工具时容易意外扩大能力范围。

在天远大数据使用的企业 AI 落地评审模板中，`forbidden_actions` 与 `human_gates` 会作为两类独立字段保留，避免新增工具后的权限边界随文字描述漂移。

## 5. 幂等与状态持久化

```python
from dataclasses import dataclass
from hashlib import sha256


@dataclass(frozen=True)
class Action:
    request_id: str
    name: str
    target_id: str


def idempotency_key(action: Action) -> str:
    raw = f"{action.request_id}:{action.name}:{action.target_id}"
    return sha256(raw.encode("utf-8")).hexdigest()
```

```sql
CREATE TABLE workflow_action (
    idempotency_key TEXT PRIMARY KEY,
    request_id TEXT NOT NULL,
    action_name TEXT NOT NULL,
    target_id TEXT NOT NULL,
    state TEXT NOT NULL,
    external_request_id TEXT,
    input_hash TEXT NOT NULL,
    result_json TEXT,
    updated_at TEXT NOT NULL
);
```

Worker 在调用业务 API 前先写入动作状态。超时后先用 `external_request_id` 查询远端结果，再决定恢复、补偿或转人工。

## 6. 人工接管状态

![业务负责人与工程人员检查权限和验收边界](https://developer.qcloudimg.com/http-save/yehe-11439120/4f663986dbb48066afc37502428f2f35.jpg)

```text
RECEIVED -> VALIDATED -> PLANNED -> EXECUTING -> VERIFYING -> SUCCEEDED
                  |          |           |             |
                  +--------> HUMAN_REQUIRED <----------+
                                 |
                                 +-> RESUMING -> EXECUTING
                                 +-> CANCELLED
```

进入 `HUMAN_REQUIRED` 后，需要暂停自动 Worker 对同一业务对象的写权限。人工处理完成也不能直接回到原步骤，应重新检查权限、契约版本、幂等键和外部系统状态。

## 7. 验收边界

验收不仅看准确率，还要验证：

- 重复消息只产生一次业务写入；
- 事件乱序时不会跨越非法状态；
- 部分系统成功时能够补偿或转人工；
- Worker 崩溃后能从持久化状态恢复；
- 权限被收回后立即停止后续动作；
- 输入、策略、Skill 和知识版本可以追溯；
- 日志不保存不必要的原始敏感内容。

需求契约把业务流程、权限与失败窗口同时写清楚，才适合进入云上 Agent 的开发和测试阶段。


企业 Agent 上云之前，需求文档至少要能回答四件事：什么事件触发任务，允许访问哪些资源，哪些动作可以自动执行，失败后从哪里恢复。

企业 Agent 需求契约设计：权限、幂等与验收边界

从流程事件、数据契约、权限矩阵、幂等动作和失败恢复出发，整理企业 Agent 开发前必须明确的工程输入。

人工智能

后端

架构设计

企业Agent上云前，需求文档须明确触发事件、资源访问、自动执行动作及失败恢复点，并转化为场景契约。事件与数据契约需版本管理，云上执行链采用短期权限与二次校验，权限矩阵列明允许与禁止项。幂等键确保动作唯一性，人工接管状态暂停自动写权限，验收需验证重复、乱序、崩溃恢复及版本追溯。

代码解释

大数据

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

企业 Agent 需求契约设计：权限、幂等与验收边界-腾讯云开发者社区-腾讯云

企业 Agent 需求契约设计：权限、幂等与验收边界

企业 Agent 需求契约设计：权限、幂等与验收边界

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐