重新思考 AI 代理的 API 设计：从数据管道到智能界面

Source: Dev.to

问题：API 为人类设计，而非为会思考的机器设计

你的 API 是为另一个时代而设计的。它们是为：

• 开发者编写 if 语句
• React 组件获取数据
• 仪表盘展示记录

今天的自主 AI 代理不仅仅是获取数据——它们需要理解、推理并作出决定。向代理提供原始数据库记录和 HTTP 状态码，迫使它们去完成本该由你的 API 已经完成的工作。

**残酷真相：**如果你的 API 只暴露数据，你就在给智能喂噪声。

从传统 API 向面向代理的 API 设计的转变，并不是增加更多端点，而是从根本上重新思考你的 API 应该提供什么。

传统 API vs. 面向代理的 API

示例：维护记录

传统 API 响应

{
  "equipment_id": "CNC-001",
  "last_maintenance": "2024-11-01",
  "maintenance_interval_days": 30,
  "maintenance_type": "preventive"
}

代理现在必须：

1. 计算是否逾期（日期运算）
2. 评估风险等级（业务逻辑）
3. 确定优先级（领域知识）
4. 生成推荐（推理）

面向代理的 API 响应

{
  "equipment_id": "CNC-001",
  "last_maintenance": "2024-11-01",
  "maintenance_interval_days": 30,
  "maintenance_type": "preventive",

  // 🔥 语义增强
  "status": "overdue",
  "overdue_by_days": 8,
  "risk_level": "high",
  "priority": 1,
  "next_due_date": "2024-12-01",
  "recommendation": "Schedule immediately - approaching critical threshold",
  "impact_if_delayed": "Estimated 4‑hour production loss, $12,000 cost"
}

现在代理可以直接行动，而无需自行计算。

差的 vs. 好的 API 设计

❌ 差：碎片化微服务

GET /users/{id}
GET /accounts/{id}
GET /transactions/{id}
GET /credit_scores/{id}
GET /eligibility_rules

代理必须编排所有这些调用。

✅ 好：基于意图的 API

GET /customer_loan_eligibility/{id}

响应

{
  "eligible": true,
  "confidence": 0.94,
  "pre_approved_amount": 50000,
  "rationale": "Strong credit history, stable income, low debt ratio",
  "next_steps": ["Submit income verification", "Review terms"]
}

一次调用取代了五次，提供了明确的意图，而不是零散的逻辑。

提供上下文语义

没有上下文

{
  "risk_score": 67,
  "incidents_last_90_days": 3
}

代理必须回答的问题：

• 67 是高还是低？
• 3 起事故值得关注吗？
• 接下来应该怎么做？

有上下文

{
  "risk_score": 67,
  "risk_category": "moderate",
  "percentile": "82nd",               // 比 82 % 的同行更差
  "incidents_last_90_days": 3,
  "trend": "increasing",             // 之前每月 1 起，现在每周 1 起
  "comparison": "2x industry average",
  "interpretation": "Risk level elevated due to incident frequency increase",
  "suggested_actions": [
    "Implement additional safety protocols",
    "Schedule equipment inspection",
    "Review operator training records"
  ]
}

现在代理明白了 数字代表什么 以及 为什么重要。

一致性以实现可靠推理

❌ 不一致（代理噩梦）

• Endpoint A 返回 {"created_at": "2024-11-01"}
• Endpoint B 返回 {"createdDate": "2024-11-01T00:00:00Z"}
• Endpoint C 返回 {"timestamp": 1698796800}

✅ 一致（代理友好）

• 所有时间戳：ISO 8601 格式
• 所有 ID：UUID v4
• 所有货币：ISO 4217 代码
• 所有状态字段：Enum 并定义取值

当代理能够信任你的合约时，它们就能大规模推理。

微服务 vs. 面向代理的架构

传统微服务流程（8 次 API 调用）

1. GET /customer/{id}/profile
2. GET /customer/{id}/membership_status
3. GET /customer/{id}/order_history
4. GET /orders/{order_id}/items
5. GET /inventory/availability
6. GET /shipping/zones/{zip}
7. GET /shipping/rates
8. 代理执行复杂编排

问题

• 8 次网络往返 → 延迟
• 8 个潜在故障点 → 可靠性风险
• 业务逻辑在代理代码中重复 → 可维护性问题
• 代理必须了解完整的服务拓扑 → 紧耦合

面向代理的架构（1 次 API 调用）

GET /shipping/eligibility/{order_id}

响应

{
  "expedited_eligible": true,
  "confidence": 0.97,
  "reason": "Premium member + in‑stock inventory + metro area",
  "estimated_delivery": "2024-12-11",
  "cost": 12.99,
  "alternatives": [
    {
      "type": "standard",
      "estimated_delivery": "2024-12-14",
      "cost": 5.99
    }
  ]
}

微服务仍然在内部提供可扩展性，但外部 API 层应将这些复杂性隐藏在面向目标的端点后面。

将 API 转变为面向代理的方式

方案 1 – 语义增强（确定性逻辑）

def enrich_maintenance_record(record):
    # Calculate semantic fields
    days_overdue = (today - record['last_done']).days - record['interval']

    # Apply business rules
    if days_overdue > 14:
        risk = "critical"
        priority = 1
        recommendation = "URGENT: Schedule immediately"
    elif days_overdue > 7:
        risk = "high"
        priority = 2
        recommendation = "Schedule within 48 hours"
    elif days_overdue > 0:
        risk = "moderate"
        priority = 3
        recommendation = "Schedule this week"
    else:
        risk = "low"
        priority = 4
        recommendation = f"Due in {abs(days_overdue)} days"

    return {
        **record,
        "status": "overdue" if days_overdue > 0 else "current",
        "days_overdue": max(0, days_overdue),
        "risk_level": risk,
        "priority": priority,
        "recommendation": recommendation
    }

优势

• ⚡ 快速（50‑100 ms）
• 💰 免费（无 LLM 成本）
• 🎯 可靠（确定性输出）
• 🔍 易调试（易于追踪）

适用场景

• 状态计算
• 风险评估
• 优先级打分
• 日期/时间运算
• 聚合与摘要
• 基于规则的推荐

方案 2 – 与 LLM 混合（选择性使用）

async def create_maintenance_plan_with_insights(equipment_id):
    # ✅ Deterministic: Get and calculate data
    equipment = get_equipment_details(equipment_id)
    history = get_maintenance_history(equipment_id)

    suggested_interval = calculate_optimal_interval(history)
    base_instructions = get_template_instructions(equipment['type'])

    # 🤖 LLM: Generate contextual insights
    if len(history) > 5:  # Only if we have data to learn from
        context = {
            "equipment_type": equipment['type'],
            "recent_failures": history[-5:],
            "pattern": analyze_failure_pattern(history)
        }

        insights = await generate_llm_insights(context)
    else:
        insights = None

    return {
        "suggested_interval": suggested_interval,   # ✅ Calculated
        "work_instructions": base_instructions,    # ✅ Template
        "contextual_recommendations": insights     # 🤖 LLM‑generated
    }

LLM 使用场景（20 %）

• 基于历史模式的上下文推荐
• 对复杂情境的自然语言解释
• 从相似案例中学习
• 根据用户行为自适应的建议

性能、成本与可靠性对比

**建议：**先使用纯确定性逻辑。仅在确定性规则无法捕获细微差别时，才加入选择性的 LLM 调用。

为面向代理的 AI 构建 API 生态系统

┌───────────────────────────────────────┐
│           AI AGENT LAYER                │
│  (ChatGPT, Claude, Custom Agents)      │
└───────────────────────────────────────┘
          │
          ▼
┌───────────────────────────────────────┐
│          Agent‑Ready API GATEWAY       │
│  – 目标导向端点                         │
│  – 语义增强                            │
│  – 合约一致性                          │
└───────────────────────────────────────┘
          │
          ▼
┌───────────────────────────────────────┐
│        Underlying Microservices         │
│  – 可扩展、独立的服务                   │
│  – 内部数据存储                         │
└───────────────────────────────────────┘

向代理层暴露轻量、意图驱动的表面，同时在内部保持微服务网格。这种设计为代理提供了所需的上下文、一致性和可靠性，使其能够有效推理并执行操作。