Skip to main content

本地开发

本文介绍如何在本地开发和调试 Agent。

快速开始​

第一步：获取项目代码​

方式一：从 GitHub 模板获取（推荐）​

访问 awesome-cloudbase-examples 获取完整的示例项目集合。

# 克隆示例仓库
git clone https://github.com/TencentCloudBase/awesome-cloudbase-examples.git
cd awesome-cloudbase-examples/httpfunctions

# 选择你需要的模板
cd <template-name>

可用模板列表：

模板名称语言框架说明
langchain-jsJavaScriptLangChainLangChain Agent 示例（JS）
langchain-tsTypeScriptLangChainLangChain Agent 示例（TS）
langgraph-jsJavaScriptLangGraphLangGraph Agent 示例（JS）
langgraph-tsTypeScriptLangGraphLangGraph Agent 示例（TS）
langgraph-pythonPythonLangGraphLangGraph Agent 示例（Python）
crewai-pythonPythonCrewAICrewAI 多 Agent 协作示例
adk-pythonPythonADKAgent Development Kit 示例
adp-jsJavaScriptADPAgent Development Platform 示例
adp-tsTypeScriptADPAgent Development Platform 示例
coze-pythonPythonCozeCoze Agent 示例
框架接入指南

如需了解如何接入特定框架，请参考：

方式二：同步线上服务到本地​

如果你已经在云端部署了 Agent 服务，可以将代码同步到本地进行开发。

前置条件：安装 CloudBase CLI

npm install -g @cloudbase/cli

# 登录云开发
cloudbase login

同步 HTTP 云函数：

# 查看云函数列表
cloudbase fn list -e <env-id>

# 下载云函数代码到本地
mkdir -p ./my-agent && cloudbase fn code download -e <env-id> <function-name> ./my-agent
cd ./my-agent

同步云托管服务：

# 查看云托管服务列表
cloudbase cloudrun list

# 下载云托管代码到本地
cloudbase cloudrun download -s <service-name> --targetPath ./my-agent
cd my-agent
CLI 文档

更多 CLI 命令和用法，请参考 CloudBase CLI 文档。

第二步：安装依赖​

根据项目类型安装依赖。每个模板的 README 文件中都有详细的安装指引。

# 使用 npm
npm install

# 或使用 yarn
yarn install

# 或使用 pnpm
pnpm install
查看模板文档

每个模板都包含详细的 README 文档，说明了依赖安装、配置和运行方式。建议先阅读模板的 README 文件。

第三步：配置环境变量​

不同模板的环境变量配置可能不同，以下以 LangGraph 模板为例。

创建 .env 文件：

# 配置 agent 中调用的模型信息
OPENAI_API_KEY=xxx
OPENAI_BASE_URL=xxx
OPENAI_MODEL=xxx
# Temperature (default: 0.7)
OPENAI_TEMPERATURE=0.7

# 可选：启用 CORS（本地开发跨域调试时可设为 true）
# ENABLE_CORS=true                    # 服务端口（默认 3000）
获取配置信息

第四步：启动服务​

node src/index.js

服务启动后，默认在 http://localhost:9000 提供服务。

使用 Docker 运行​

对于云托管项目，可以使用 Docker 进行本地开发，确保本地环境与线上环境一致。

# 构建镜像
docker build -t my-agent .

# 运行容器
docker run -p 9000:9000 \
  -e OPENAI_API_KEY=your-api-key \
  -e OPENAI_BASE_URL=model-base-url \
  -e OPENAI_MODEL=model \
  -e OPENAI_TEMPERATURE=0.7 \
  my-agent

本地调试​

方式一：使用 cURL 调试​

curl 'http://localhost:9000/send-message' \
  -H 'Accept: text/event-stream' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "threadId": "550e8400-e29b-41d4-a716-446655440000",
    "messages": [
      { "id": "msg-1", "role": "user", "content": "你好" }
    ],
    "tools": [],
    "context": [],
    "state": {},
    "forwardedProps": {}
  }'

方式二：代理线上请求到本地​

此方法适用于将 Agent UI 或 SDK 对线上 Agent 的请求代理到本地，实现不更改客户端代码的情况下本地调试。

线上地址示例：

https://lowcode-3geceaptb6c8835b.api.tcloudbasegateway.com/v1/aibot/bots/agent-kkk-5gxr7dys9d0c5427/send-message

1. 安装 Whistle​

npm install -g whistle

# 启动 Whistle
w2 start

2. 配置代理规则​

访问 http://localhost:8899，在 Rules 中添加：

# 将线上 Agent 请求代理到本地
https://lowcode-3geceaptb6c8835b.api.tcloudbasegateway.com/v1/aibot/bots/agent-kkk-5gxr7dys9d0c5427/send-message resCross://* http://localhost:9000/send-message

3. 配置代理​

根据使用方式不同，在不同位置配置代理：

在微信开发者工具中：

  1. 打开微信开发者工具
  2. 设置 → 代理设置 → 手动设置代理
  3. 代理服务器：127.0.0.1
  4. 端口：8899
  5. 勾选"使用代理"

在浏览器中：

可以通过浏览器插件将网页中的请求代理到 8899 端口：

  • Chrome：使用 SwitchyOmega 插件
    1. 安装 SwitchyOmega 插件
    2. 新建情景模式 → 代理服务器
    3. 代理协议：HTTP
    4. 代理服务器：127.0.0.1
    5. 代理端口：8899
    6. 应用选项并切换到该情景模式

4. 安装 HTTPS 证书​

访问 http://localhost:8899，点击 HTTPS → 下载根证书并安装。

使用场景
  • 使用 Agent UI 调试线上 Agent
  • 使用 SDK 在真实环境中调试
  • 不修改客户端代码的情况下本地调试

常见问题​

1. 端口被占用​

# 查看端口占用
lsof -i :9000  # macOS/Linux
netstat -ano | findstr :9000  # Windows

# 杀死进程
kill -9 <PID>  # macOS/Linux
taskkill /PID <PID> /F  # Windows

# 或更换端口
PORT=3001 node index.js

2. 代理不生效​

  • 确保 Whistle 已启动：w2 status
  • 检查代理规则是否正确
  • 确认系统代理已配置
  • 小程序需要在微信开发者工具中单独配置代理

下一步​

完成本地开发后，可以将 Agent 部署到云端：

或了解如何在客户端调用 Agent：