03 - 方案选型对比

3.1 ACI vs 传统 API 封装对比矩阵

3.1.1 全维度对比表

3.1.2 适用场景对比

flowchart TD
    A[应用场景] --> B{用户是谁？}
    
    B -->|人类用户<br/>通过界面| C[传统 API]
    B -->|AI Agent| D[ACI]
    
    C --> C1[Web App]
    C --> C2[Mobile App]
    C --> C3[内部系统]
    
    D --> D1[智能助手]
    D --> D2[自动化 Agent]
    D --> D3[Multi-Agent 系统]
    
    E{交互复杂度？} -->|简单 CRUD| C
    E -->|复杂推理链| D

决策树结论：

• 使用传统 API：确定性场景、高频调用、人类直接调用
• 使用 ACI：模糊需求、多步推理、Agent 自主决策

3.1.3 技术栈对比

3.2 设计范式差异：命令式 vs 声明式

3.2.1 命令式 API 设计

传统 API 采用命令式（Imperative）设计：调用方精确控制每一步。

示例：创建订单

# 传统 REST API 调用
user = api.get_user_by_name("张三")
product = api.get_product_by_name("拿铁")
order = api.create_order(
    user_id=user.id,
    product_id=product.id,
    quantity=1,
    size="large"
)
payment = api.process_payment(order.id, method="alipay")

特点：

• 调用方编排流程
• 每一步状态显式管理
• 错误在每个步骤处理

3.2.2 声明式 ACI 设计

ACI 采用声明式（Declarative）设计：Agent 表达目标，ACI 处理执行细节。

示例：同样场景

Agent -> ACI: "帮张三订一杯大杯拿铁，用支付宝支付"

ACI 内部处理：
1. 识别用户 "张三"
2. 识别产品 "大杯拿铁"
3. 创建订单
4. 发起支付
5. 返回结果："订单已创建，支付成功，订单号 #12345"

特点：

• Agent 描述目标
• ACI 自动编排工具链
• 错误在语义层统一处理

3.2.3 范式对比分析

混合模式：实际应用中，ACI 内部可能调用命令式 API 完成具体动作，形成”声明式外壳 + 命令式内核”的架构。

3.3 工具描述语言对比（OpenAPI vs ACI Schema）

3.3.1 OpenAPI 的局限性

OpenAPI 是为人类开发者设计的接口文档，对 Agent 不够友好：

问题 1：缺乏语义描述

# OpenAPI 示例
parameters:
  - name: q
    type: string
    description: "查询字符串"

Agent 看到：需要一个字符串参数 q 但不知道：“q” 应该包含什么？格式要求？

问题 2：无示例引导

OpenAPI 3.0 虽支持 example，但：

• 非强制字段
• 通常只有一个示例
• 缺乏边界情况说明

问题 3：错误码难以理解

responses:
  400:
    description: "Bad Request"

Agent 无法得知：

• 什么情况下返回 400？
• 如何修复？
• 是否需要重试？

3.3.2 ACI Schema 的改进

MCP 定义的 ACI Schema 针对 Agent 优化：

{
  "name": "search_products",
  "description": "搜索产品目录。支持自然语言查询，如'便宜的红色T恤'或'适合跑步的鞋子'。",
  "examples": [
    {
      "description": "基础搜索",
      "input": {
        "query": "无线耳机"
      },
      "output": {
        "products": ["AirPods Pro", "Sony WF-1000XM5"]
      }
    },
    {
      "description": "带过滤条件",
      "input": {
        "query": "200元以下的蓝牙耳机"
      },
      "output": {
        "products": ["Redmi Buds 5", "QCY T13"]
      }
    },
    {
      "description": "歧义处理",
      "input": {
        "query": "苹果"  // 可能指水果或品牌
      },
      "behavior": "询问用户是指 Apple 品牌还是水果类别"
    }
  ],
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "搜索查询，支持自然语言描述需求"
      }
    },
    "required": ["query"]
  },
  "errorHandling": {
    "no_results": "返回友好提示：'未找到匹配产品，建议尝试其他关键词'",
    "ambiguous": "询问用户澄清意图",
    "timeout": "提示用户稍后重试"
  }
}

关键改进：

• 自然语言描述：说明工具用途和使用场景
• 丰富示例：覆盖典型和边界情况
• 行为定义：明确歧义处理方式
• 错误引导：提供可操作建议

3.3.3 描述语言对比矩阵

3.4 调用流程与错误处理差异

3.4.1 调用流程对比

传统 API 调用流程：

sequenceDiagram
    participant C as Client
    participant A as API
    participant S as Service
    
    C->>A: 1. 构建请求
    Note over C: 精确参数填充
    
    A->>A: 2. 参数校验
    Note over A: 类型/范围检查
    
    alt 校验失败
        A-->>C: 400 Bad Request
    else 校验通过
        A->>S: 3. 执行业务逻辑
        S-->>A: 结果
        A-->>C: 4. 返回响应
    end

ACI 调用流程：

sequenceDiagram
    participant A as Agent
    participant AC as ACI
    participant T as Tool
    
    A->>AC: 1. 表达意图（可能模糊）
    Note over A: 自然语言输入
    
    AC->>AC: 2. 意图解析
    Note over AC: LLM 语义理解
    
    alt 意图不明
        AC-->>A: 请求澄清
        A->>AC: 补充信息
    else 参数缺失
        AC-->>A: 询问缺失参数
        A->>AC: 提供参数
    else 意图明确
        AC->>T: 3. 调用工具
        T-->>AC: 结果
        AC->>AC: 4. 格式化响应
        AC-->>A: 自然语言结果
    end

3.4.2 错误处理模式对比

传统 API 错误码：

ACI 错误处理：

{
  "error": {
    "type": "clarification_needed",
    "message": "您想查询北京今天还是明天的天气？",
    "options": ["今天", "明天"],
    "suggested_action": "请指定日期"
  }
}

ACI 错误类型：

3.4.3 用户体验对比

场景：用户说”帮我订个外卖”（缺少关键信息）

传统 API 方案：

API Response: 400 Bad Request
{"error": "Missing required fields: restaurant, items, address"}

结果：Agent 无法优雅处理，用户体验差

ACI 方案：

ACI Response: 
"好的！我需要一些信息来帮您下单：
1. 您想从哪家餐厅订？
2. 您想吃什么？
3. 送到哪里？"

结果：对话式补充，体验自然

3.5 性能与成本对比

3.5.1 延迟对比

数据点：根据 LangSmith 2024 报告，ACI 平均延迟 1.2s，传统 API 平均 150ms，但 ACI 任务完成率高出 23%。

3.5.2 成本对比

总拥有成本（TCO）：对于复杂任务，ACI 虽然单次调用成本高，但因成功率提升和人工介入减少，整体 TCO 可能更低。

3.6 本章小结

通过系统性对比，我们得出以下关键结论：

1. ACI 不是替代传统 API，而是补充：两者各有适用场景
2. 设计范式根本不同：命令式 vs 声明式
3. 描述语言需要演进：从 OpenAPI 的精确描述到 ACI 的语义描述
4. 错误处理更智能：从机器错误码到对话式引导
5. 成本结构不同：高单次成本但低人工介入成本

下一章将深入分析现有 ACI 协议工具的实现，包括 MCP、Claude Code、LangChain Tools 等。

本章引用：

1. OpenAPI Specification 3.0. https://swagger.io/specification/
2. MCP Specification. https://modelcontextprotocol.io
3. LangSmith Performance Report 2024. https://langchain.com/langsmith
4. “The Rise of Agentic AI.” Andreessen Horowitz. 2024.