本地开发

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

快速开始

第一步：获取项目代码

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

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

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

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

可用模板列表：

模板名称	语言	框架	说明
langchain-js	JavaScript	LangChain	LangChain Agent 示例（JS）
langchain-ts	TypeScript	LangChain	LangChain Agent 示例（TS）
langgraph-js	JavaScript	LangGraph	LangGraph Agent 示例（JS）
langgraph-ts	TypeScript	LangGraph	LangGraph Agent 示例（TS）
langgraph-python	Python	LangGraph	LangGraph Agent 示例（Python）
crewai-python	Python	CrewAI	CrewAI 多 Agent 协作示例
adk-python	Python	ADK	Agent Development Kit 示例
adp-js	JavaScript	ADP	Agent Development Platform 示例
adp-ts	TypeScript	ADP	Agent Development Platform 示例
coze-python	Python	Coze	Coze Agent 示例

框架接入指南

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

• LangChain 开发指南
• LangGraph 开发指南
• CrewAI 开发指南

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

如果你已经在云端部署了 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 文件中都有详细的安装指引。

Node.js 项目

# 使用 npm
npm install

# 或使用 yarn
yarn install

# 或使用 pnpm
pnpm install

Python 项目

# 使用 pip
pip install -r requirements.txt

查看模板文档

每个模板都包含详细的 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）

获取配置信息

• API Key：在云开发控制台 - API 密钥创建
• 模型列表：参考 大模型配置指南

第四步：启动服务

Node.js 项目

node src/index.js

Python 项目

# 直接运行
python -u app.py

服务启动后，默认在 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 部署到云端：

• 📦 HTTP 云函数部署
• 🚀 云托管部署

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

• 📱 小程序调用
• 🌐 Web 调用
• 🔧 Node.js 调用