ZGI 上线 Gitee：把 Agent 从演示原型带进可执行、可追踪的运行时

创建一个能调用模型、工具和知识库的 Agent，通常只是工程的起点。进入真实环境后，团队还要回答一组更棘手的问题：任务由谁执行，失败后如何处理，运行过程怎样追踪，多个 Agent 又该如何统一管理。Agent Runtime 项目 ZGI 正式同步上线 Gitee，并开放源代码与部署文档，关注的正是 Agent 从 Demo 走向长期运行的这段距离。

Agent Demo 与 Agent Runtime 之间差了什么

一个 Demo 往往只需要完成一次理想路径：接收输入、调用模型、执行工具、返回答案。但生产系统不能假设网络永远稳定、模型永远按时响应、工具调用永远成功。

从工程视角看，Agent Runtime 至少需要承接三类职责：

• 执行：接收任务，组织模型与工具调用，并明确任务的开始、结束、超时和失败状态。
• 追踪：记录每次运行的输入、步骤、工具调用、耗时和错误，使问题能够复现和定位。
• 管理：统一处理 Agent 配置、运行实例、资源边界和生命周期，而不是依赖开发者手工启动脚本。

这也是 ZGI 标题中“被执行、追踪和管理”的实际意义。Agent 定义回答“它能做什么”，Runtime 则回答“它如何持续工作，以及出问题时我们怎样知道”。

需要注意的是，来源摘要没有披露 ZGI 的具体 API、配置字段和内部架构。因此，下面的配置与命令是用于评估 Agent Runtime 的通用实践模板，接入 ZGI 时应以项目仓库中的部署文档和实际接口为准。

先把一次运行定义清楚

团队评估 Runtime 时，不应只检查 Agent 能否返回结果，还要检查每次运行是否拥有稳定的身份和状态流转。一个实用的任务模型可以包含以下字段：

# runtime-contract.example.yaml
# 示例契约，字段名需要按 ZGI 的实际配置或 API 调整。
agent:
  name: customer-support
  version: "2025-01"

execution:
  timeout_seconds: 120
  max_attempts: 3
  concurrency: 4

trace:
  enabled: true
  record_tool_calls: true
  redact_fields:
    - authorization
    - phone
    - email

lifecycle:
  terminal_states:
    - succeeded
    - failed
    - cancelled
    - timed_out

这里有几个容易被忽略的决定：

• version 让运行记录能够关联到确定的 Agent 配置，避免修改提示词后无法复现旧任务。
• timeout_seconds 和 max_attempts 必须同时存在，但重试不能默认用于所有工具。付款、发券、创建工单等操作需要幂等键，否则重试可能产生重复副作用。
• redact_fields 应在日志进入存储系统之前生效。事后清理敏感数据通常成本更高，也更难证明已经清理完整。
• 终态必须明确。长期停留在 running 的任务会占用并发额度，也会让监控数据失真。

部署前做一次可重复的预检

ZGI 已开放部署文档。拿到项目代码后，可以这样实践：在执行正式部署命令前，用一个小脚本检查基础工具、环境文件和 Compose 配置。下面假设仓库采用 Docker Compose；如果实际文档使用其他方式，应替换对应检查命令。

将 PROJECT_DIR 改成 ZGI 本地代码目录，然后直接运行：

#!/usr/bin/env bash
set -euo pipefail

PROJECT_DIR="${PROJECT_DIR:-$PWD}"
cd "$PROJECT_DIR"

command -v docker >/dev/null 2>&1 || {
  echo "docker is required" >&2
  exit 1
}

docker compose version >/dev/null

if [[ ! -f .env ]]; then
  if [[ -f .env.example ]]; then
    cp .env.example .env
    echo "Created .env from .env.example; fill in required values before startup."
  else
    echo "No .env or .env.example found; check the deployment documentation." >&2
    exit 1
  fi
fi

if [[ ! -f compose.yaml && ! -f docker-compose.yml && ! -f docker-compose.yaml ]]; then
  echo "No Compose file found; use the deployment method documented by the project." >&2
  exit 1
fi

docker compose config --quiet
echo "Preflight passed. Review secrets in .env, then run: docker compose up -d"

保存为 preflight.sh 后执行：

chmod +x preflight.sh
PROJECT_DIR=/path/to/zgi ./preflight.sh

这段脚本不会替代官方部署文档，但能把“缺少环境文件”“Compose 配置无法解析”等问题挡在启动之前。真正上线时，还应把预检放进 CI，而不是只在开发者电脑上执行。

追踪不是多打印几行日志

Agent 的一次运行通常包含模型请求、检索、工具调用和状态更新。只记录最终答案，很难解释它为什么失败；记录全部原始内容，又可能泄露令牌、个人信息或业务数据。

更合适的做法是采用结构化事件，并为整次运行复用同一个 run_id。可以这样设计事件格式，再映射到 ZGI 实际提供的追踪能力：

{
  "event": "tool_call_finished",
  "run_id": "run_01J...",
  "agent_version": "2025-01",
  "tool": "ticket.create",
  "status": "succeeded",
  "duration_ms": 382,
  "attempt": 1,
  "input_summary": "redacted",
  "timestamp": "2025-01-15T08:30:00Z"
}

建议重点验证以下问题：

• 能否从最终结果反查完整执行链路？
• 模型调用和工具调用是否分别统计耗时、错误率与重试次数？
• 运行记录是否绑定 Agent 版本、模型配置和工具版本？
• 管理员能否取消卡住的任务，并区分取消、超时和执行失败？
• 日志、提示词和工具参数是否有分级访问与脱敏机制？

追踪数据还需要保留期限。无限期保存全部提示词和工具参数既昂贵，也会扩大安全风险。团队应根据排障、审计和合规要求分别设置保留策略。

采用 ZGI 时的评估清单

ZGI 上线 Gitee 的价值，在于开发者可以结合开放的代码和部署文档，实际检查 Runtime 是否适合自己的 Agent 工作负载。评估时可以从一个非关键 Agent 开始，跑通任务提交、状态查询、失败重试、主动取消和链路追踪，再逐步增加并发与工具数量。

上线前至少确认这些边界：

• Runtime 进程重启后，运行中任务会恢复、重试还是失败？
• 相同任务重复提交时，系统和业务工具如何保证幂等？
• 并发限制是在 Agent、租户还是整个集群层面生效？
• 模型密钥与业务凭据如何注入、轮换和审计？
• 运行历史能否导出，数据格式是否便于接入现有监控系统？
• 升级 Runtime 或 Agent 配置时，旧任务如何处理？

不要用一次成功的对话作为验收标准。更可靠的验收方式是主动制造超时、工具报错、进程重启和重复请求，观察系统能否给出确定状态与完整证据。Agent 只有在失败路径同样可见、可控时，才真正具备长期运行的基础。