Agent 专题：从第一次调用到可恢复的智能工作流

这个专题解决什么问题

如果你只看单个模型或单个客户端，很容易遇到三个断点：API 能调用，但不知道如何让模型使用工具；工具能调用，但没有状态、步数和权限边界；任务能完成，但无法解释过程、恢复失败或复用成功配置。

这个专题把 GPT88 现有的 API、模型、开发工具和工程实践文档组织成一条 Agent 学习路线。你可以把它当作 Cocode 式的总入口：先快速开始，再进入核心概念、开发者 API、工具接入、可观察性和排错。

看完后的完成标准

完成本专题的最小标准不是“读完所有页面”，而是你能够独立完成下面这些动作：

• 使用 API Key + Base URL + 模型 ID 跑通一次最小请求；
• 给模型声明一个工具，并识别返回中的 tool_calls；
• 在本地执行允许的工具，把结果以 role: tool 消息回传；
• 给 Agent 设置最大步数、超时、允许动作和人工确认边界；
• 记录请求 ID、工具输入、工具输出、失败原因和最终交付物；
• 能在 401、404、429、超时或工具失败时，从最小故障点恢复。

推荐学习路径

Agent 的六个核心概念

用户目标
   ↓
读取上下文 → 规划下一步 → 调用模型
                         ↓
                 需要工具？──否──→ 返回结果
                     │是
                     ↓
              执行工具并记录结果
                     ↓
                 继续循环
                     ↓
               验证产出并交付

一个重要边界是：模型只能提出工具调用，真正执行工具的是你的应用或客户端。应用必须校验工具名和参数，决定是否允许执行，再把结构化结果回传给模型。不要把“模型说要执行”直接等同于“动作已经执行”。

最短成功路径：跑通一个工具调用

1. 准备输入。创建 API Key，并通过 GET /v1/models 选择当前账号可见的模型。验证：你能拿到一个真实可用的模型 ID。
2. 先跑普通请求。用 快速开始 的最小示例确认认证、网络和响应结构没有问题。验证：返回 choices[0].message。
3. 声明一个只读工具。从“读取项目状态”或“查询任务状态”开始，不要一上来就开放删除、发布或支付动作。验证：请求体包含 tools 和清晰的 JSON Schema。
4. 识别工具调用。检查 choices[0].message.tool_calls，读取工具名、调用 ID 和 JSON 参数。验证：参数能被 JSON 解析并通过本地 Schema 校验。
5. 执行并回传。由应用执行允许的只读函数，并把结果作为 role: tool 消息放回同一轮消息历史。验证：下一次模型响应能够引用工具结果。
6. 检查最终结果。不要只检查模型有没有返回文字，还要验证工具结果、最终结论和交付格式。验证：结果能被人或程序复核。

工具调用之后，应用要做什么

curl https://api.gpt88.cc/v1/chat/completions \
  -H "Authorization: Bearer $GPT88_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "user", "content": "检查项目当前发布状态"}
    ],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_project_status",
        "description": "读取项目当前环境、版本和发布状态",
        "parameters": {
          "type": "object",
          "properties": {},
          "additionalProperties": false
        }
      }
    }],
    "tool_choice": "auto"
  }'

把调用封装成可恢复循环

原型阶段可以手动处理一次工具调用；进入真实项目后，需要把循环封装成有状态的执行器。至少保存目标、消息历史、每一步工具调用、工具结果、错误、耗时和最终交付物。

const state = {
  goal,
  messages: [{ role: "user", content: goal }],
  steps: [],
  maxSteps: 8,
}

while (state.steps.length < state.maxSteps) {
  const response = await callModel(state.messages, tools)
  const toolCalls = response.choices?.[0]?.message?.tool_calls ?? []

  if (toolCalls.length === 0) {
    return verifyAndDeliver(response.choices[0].message.content)
  }

  state.messages.push(response.choices[0].message)
  for (const call of toolCalls) {
    const args = JSON.parse(call.function.arguments || "{}")
    const result = await executeAllowedTool(call.function.name, args)
    state.steps.push({ call, result })
    state.messages.push({
      role: "tool",
      tool_call_id: call.id,
      content: JSON.stringify(result),
    })
  }
}

throw new Error("agent step limit reached")

这个示例是工作流骨架，不是可以直接复制到生产环境的完整 SDK。生产实现还需要加入：

• 参数 Schema 校验和工具白名单；
• 超时、重试、指数退避和幂等键；
• 敏感数据脱敏、日志保留和终端用户标识；
• 最大步骤数、最大成本或资源预算；
• 失败后继续、暂停等待人工确认或安全回滚的策略。

什么时候用哪种接入方式

按工具选择接入教程

如果你还没有决定使用哪个工具，先选择能最快完成一次可验证任务的入口：终端优先 Codex CLI 或 Claude Code，编辑器优先 Cursor 或 Cline，应用编排优先 Dify，纯 API 开发优先 Python 或 Node.js SDK。

可观察性、权限与恢复

Agent 的质量不只看最终回答，还要看它是否走了正确的路径。建议为每次任务建立一个可追踪记录，至少包含：任务目标、使用模型、请求 ID、消息摘要、工具名、参数摘要、执行结果、失败原因、人工确认点和最终交付物位置。

• Harness Inspector：把 Agent 意图、Session、文件活动和 Commit 连接成交付证据链。
• Codex 工具恢复：工具不可用时，从文件工具、执行环境和恢复顺序开始排查。
• Loop Engineering 与 Harness：把一次任务的成功路径沉淀为可复用循环。
• Skills 与上下文工程：将规则、上下文、权限和工作记录组合成稳定工作方式。

生产化验收清单

身份与配置
- API Key 放在服务端环境变量或密钥管理器中
- 不在日志、截图、Prompt 或前端代码中输出完整 Key
- 模型 ID、Base URL 和当前账号权限已验证

执行与可靠性
- 工具名和参数经过白名单 / Schema 校验
- 设置最大步骤数、超时、重试和停止条件
- 对写入、发布、发送和删除动作保留人工确认
- 工具执行具备幂等或可安全重试能力

观测与验收
- 记录 request_id、模型、耗时、工具调用和错误摘要
- 最终结果有结构化验收标准，而不是只看自然语言
- 失败任务可以从最近一个安全状态恢复
- 成功的配置、Prompt、工具 Schema 和验收清单已保存

扩展前检查
- 先用少量任务验证质量、耗时、成本和失败率
- 再组合多个工具或执行批量任务
- 模型、价格、限速和响应差异以控制台与实时 API 为准

常见问题与排错顺序

练习任务

用一个只读的“项目状态检查 Agent”完成下面的练习：

1. 声明 get_project_status 工具，只返回环境、版本、测试状态和最近一次发布结果。
2. 让模型根据用户问题决定是否调用工具，不允许直接猜测项目状态。
3. 模拟一次工具成功返回和一次工具超时，分别验证 Agent 的回答。
4. 把每一步写入 JSONL 或数据库，包含调用 ID、参数、结果和耗时。
5. 给任务加上最大 4 步限制，并写出“超过限制后如何暂停和人工接管”。

验收标准：

• 没有工具结果时，Agent 明确说明无法确认，而不是编造状态；
• 工具失败时，用户能看到可执行的下一步，而不是无上下文的“请求失败”；
• 同一请求可以通过 request ID 和 tool call ID 还原执行过程；
• 修改工具描述或模型后，仍能通过同一套验收清单回归。

下一步阅读

• 第一次接入：Quick start → Model list API → Chat Completions API.
• 使用成熟工具：Integration guide，then open the relevant Claude Code, Codex CLI, Cursor, Cline or Dify page.
• 构建生产服务：Complete integration guide → Config export → Harness Inspector.
• 处理异步媒体任务：Async image generation API guide，bring task submission, polling, recovery and result downloads into the Agent workflow.