5. Core Workflow (Understand Steps First, Then Examples)
Choose mode
Need multi-language/existing container/Docker: choose "Container mode"
Need long connection/streaming/low latency/multiple functions coexisting: prioritize "Function mode"
Initialize local project
General: Use template
init
(both Function mode and Container mode can start from templates)
Container mode must "check or generate Dockerfile":
Node.js minimal example:
FROM
node:18-alpine
WORKDIR
/app
COPY
package*.json ./
RUN
npm ci --omit=dev
COPY
. .
ENV
NODE_ENV=production
EXPOSE
3000
CMD
[
"node"
,
"server.js"
]
Python minimal example:
FROM
python:3.11-slim
WORKDIR
/app
COPY
requirements.txt ./
RUN
pip install -r requirements.txt --no-cache-dir
COPY
. .
ENV
PORT=3000
EXPOSE
3000
CMD
[
"python"
,
"app.py"
]
Local running
(Function mode only)
Automatically use
npm run dev/start
or entry file via
run
Configure access
Set
OpenAccessTypes
(WEB/VPC/PRIVATE) as needed; configure security domain and authentication for Web scenarios
Deploy
Specify CPU/Mem/instance count/environment variables, etc. during
deploy
Verify
Use
detail
to confirm access address and configuration meet expectations
Example Tool Calls
View templates/services
{
"name"
:
"queryCloudRun"
,
"arguments"
:
{
"action"
:
"templates"
}
}
{
"name"
:
"queryCloudRun"
,
"arguments"
:
{
"action"
:
"detail"
,
"detailServerName"
:
"my-svc"
}
}
Initialize project
{
"name"
:
"manageCloudRun"
,
"arguments"
:
{
"action"
:
"init"
,
"serverName"
:
"my-svc"
,
"targetPath"
:
"/abs/ws/my-svc"
,
"template"
:
"helloworld"
}
}
Download code
(optional)
{
"name"
:
"manageCloudRun"
,
"arguments"
:
{
"action"
:
"download"
,
"serverName"
:
"my-svc"
,
"targetPath"
:
"/abs/ws/my-svc"
}
}
Local running
(Function mode only)
{
"name"
:
"manageCloudRun"
,
"arguments"
:
{
"action"
:
"run"
,
"serverName"
:
"my-svc"
,
"targetPath"
:
"/abs/ws/my-svc"
,
"runOptions"
:
{
"port"
:
3000
}
}
}
Deploy
{
"name"
:
"manageCloudRun"
,
"arguments"
:
{
"action"
:
"deploy"
,
"serverName"
:
"my-svc"
,
"targetPath"
:
"/abs/ws/my-svc"
,
"serverConfig"
:
{
"OpenAccessTypes"
:
[
"WEB"
]
,
"Cpu"
:
0.5
,
"Mem"
:
1
,
"MinNum"
:
0
,
"MaxNum"
:
5
}
}
}
Create AI agent
(optional)
{
"name"
:
"manageCloudRun"
,
"arguments"
:
{
"action"
:
"createAgent"
,
"serverName"
:
"my-agent"
,
"targetPath"
:
"/abs/ws/agents"
,
"agentConfig"
:
{
"agentName"
:
"MyAgent"
,
"botTag"
:
"demo"
,
"description"
:
"My agent"
,
"template"
:
"blank"
}
}
}
Run agent
(optional)
{
"name"
:
"manageCloudRun"
,
"arguments"
:
{
"action"
:
"run"
,
"serverName"
:
"my-agent"
,
"targetPath"
:
"/abs/ws/agents/my-agent"
,
"runOptions"
:
{
"port"
:
3000
,
"runMode"
:
"agent"
}
}
}
6. Best Practices (Strongly Recommended)
Prioritize PRIVATE/VPC or mini-program internal
callContainer
, reduce public network exposure
Web must use CloudBase Web SDK authentication; mini-programs authenticated by platform
Secrets via environment variables; separate configuration for multiple environments (dev/stg/prod)
Use
queryCloudRun.detail
to verify configuration and accessibility before and after deployment
Image layers reusable, small volume; monitor startup latency and memory usage
Agent development: Use
@cloudbase/aiagent-framework
, supports SSE streaming responses, BotId format is
ibot-{name}-{tag}
7. Quick Troubleshooting
Access failure
Check OpenAccessTypes/domain/port, whether instance scaled down to 0
Deployment failure
Verify Dockerfile/build logs/image volume and CPU/Mem ratio
Local running failure
Only Function mode supported; requires
package.json
dev
/
start
or entry
index.js|app.js|server.js
Performance jitter
Reduce dependencies and initialization; appropriately increase MinNum; optimize cold start
Agent running failure
Check
@cloudbase/aiagent-framework
dependency, BotId format, SSE response format
8. Function Mode CloudRun (Function Mode) Key Points (Concise)
Definition
CloudRun + function framework (
@cloudbase/functions-framework
) + function code, making container service development as simple as writing cloud functions
When to choose
Need WebSocket/SSE/file upload/streaming responses; need long tasks or connect to DB/message queue; need multiple functions per instance and shared memory, low latency and better logs/debugging
Agent mode
Develop AI agents based on Function mode CloudRun, use
@cloudbase/aiagent-framework
, supports SSE streaming responses and personalized AI applications
Tool support
Local running only supports Function mode (
manageCloudRun
→
run
); deploy using
manageCloudRun
→
deploy
; query using
queryCloudRun
Migration tips
Different from cloud function call chain/runtime, migration requires minor modifications (including client calling methods)
Portability
Based on function framework, can run locally/host/Docker, non-CloudRun requires self-managed build and deployment
9. Service Invocation Methods (Concise Examples)
HTTP Direct Access (when WEB public network enabled)
curl
-L
"https://"
WeChat Mini Program (internal direct connection, recommend closing public network)
// app.js (ensure wx.cloud.init() is called)
const
res
=
await
wx
.
cloud
.
callContainer
(
{
config
:
{
env
:
""
}
,
path
:
"/"
,
method
:
"GET"
,
header
:
{
"X-WX-SERVICE"
:
""
}
}
)
;
Web (JS SDK, need to configure security domain and authentication)
import
cloudbase
from
"@cloudbase/js-sdk"
;
const
app
=
cloudbase
.
init
(
{
env
:
""
}
)
;
// Collect user's phone number into variable phoneNum by providing a input UI
const
auth
=
app
.
auth
(
)
;
// Send SMS code
const
verificationInfo
=
await
auth
.
getVerification
(
{
phone_number
:
+86
${
phoneNum
}
,
}
)
;
// Collect user's phone number into variable verificationCode by providing a input UI
// Sign in
await
auth
.
signInWithSms
(
{
verificationInfo
,
verificationCode
,
phoneNum
,
}
)
;
const
res
=
await
app
.
callContainer
(
{
name
:
""
,
method
:
"POST"
,
path
:
"/api"
,
header
:
{
"Content-Type"
:
"application/json"
}
,
data
:
{
key
:
"value"
}
}
)
;
// Web JS SDK initialization MUST be synchronous:
// - Always use top-level
import cloudbase from "@cloudbase/js-sdk";
// - Do NOT use dynamic imports like
import("@cloudbase/js-sdk")
or async wrappers such as
initCloudBase()
with internal
initPromise
Node.js (server-side/cloud function internal call)
import
tcb
from
"@cloudbase/node-sdk"
;
const
app
=
tcb
.
init
(
{
}
)
;
const
res
=
await
app
.
callContainer
(
{
name
:
""
,
method
:
"GET"
,
path
:
"/health"
,
timeout
:
5000
}
)
;
Recommendations
Mini Program/Server side prioritize internal network (VPC/PRIVATE) calls, reduce exposure surface
Web scenarios need to enable WEB, public domain and security domain, and use SDK authentication