多 Agent 接口契约：状态、错误与版本怎么定

多 Agent 内部可以有不确定输出，对外接口却不能靠调用方猜。裸字符串或随意 JSON 一旦穿过网关，前端状态、重试和错误提示都会长出自己的分支。

接口先固定顶层结构、运行状态和错误语义，再用 Pydantic、Protobuf 或项目现有 Schema 工具校验。强类型能减少歧义，但不能承诺“永不返工”。

1. 三项契约分别约束什么

第一，统一顶层响应。status、trace_id、data 和 error 只是示例，是否采用 envelope 要与现有 API 规范一致。

第二要点：显式定义有限状态机（FSM）状态码。将 Agent 的运行状态枚举化（如 RUNNING、AWAITING_INPUT、COMPLETED、FAILED）。前端打字机组件只需根据状态码切换 UI，无需猜测 Prompt 文本含义。

第三，输入输出都做 Schema 校验。校验能阻止格式和范围错误，语义正确性仍需业务规则与测试覆盖。

2. Python 接口契约示意

以下展示基于 Python Pydantic 实现的标准 Agent 网关接口定义脚手架：

import logging
from typing import Dict, Any, Optional, Generic, TypeVar
from pydantic import BaseModel, Field

logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(message)s")

T = TypeVar('T')

class AgentAPIResponse(BaseModel, Generic[T]):
    status: str = Field(..., description="状态: RUNNING | COMPLETED | FAILED")
    trace_id: str = Field(..., description="分布式追踪 Trace ID")
    data: Optional[T] = Field(default=None, description="业务成功载荷")
    error_message: Optional[str] = Field(default=None, description="错误描述")

class DiagnosisDataPayload(BaseModel):
    summary: str = Field(..., description="分析总结")
    action_required: bool = Field(..., description="是否需要人工介入")

class AgentInterfaceGateway:
    def format_success_response(self, trace_id: str, summary: str, action_required: bool) -> Dict[str, Any]:
        payload = DiagnosisDataPayload(summary=summary, action_required=action_required)
        response = AgentAPIResponse[DiagnosisDataPayload](
            status="COMPLETED",
            trace_id=trace_id,
            data=payload
        )
        logging.info(f"[接口网关] 成功封装标准 API 响应, TraceID: {trace_id}")
        return response.model_dump()

if __name__ == "__main__":
    gateway = AgentInterfaceGateway()
    res = gateway.format_success_response("trace_fmt_9901", "节点内存正常", False)
    print(f"标准不返工接口输出:\n{res}")

3. 接口设计的度量指标

• agent_api_contract_validation_errors_total: 契约校验失败数。
• agent_api_refactoring_rate: 接口修改返工频率。

4. 版本演进比一次定稿更重要

第一，对跨进程、跨团队边界的数据显式定义 Schema；进程内部是否使用同一套模型，按维护成本选择。

第二，统一顶层包装结构（Standard Envelope Required）。固定返回 status, trace_id 与 data。

接口定稿前应把成功、可重试失败、不可重试失败和异步受理分别写成样例。调用方根据稳定的错误语义决定是否继续，而不是解析模型返回的自然语言。字段增加可保持向后兼容，字段删除或语义变化则要走版本升级与回归验证；这比临时在客户端补判断更可靠。