在华为云上落地一个可观测的 AI Agent:工具编排、状态管理与部署实践
摘要
很多团队能把 Agent 的 Demo 跑起来,却很难让它稳定上线。真正卡住工程的,往往不是模型能力,而是工具编排、会话状态、失败重试与可观测性。本文以开源思路出发,给出一套可落地的 AI Agent 架构:四段循环、统一工具契约、结构化轨迹,以及在华为云上的无服务器部署映射,并附带可直接改造的 Python 示例代码。
一、Demo 能跑,为什么上线就崩
一个典型的 Agent Demo 通常长这样:把用户问题丢给大模型,模型返回一个函数调用,代码执行函数,再把结果塞回上下文,循环几轮拿到答案。演示效果不错,但一到生产环境就会暴露几类问题:
- 状态丢失:多轮对话后上下文越来越长,早期关键信息被挤掉,或者会话重启后状态归零;
- 工具失控:某个工具超时或返回异常结构,循环卡死或反复重试;
- 无法定位:线上出问题时,只能看到一句"回答不对",看不到模型在哪一步、调了什么工具、传了什么参数;
- 成本不可控:循环步数没有上限,Token 消耗随对话轮次线性甚至指数上升。
这些问题本质上是工程问题。下面按"循环设计 → 工具契约 → 可观测性 → 云上部署"四个层面拆解。
二、把 Agent 抽象成四段循环
无论用哪家模型,Agent 的执行都可以抽象为四段:
- 感知(Perceive):组装目标、历史、检索到的上下文;
- 决策(Plan):模型输出下一步动作,调用工具或给出最终答案;
- 行动(Act):执行工具,带超时、重试与权限校验;
- 观察(Observe):把结构化结果回填上下文,进入下一轮。
关键是给循环加上步数上限和终止条件,否则一个错误的工具描述就可能让 Agent 原地打转。
def run_agent(goal, tools, max_steps=8):
ctx = {"goal": goal, "history": [], "scratch": {}}
for step in range(max_steps):
action = llm_decide(ctx, tools)
trace(step, "decide", action)
if action["type"] == "final":
return action["answer"]
result = execute_tool(action, tools) # 超时/重试在此封装
ctx["history"].append({"action": action, "result": result})
trace(step, "observe", result)
return "已达到最大步数,返回当前最优结果"
这段代码刻意保持朴素,因为工程化的空间在每一段的可替换性上:决策可以换模型,工具可以换实现,轨迹可以换存储,而循环本身不变。
三、工具契约:Agent 的手脚要标准化
工具是 Agent 与外部世界交互的接口。建议每个工具都遵循统一契约:名称、用途描述、参数 JSON Schema、返回结构、超时时间。
{
"name": "query_order",
"description": "根据订单号查询订单状态,仅在用户提供订单号时调用",
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string", "description": "订单号,纯数字"}
},
"required": ["order_id"]
},
"timeout_ms": 3000
}
统一契约带来三个好处:
- 工具可以在不同模型、不同 Agent 之间复用;
- 参数校验可以在执行前完成,避免把脏参数传给下游;
- 超时与重试策略可以集中配置,而不是散落在业务代码里。
一个常见错误是把工具描述写得过宽,例如"查询数据库"。模型很容易在不需要的时候调用它。描述里写清适用条件和不适用条件,能显著降低误调用率。
四、可观测性:让每一步都能回放
Agent 上线后最需要的不是更多功能,而是可调试。建议在三个层面埋点:
- 轨迹(Trace):记录每一步的输入、决策、工具名、参数、返回、耗时;
- 指标(Metrics):每轮步数、工具成功率、Token 消耗、端到端延迟;
- 日志(Logs):结构化事件,便于检索与告警。
把每轮循环抽象成一棵调用树是最实用的做法:父节点是一次 Agent 回合,子节点是工具调用。有了调用树,线上问题可以直接按 trace_id 回放,回归测试也可以复用真实轨迹。
import json, time, uuid
def trace(step, event, payload, trace_id=None):
record = {
"trace_id": trace_id or str(uuid.uuid4()),
"step": step,
"event": event,
"payload": payload,
"ts": int(time.time() * 1000),
}
logger.info(json.dumps(record, ensure_ascii=False))
五、在华为云上的部署映射
把上面的架构映射到云服务,一套性价比较高的组合是:
- 模型服务:ModelArts 或兼容 OpenAI 协议的推理服务,负责决策;
- 编排层:FunctionGraph 承载 Agent 循环,按调用计费、弹性伸缩;
- 存储层:OBS 保存轨迹与知识库文件,云数据库保存会话状态;
- 入口层:API 网关统一暴露接口,做鉴权、限流与灰度;
- 可观测:云日志服务(LTS)收集结构化日志,配合告警规则。
这套组合的最大优势是无服务器化:早期验证阶段无需长期维护实例,成本随调用量浮动。等流量上来后,再把编排层拆成常驻服务,迁移成本也不高。
如果涉及企业知识库,可以把文档放到 OBS,用向量检索服务构建 RAG;Agent 在决策阶段先检索再回答,能明显降低幻觉。
六、成本与稳定性优化
上线后常见的两个优化方向:
成本:给循环设步数上限;对简单意图走轻量模型,复杂任务才路由到强模型;把重复的工具结果做缓存;压缩上下文,只保留与当前目标相关的片段。
稳定性:工具调用统一超时与重试;对不可逆操作(如扣款、删除)加人工确认;用幂等键避免重试导致重复执行;对模型输出做 schema 校验,解析失败时走降级分支。
七、小结
Agent 的竞争力最终落在工程细节上:循环设计清楚、工具契约统一、轨迹可回放,再借助云上的弹性能力快速部署。开源生态提供了大量可复用组件,云平台解决了弹性与运维问题,两者结合,才能让 Agent 从演示走向可长期迭代的产品。
下一步可以从最小闭环开始:先跑通"单工具 + 轨迹记录",再逐步增加工具和评测集。不要一开始就追求全自动,先把可观测性做扎实,后面每一步都会更稳。
- 点赞
- 收藏
- 关注作者
评论(0)