Agent 开发最佳实践

本文介绍在 CloudBase 上开发和部署 AI Agent 的推荐路径，帮助你在最短时间内跑通「创建 → 调试 → 对外调用」的完整链路，并避开常见问题。

核心概念

在开始之前，先建立三个关键认知：

概念	说明
Agent 的运行形态	部署在 CloudBase 上的 Agent 本质是一个监听端口的 HTTP 服务（Web 云函数形态）。使用官方模板时该服务已内置；自建工程时需要自己实现（见下文）
统一调用入口	Agent 部署后通过云开发网关对外提供服务，调用地址为 https://<envId>.api.tcloudbasegateway.com/v1/aibot/bots/<agentId>/<path>。网关将 <path>、请求方法、请求体原样转发给你的服务，流式响应逐帧透传
模型接入点	环境内置大模型通过 https://<envId>.api.tcloudbasegateway.com/v1/ai/cloudbase 提供 OpenAI 兼容接口。官方模板默认使用该接入点，模型凭证通过 CLOUDBASE_APIKEY 环境变量传入

两种开发方式对比

开发方式	适用场景	上手成本
控制台模板创建（推荐）	绝大多数场景。基于官方 cloudbase-agent 模板，创建即可用	低。部署、模型凭证、调用协议全部由平台自动配置，无需手动填写任何密钥
CLI 自建工程	需要使用 LangChain、LangGraph 等自选框架，或对服务形态有特殊要求	中。需自行处理启动脚本、HTTP 服务与模型凭证配置，见下文「自建工程要点」

推荐路径：控制台模板创建

第 1 步：创建 Agent

在控制台「AI - Agent」页面创建 Agent，选择官方 cloudbase-agent 模板。创建过程中平台会自动完成：

• Agent 服务的部署与初始化
• 模型凭证注入（CLOUDBASE_APIKEY、AGENT_MODEL 等环境变量自动配置）

全程无需手动填写 API Key。创建后等待 Agent 状态变为「正常」即可。

第 2 步：在控制台调试

进入 Agent 详情页的「接入 & 调试」标签页，可以直接发起测试对话验证 Agent 是否就绪。模板 Agent 的对话接口遵循 JSON-RPC 格式：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/prompt",
  "params": {
    "prompt": [{ "type": "text", "text": "你好，介绍一下你自己" }]
  }
}

收到模型的正常回复即代表整条链路（部署、网关路由、模型调用）全部就绪。

第 3 步：拉到本地开发

Agent 详情页的「本地开发」标签页提供了针对你这个 Agent 的完整命令（含 agentId 与 envId，可整段复制到终端）：

# 1. 安装 CLI 并登录
npm install -g @cloudbase/cli && tcb login

# 2. 拉取 Agent 代码到本地
tcb fn code download <agentId> ./my-agent -e <envId>

# 3. 本地启动调试
cd my-agent
rm -rf node_modules && npm install && npm run dev

本地修改验证完成后，一条命令发布回云端：

tcb fn deploy <agentId> -e <envId>

要点：

• 本地运行需要模型凭证：云端部署时 CLOUDBASE_APIKEY、AGENT_MODEL、CLOUDBASE_ENV_ID 已自动配置，本地取相同值即可——在详情页右上角「环境变量 - 前往查看」处查看
• 换模型：修改 AGENT_MODEL 环境变量，模型名以控制台「AI - 大模型」页面已开通的模型为准
• 扩展能力：模板基于 @cloudbase/open-agent-kernel（OAK）构建，可通过其配置扩展工具调用（MCP）、会话持久化、多模态附件、人工审批等能力
• 更多本地调试细节参考 Agent 本地开发

第 4 步：把开发交给你的 AI 编程工具

如果你使用 Claude Code、Cursor、Codex 等 AI 编程工具，可以把上面的本地开发流程整体交给它：

1. 在控制台「环境配置 - API Key」创建一个环境 API Key
2. 将 Key 以环境变量方式提供给你的终端或编程 Agent（如 export CLOUDBASE_APIKEY=<key>）
3. 编程 Agent 即可代替你完成拉代码、本地调试、调用模型接入点与 Agent 端点验证、执行部署的完整闭环

注意：环境 API Key 权限较高，只在开发环境使用，不要写入代码仓库或前端代码。

更深度的 Agent 辅助开发（MCP、规则文件）参考 CloudBase AI Toolkit。

第 5 步：从你的服务端调用

「接入 & 调试」页提供 cURL / Node / 小程序 / Web 四种接入代码，可直接复制。以 cURL 为例：

curl -N -X POST "https://<envId>.api.tcloudbasegateway.com/v1/aibot/bots/<agentId>/acp" \
  -H "Authorization: Bearer <环境 API Key>" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"session/prompt","params":{"prompt":[{"type":"text","text":"你好"}]}}'

• 服务端调用必须携带 Authorization: Bearer <环境 API Key> 鉴权，未携带将返回 401。环境 API Key 在控制台「环境配置 - API Key」页面管理
• 响应为 SSE 流式，逐帧返回 session/update 事件。注意事件有多种类型：仅 agent_message_chunk（正文）与 agent_thought_chunk（思考过程）携带 params.update.content.text 增量文本，agent_phase、usage_update 等其他类型不含该字段，客户端应按 sessionUpdate 类型分支处理并忽略未识别的事件类型。完整事件定义见 ACP 协议文档
• Web / 小程序端应使用身份认证登录态调用，不要在前端代码中暴露环境 API Key

自建工程要点

使用自选框架（LangChain、LangGraph、CrewAI 等）自建工程时，可参考官方示例仓库 awesome-cloudbase-examples 的 httpfunctions/ 目录。以下三点是部署成败的关键：

1. 必须提供 scf_bootstrap 启动脚本

工程根目录需要一个可执行的 scf_bootstrap 文件作为启动入口：

#!/bin/bash
export PORT=${PORT:-9000}
node src/index.js

创建后执行 chmod 755 scf_bootstrap。缺少该文件时部署失败，报错 ResourceNotFound.Entryfile。

2. 代码形态是 HTTP Server

const http = require('http');
http.createServer(handler).listen(process.env.PORT || 9000);

监听 PORT 环境变量指定的端口（默认 9000），不要写成 exports.main = ... 的事件函数形态。

3. 使用 CLI 部署

使用 CloudBase CLI（3.7 及以上版本）：

tcb agent create -e <envId> --name my-agent --runtime Nodejs20.19 \
  --code . --install-dep --memory-size 1024 \
  --ignore ".git,node_modules,.DS_Store" \
  --env "OPENAI_API_KEY=<环境 API Key>,OPENAI_BASE_URL=https://<envId>.api.tcloudbasegateway.com/v1/ai/cloudbase,OPENAI_MODEL=<模型名>"

要点：

• 运行时使用 Nodejs20.19
• --install-dep：依赖在云端安装，本地 node_modules 无需上传（务必配合 --ignore 排除）
• 超时时间默认 7200 秒，已为 Agent 长连接场景设计，无需调整
• 环境变量名以你所用示例工程的 README 为准（上例为 httpfunctions/ 系列示例的约定）。注意：即使 Agent 与模型在同一环境内，调用模型接入点也必须显式携带环境 API Key，平台不会在自建部署中自动注入凭证
• 部署后通过 tcb agent detail <agentId> -e <envId> 轮询，Ready 就绪后即可调用；首次初始化需要数分钟属正常现象
• 网关对路径与协议不做约束，你可以实现自己的接口协议；若需对接官方前端组件，参考 Agent 开发文档 实现对应协议

发布与稳定运行

用 AI 编程工具迭代 Agent 时，改动频繁且单次改动范围不可控，"看起来能跑"与"真的正确"之间的差距会变大。以下实践帮助你快速迭代而不破坏线上服务。

环境隔离。 为开发与生产使用独立的 CloudBase 环境和各自的 API Key：开发环境允许 AI 工具自由迭代，生产环境只接受通过验收的版本。环境 ID 与 Key 通过环境变量注入，代码中不做硬编码，保证同一份代码在两个环境无修改部署。

蓝绿发布，不原地修补。 发布新版本时新建 Agent（得到新 agentId）→ 对新 agentId 跑验收 → 通过后将调用方配置切换到新版本 → 异常时切回旧 agentId 即可秒级回退 → 稳定运行后再清理旧版本。部署失败的实例删除重建，不在失败实例上反复修补。若 Agent 依赖有状态会话，切换前确认会话持久化在数据库等环境级存储而非进程内存，否则切换会中断已有用户的对话上下文。

协议级验收，不只看输出。 AI 生成代码最典型的隐性故障是接口"半正常"：流式响应能吐出文本，但结束事件缺失或错误，按协议实现的前端组件会挂起——肉眼看 demo 完全发现不了。验收脚本应校验：事件流完整且正常结束（而不是只判断"收到了文本"）；带合法凭证返回 200、不带凭证返回 401 两个方向都要测；再加 3~5 个固定输入的冒烟用例。脚本纳入代码仓库，AI 工具改完代码同样先过验收再合入；契约断言由开发者确认后锁定，不允许 AI 修改验收脚本本身。

依赖锁定。 package.json 使用精确版本号而非 ^/~——AI 框架类依赖迭代极快，宽松版本号会导致"上周还能部署、这周装不上"的漂移。明确告知 AI 编程工具：不允许修改依赖版本与协议适配层代码，只在业务逻辑范围内改动。

配额监控与降级。 大模型 Token 用量独立于资源点计量（见下文常见问题），重要业务定期检查控制台「套餐用量 - Token 用量」，提前准备加购 Token 资源包或接入自有模型 API Key 的降级路径，客户端对 429 做友好降级提示。

推荐与避免

✓ 推荐	✗ 避免
从控制台模板创建起步，凭证与协议层开箱即用	从零手写协议层与凭证管理，问题排查成本高
开发、生产分环境，各自独立 API Key	单环境混用，AI 工具直接操作生产
新建部署 + 验证 + 切流，保留旧版本可回退	原地更新线上服务，失败后无版本可回
模型访问统一走 /v1/ai/cloudbase 接入点	硬编码指向单一厂商接入点，配额独立计量易触发限额
package.json 锁定已验证的依赖版本	使用宽松版本号（^），框架跨版本升级可能引入不兼容
自建工程先本地跑通再部署	直接部署后在云端排障
验证调用时确认完整响应流正常结束	只看到有文本输出就认为成功

常见问题

调用模型返回 429 EXCEED_TOKEN_QUOTA_LIMIT？

大模型 Token 用量是独立于资源点的计量维度，且不同模型接入点的配额独立计算。排查步骤：

1. 在控制台「套餐用量 - Token 用量」查看各模型的 Token 消耗与剩余额度
2. 确认代码使用的是 /v1/ai/cloudbase 接入点
3. 额度不足时，可加购 Token 资源包，或在「AI - 大模型」中接入自有模型 API Key

调用模型返回 403 AI_MODEL_NOT_SUPPORTED？

请求的模型名在当前环境未开通。以控制台「AI - 大模型」页面展示的已开通模型为准，注意模型名需完整匹配（含版本后缀）。

调用 Agent 返回 401？

请求未携带有效鉴权。服务端调用需携带 Authorization: Bearer <环境 API Key>；前端调用使用身份认证登录态。

部署后一直未就绪？

Agent 创建后需要数分钟完成资源初始化，属正常现象。若长时间未就绪，用 tcb agent detail 查看失败原因；自建工程最常见的原因是缺少 scf_bootstrap 或依赖安装失败。

自建工程创建失败后如何恢复？

修复问题后，先 tcb agent delete <agentId> --yes 删除失败的 Agent，再重新执行 tcb agent create；不建议在失败实例上原地更新。

相关资源

• Agent 开发概述
• Agent 本地开发
• ACP 协议
• @cloudbase/open-agent-kernel
• 官方示例仓库 awesome-cloudbase-examples
• 身份认证最佳实践
• 私有网络接入最佳实践
• 云托管灰度发布