张胜宇
e239eb778b
1) 客服 Agent 四份交付文档 + 构建脚手架：品牌由包装占位 XX科技 / 旧名 南方财富 统一为南方基金（热线 400-889-8899 / 官网 nffund.com），系统名改为「智能服务系统」； 同步追加 §0.4 修订记录行，工程记录行保留原占位字面以支撑硬编码扫描验收。 2) 开发文档：清理 28 份已作废/残留文档（14 份移出归档 + 14 份仓库副本）， 新增《文档规整方案与开发前待决事项-2026-09-17》。 3) 客服agent 四份交付文档首次纳入本分支。
59 lines
1.8 KiB
Python
59 lines
1.8 KiB
Python
from typing import Any
|
||
|
||
from pydantic import BaseModel, ConfigDict, Field
|
||
|
||
|
||
class AgentRunCreateRequest(BaseModel):
|
||
model_config = ConfigDict(extra="forbid")
|
||
|
||
agent_type: str
|
||
message: str = Field(min_length=1)
|
||
session_id: str
|
||
idempotency_key: str = Field(min_length=16, max_length=128)
|
||
|
||
|
||
class AgentRunAcceptedResponse(BaseModel):
|
||
run_id: str
|
||
trace_id: str
|
||
status: str
|
||
status_url: str
|
||
events_url: str
|
||
|
||
|
||
class AgentRunAcceptedEnvelope(BaseModel):
|
||
"""`POST /api/v1/agent-runs` 的 202 响应（文档 §3.3 + §6.2）。
|
||
|
||
文档 §6.2 明确给出的是 `{data:{run_id,trace_id,status,status_url,events_url}, meta:{trace_id}}`
|
||
信封，§3.3 又规定"业务接口不得增加其他顶层字段"。此前这里返回的是平铺对象，接入方按
|
||
文档取 `data.run_id` 会拿到空值——这是接入者第一步就会踩到的契约偏差，因此补齐信封。
|
||
|
||
`data` 内的字段名与语义与改动前完全一致，客户端只是多读一层 `data`；
|
||
`meta.trace_id` 是**本次请求**的 trace，`data.trace_id` 是运行自身的 trace（两者通常相同）。
|
||
"""
|
||
|
||
data: AgentRunAcceptedResponse
|
||
meta: dict[str, str]
|
||
|
||
|
||
class AgentRunStatusResponse(BaseModel):
|
||
run_id: str
|
||
trace_id: str
|
||
status: str
|
||
agent_type: str
|
||
session_id: str
|
||
result: dict[str, Any] | None = None
|
||
error_code: str | None = None
|
||
created_at: str
|
||
completed_at: str | None = None
|
||
|
||
|
||
class AgentRunStatusEnvelope(BaseModel):
|
||
"""`GET /api/v1/agent-runs/{run_id}` 的成功响应（文档 §3.3 + §6.3）。
|
||
|
||
单资源信封只多一层 `{data, meta}`：`data` 里的字段名与语义**与改动前完全一致**，
|
||
客户端除多读一层 `data` 外不需要任何适配。
|
||
"""
|
||
|
||
data: AgentRunStatusResponse
|
||
meta: dict[str, str]
|