Agent Management

version tip

This module has been added since v5.0.0.

Agent supports two underlying deployment types:

• SCF (SCF): lightweight, pay-as-you-go, suitable for low concurrency scenarios.
• TCBR (Cloud Run): containerized, suitable for high concurrency or scenarios requiring custom runtime environments.

---

Create an Agent

1. API Description

API feature: Create an Agent based on SCF (Cloud Function) in the current environment.

API declaration: app.agent.createAgent(params): Promise<ICreateAgentResponse>

2. Input Parameters

Field	Required	Type	Description
Name	Required	String	Agent name
Runtime	Required	RuntimeVersion	Runtime version, see the enumeration table below.
AgentId	No	String	Agent ID, auto-generated if not provided
envVariables	No	Record<string,string>	Environment variable key-value pairs
Timeout	No	Number	Timeout period (seconds), default 7200
MemorySize	No	Number	Memory size (MB), default 128, optional 64 or 128~3072 (in increments of 128)
InstallDependency	No	Boolean	Whether to automatically install dependencies, default false
SessionConfig	No	ISessionConfig	Session configuration, see description below
cwd	No	String	Local code directory, mutually exclusive with ZipFile
ignore	No	String | String[]	File glob to ignore during packaging (only valid for cwd method)
deployMode	No	'zip' | 'cos'	Deployment method, default 'zip'; for large files, 'cos' is recommended
ZipFile	No	String	Base64-encoded ZIP file content, mutually exclusive with cwd
CosBucketRegion	No	String	COS Bucket region (used only for direct upload)
TempCosObjectName	No	String	COS temporary object name (used only for direct upload)

RuntimeVersion Enum

Value	Description
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

Field	Required	Type	Description
SessionSource	No	String	Session source: 'HEADER' (default), 'COOKIE', 'QUERY_STRING'
SessionName	No	String	Session name, 5-40 characters, starting with a letter; default 'X-Session-Id'
MaximumConcurrencySessionPerInstance	No	Number	Maximum concurrent sessions per instance, 1-100, default 1
MaximumTTLInSeconds	No	Number	Maximum session lifetime (seconds), default 21600
MaximumIdleTimeInSeconds	No	Number	Maximum session idle time (seconds), default 1800
MaxConcurrency	No	Number	Maximum concurrency per instance, 1-100, default 50

3. Return Results

Field	Type	Description
AgentId	String	Created Agent ID
RequestId	String	Unique identifier of the request

4. Sample Code

import CloudBase from '@cloudbase/manager-node'

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

async function main() {
  // Method 1: Create via local code directory
  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()

---

Query Agent List

1. API Description

API feature: queries the Agent list in the current environment

API declaration: app.agent.describeAgentList(params?): Promise<IDescribeAgentListResponse>

2. Input Parameters

Field	Required	Type	Description
PageSize	No	Number	Number of items per page, default: 20
PageNumber	No	Number	Page number, default: 1
AgentId	No	String	Specify Agent ID (used for querying a single one)

3. Return Results

Field	Type	Description
AgentList	Array<IAgentInfo>	Agent list
Total	Number	Total Agents
RequestId	String	Unique identifier of the request

IAgentInfo

Field	Type	Description
AgentId	String	Agent ID
Name	String	Agent name
AgentType	String	Agent type: scf or tcbr
Introduction	String	Introduction
Avatar	String	Avatar URL
Tags	String[]	Tag list
CreateTime	String	Creation time
UpdateTime	String	Update time
Status	String	Status
ServiceId	String	Underlying service ID

4. Sample Code

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

---

Query Agent Details

1. API Description

API feature: query the details of a single Agent, and check whether the underlying resources (SCF / Cloud Run) are ready and available.

API declaration: app.agent.describeAgent(agentId): Promise<IDescribeAgentResponse>

2. Input Parameters

Field	Required	Type	Description
agentId	Yes	String	Agent ID

3. Return Results

Field	Type	Description
AgentInfo	IAgentInfo	Basic information of the Agent, null when not present
IsReady	Boolean	whether the Agent is ready and available
NotReadyReason	String	Reason description when unavailable
RequestId	String	Unique identifier of the request

4. Sample Code

async function main() {
  const detail = await app.agent.describeAgent('agent-xxx')
  if (detail.IsReady) {
    console.log('Agent is ready')
  } else {
    console.log('Unavailable reason:', detail.NotReadyReason)
  }
}

---

Update an Agent

1. API Description

API feature: Updates the Agent's code or configuration, automatically invoking the corresponding logic based on the Agent type (SCF / TCBR).

API declaration: app.agent.updateAgent(params): Promise<IUpdateScfAgentResponse>

2. Input Parameters

Field	Required	Type	Description
AgentId	Yes	String	Agent ID
cwd	No	String	Local code directory (mutually exclusive with ZipFile)
ZipFile	No	String	Base64-encoded ZIP file content (mutually exclusive with cwd)
envVariables	No	Record<string,string>	Environment variable key-value pairs
Runtime	No	RuntimeVersion	Runtime version
Timeout	No	Number	Timeout period (seconds)
MemorySize	No	Number	Memory size (MB)
InstallDependency	No	Boolean	whether to automatically install dependencies
Ignore	No	String | String[]	Files to ignore during packaging (file glob)

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
elapsedTime	Number	Total elapsed time for update (ms)
message	String	Result message
details	String[]	Details of each step

4. Sample Code

async function main() {
  const res = await app.agent.updateAgent({
    AgentId: 'agent-xxx',
    cwd: '/path/to/new/code',
    envVariables: { API_KEY: 'new-key' }
  })
  console.log(`Update completed, elapsed time ${res.elapsedTime}ms`)
}

---

Delete the Agent

1. API Description

API feature: deletes the specified Agent and attempts to delete the underlying SCF or Cloud Run resources.

API declaration: app.agent.deleteAgent(params): Promise<IDeleteAgentResponse>

2. Input Parameters

Field	Required	Type	Description
AgentId	Yes	String	Agent ID

3. Return Results

Field	Type	Description
RequestId	String	Unique identifier of the request
AgentDeleted	Boolean	whether the Agent record was successfully deleted
ResourceResult	Object | undefined	Result of underlying resource deletion; see below for details

ResourceResult

Field	Type	Description
Type	String	Resource type: scf or tcbr
Name	String	Resource name (i.e. AgentId)
Deleted	Boolean	whether the underlying resources were successfully deleted
Error	String	Error message when deletion fails
CleanupHint	String	Manual cleanup instructions when deletion fails

Caution

If the underlying resources fail to be deleted (ResourceResult.Deleted = false), the Agent record has been deleted, but the SCF or Cloud Run service still exists. Manually clean them up according to CleanupHint.

4. Sample Code

async function main() {
  const res = await app.agent.deleteAgent({ AgentId: 'agent-xxx' })
  if (res.AgentDeleted) {
    if (res.ResourceResult?.Deleted) {
      console.log('Agent and underlying resources have been deleted')
    } else {
      console.warn('Agent has been deleted, but underlying resources deletion failed:', res.ResourceResult?.CleanupHint)
    }
  }
}

---

Obtain Agent Logs

1. API Description

API feature: Obtains the Agent's runtime logs, automatically routing to the corresponding log source based on the Agent type (SCF function logs / CLS logs)

API declaration: app.agent.getAgentLogs(params): Promise<any>

Response Structure Description

• SCF Agent: Returns an array of function logs (IFunctionLogDetailRes[])
• TCBR Agent: Returns the CLS log structure (ISearchClsLogResponse, same as app.log.searchClsLog)

2. Input Parameters

Field	Required	Type	Description
AgentId	Yes	String	Agent ID
offset	No	Number	Offset, default 0 (SCF Agent only)
limit	No	Number	Number of returned logs, default 10, maximum 100
startTime	No	String	Start time, format: YYYY-MM-DD HH:mm:ss
endTime	No	String	End time, format: YYYY-MM-DD HH:mm:ss
requestId	No	String	Filter by RequestId (valid for SCF Agent only)

3. Sample Code

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))
}