Agent 管理

版本提示

自 v5.0.0 起新增此模块。

Agent 支持两种底层部署类型：

SCF（云函数）：轻量级、按需计费，适合低并发场景
TCBR（云托管）：容器化，适合高并发或需要自定义运行环境的场景

创建 Agent

1. 接口描述

接口功能：在当前环境下创建一个基于 SCF（云函数）的 Agent

接口声明：app.agent.createAgent(params): Promise<ICreateAgentResponse>

2. 输入参数

字段	必填	类型	说明
Name	是	String	Agent 名称
Runtime	是	RuntimeVersion	运行时版本，见下方枚举表
AgentId	否	String	Agent ID，不传则自动生成
envVariables	否	`Record<string,string>`	环境变量键值对
Timeout	否	Number	超时时间（秒），默认 7200
MemorySize	否	Number	内存大小（MB），默认 128，可选 64 或 128~3072（128 阶梯）
InstallDependency	否	Boolean	是否自动安装依赖，默认 `false`
SessionConfig	否	ISessionConfig	会话配置，见下方说明
cwd	否	String	本地代码目录，与 `ZipFile` 二选一
ignore	否	String \| String[]	打包时忽略的文件 glob（仅 `cwd` 方式有效）
deployMode	否	`'zip'` \| `'cos'`	上传方式，默认 `'zip'`，大文件推荐 `'cos'`
ZipFile	否	String	Base64 编码的 ZIP 文件内容，与 `cwd` 二选一
CosBucketRegion	否	String	COS Bucket 区域（仅直接上传时使用）
TempCosObjectName	否	String	COS 临时对象名称（仅直接上传时使用）

RuntimeVersion 枚举

值	说明
`Nodejs20.19`	Node.js 20.19
`Nodejs18.15`	Node.js 18.15
`Nodejs16.13`	Node.js 16.13
`Nodejs14.18`	Node.js 14.18
`Python3.10`	Python 3.10
`Python3.9`	Python 3.9
`Python3.7`	Python 3.7
`Php8.0`	PHP 8.0
`Php7.4`	PHP 7.4
`Go1`	Go 1.x
`Java11`	Java 11
`Java8`	Java 8

ISessionConfig

字段	必填	类型	说明
SessionSource	否	String	会话来源：`'HEADER'`（默认）、`'COOKIE'`、`'QUERY_STRING'`
SessionName	否	String	会话名称，5~40 字符，字母开头，默认 `'X-Session-Id'`
MaximumConcurrencySessionPerInstance	否	Number	单实例并发会话数，1~100，默认 1
MaximumTTLInSeconds	否	Number	会话最长生命周期（秒），默认 21600
MaximumIdleTimeInSeconds	否	Number	会话最长空闲时间（秒），默认 1800
MaxConcurrency	否	Number	单实例最大并发数，1~100，默认 50

3. 返回结果

字段	类型	说明
AgentId	String	创建的 Agent ID
RequestId	String	请求唯一标识

4. 示例代码

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

async function main() {
  // 方式一：通过本地代码目录创建
  const res = await app.agent.createAgent({
    Name: 'my-agent',
    Runtime: 'Nodejs18.15',
    cwd: '/path/to/agent/code',
    InstallDependency: true,
    envVariables: {
      OPENAI_API_KEY: 'sk-xxx'
    }
  })
  console.log('Agent ID:', res.AgentId)
}

main()

查询 Agent 列表

1. 接口描述

接口功能：查询当前环境下的 Agent 列表

接口声明：app.agent.describeAgentList(params?): Promise<IDescribeAgentListResponse>

2. 输入参数

字段	必填	类型	说明
PageSize	否	Number	每页返回数量，默认 20
PageNumber	否	Number	页码，默认 1
AgentId	否	String	指定 Agent ID（用于查询单个）

3. 返回结果

字段	类型	说明
AgentList	`Array<IAgentInfo>`	Agent 列表
Total	Number	Agent 总数
RequestId	String	请求唯一标识

IAgentInfo

字段	类型	说明
AgentId	String	Agent ID
Name	String	Agent 名称
AgentType	String	Agent 类型：`scf` 或 `tcbr`
Introduction	String	简介
Avatar	String	头像 URL
Tags	String[]	标签列表
CreateTime	String	创建时间
UpdateTime	String	更新时间
Status	String	状态
ServiceId	String	底层服务 ID

4. 示例代码

async function main() {
  const { AgentList, Total } = await app.agent.describeAgentList({ PageSize: 10 })
  console.log(`共 ${Total} 个 Agent`)
  AgentList.forEach(a => console.log(a.AgentId, a.Name, a.AgentType))
}

查询 Agent 详情

1. 接口描述

接口功能：查询单个 Agent 详情，并检查底层资源（云函数 / 云托管）是否就绪可用

接口声明：app.agent.describeAgent(agentId): Promise<IDescribeAgentResponse>

2. 输入参数

字段	必填	类型	说明
agentId	是	String	Agent ID

3. 返回结果

字段	类型	说明
AgentInfo	IAgentInfo	Agent 基本信息，不存在时为 `null`
IsReady	Boolean	Agent 是否已就绪可调用
NotReadyReason	String	不可用时的原因说明
RequestId	String	请求唯一标识

4. 示例代码

async function main() {
  const detail = await app.agent.describeAgent('agent-xxx')
  if (detail.IsReady) {
    console.log('Agent 已就绪')
  } else {
    console.log('不可用原因:', detail.NotReadyReason)
  }
}

更新 Agent

1. 接口描述

接口功能：更新 Agent 的代码或配置，自动根据 Agent 类型（SCF / TCBR）调用对应逻辑

接口声明：app.agent.updateAgent(params): Promise<IUpdateScfAgentResponse>

2. 输入参数

字段	必填	类型	说明
AgentId	是	String	Agent ID
cwd	否	String	本地代码目录（与 `ZipFile` 二选一）
ZipFile	否	String	Base64 编码的 ZIP 文件内容（与 `cwd` 二选一）
envVariables	否	`Record<string,string>`	环境变量键值对
Runtime	否	RuntimeVersion	运行时版本
Timeout	否	Number	超时时间（秒）
MemorySize	否	Number	内存大小（MB）
InstallDependency	否	Boolean	是否自动安装依赖
Ignore	否	String \| String[]	打包忽略的文件 glob

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
elapsedTime	Number	更新总耗时（毫秒）
message	String	结果消息
details	String[]	各步骤详细信息

4. 示例代码

async function main() {
  const res = await app.agent.updateAgent({
    AgentId: 'agent-xxx',
    cwd: '/path/to/new/code',
    envVariables: { API_KEY: 'new-key' }
  })
  console.log(`更新完成，耗时 ${res.elapsedTime}ms`)
}

删除 Agent

1. 接口描述

接口功能：删除指定 Agent，同时尝试删除底层云函数或云托管资源

接口声明：app.agent.deleteAgent(params): Promise<IDeleteAgentResponse>

2. 输入参数

字段	必填	类型	说明
AgentId	是	String	Agent ID

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
AgentDeleted	Boolean	Agent 记录是否删除成功
ResourceResult	Object \| undefined	底层资源删除结果，见下方说明

ResourceResult

字段	类型	说明
Type	String	资源类型：`scf` 或 `tcbr`
Name	String	资源名称（即 AgentId）
Deleted	Boolean	底层资源是否删除成功
Error	String	删除失败时的错误信息
CleanupHint	String	删除失败时的手动清理提示

注意

若底层资源删除失败（ResourceResult.Deleted = false），Agent 记录已删除，但云函数或云托管服务仍存在，需根据 CleanupHint 手动清理。

4. 示例代码

async function main() {
  const res = await app.agent.deleteAgent({ AgentId: 'agent-xxx' })
  if (res.AgentDeleted) {
    if (res.ResourceResult?.Deleted) {
      console.log('Agent 及底层资源均已删除')
    } else {
      console.warn('Agent 已删除，但底层资源删除失败:', res.ResourceResult?.CleanupHint)
    }
  }
}

获取 Agent 日志

1. 接口描述

接口功能：获取 Agent 的运行日志，自动根据 Agent 类型路由到对应日志源（SCF 函数日志 / CLS 日志）

接口声明：app.agent.getAgentLogs(params): Promise<any>

返回结构说明

SCF Agent：返回函数日志数组（IFunctionLogDetailRes[]）
TCBR Agent：返回 CLS 日志结构（ISearchClsLogResponse，同 app.log.searchClsLog）

2. 输入参数

字段	必填	类型	说明
AgentId	是	String	Agent ID
offset	否	Number	偏移量，默认 0（仅 SCF Agent）
limit	否	Number	返回条数，默认 10，最大 100
startTime	否	String	开始时间，格式 `YYYY-MM-DD HH:mm:ss`
endTime	否	String	结束时间，格式 `YYYY-MM-DD HH:mm:ss`
requestId	否	String	按 RequestId 筛选（仅 SCF Agent 有效）

3. 示例代码

async function main() {
  const logs = await app.agent.getAgentLogs({
    AgentId: 'agent-xxx',
    limit: 20,
    startTime: '2025-01-01 00:00:00',
    endTime: '2025-01-01 23:59:59'
  })
  console.log(JSON.stringify(logs, null, 2))
}

Agent 管理

创建 Agent​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

查询 Agent 列表​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

查询 Agent 详情​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

更新 Agent​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

删除 Agent​

1. 接口描述​

2. 输入参数​

3. 返回结果​

4. 示例代码​

获取 Agent 日志​

1. 接口描述​

2. 输入参数​

3. 示例代码​

创建 Agent

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

查询 Agent 列表

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

查询 Agent 详情

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

更新 Agent

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

删除 Agent

1. 接口描述

2. 输入参数

3. 返回结果

4. 示例代码

获取 Agent 日志

1. 接口描述

2. 输入参数

3. 示例代码