Deploying with CloudBase Run

CloudBase Run is the recommended way to deploy Agents. It supports persistent connections, custom runtimes, and elastic scaling, making it ideal for complex Agents and high-concurrency scenarios.

Prerequisites

• A CloudBase environment has been activated
• Python 3.9+ is installed
• Agent development is complete
• CloudBase CLI is installed (optional, for CLI-based deployment)

Code Examples

JavaScript (LangChain)

Project Structure

my-agent/
├── index.js          # Entry file
├── package.json      # Dependency configuration
└── Dockerfile        # Container configuration

Entry File

// index.js
const { LangchainAgent, createAgentServer } = require("@cloudbase/agent-adapter-langchain");
const { createReactAgent } = require("@langchain/langgraph/prebuilt");
const { ChatOpenAI } = require("@langchain/openai");
const { tool } = require("@langchain/core/tools");
const { z } = require("zod");

// Define tools (optional)
const searchTool = tool(
  async ({ query }) => {
    return `Search results: relevant information about "${query}"...`;
  },
  {
    name: "search",
    description: "Search for information",
    schema: z.object({
      query: z.string().describe("Search keyword"),
    }),
  }
);

// Create the model
const model = new ChatOpenAI({
  model: process.env.TCB_AI_MODEL || "hunyuan-turbos-latest",
  apiKey: process.env.TCB_API_KEY,
  configuration: {
    baseURL: `https://${process.env.TCB_ENV_ID}.api.tcloudbasegateway.com/v1/ai/hunyuan/v1`,
  },
});

// Create a ReAct Agent
const reactAgent = createReactAgent({
  llm: model,
  tools: [searchTool],
});

// Wrap as a CloudBase Agent
const agent = new LangchainAgent({
  name: "SearchAgent",
  description: "Intelligent search assistant",
  agent: reactAgent,
});

// Export the server
module.exports = createAgentServer(agent);

Dependency Configuration

{
  "name": "my-agent",
  "main": "index.js",
  "dependencies": {
    "@cloudbase/agent-adapter-langchain": "latest",
    "@cloudbase/agent-server": "latest",
    "@langchain/langgraph": "latest",
    "@langchain/openai": "latest",
    "@langchain/core": "latest",
    "zod": "^3.22.0"
  }
}

Dockerfile

FROM node:18-slim

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm install --production

# Copy source code
COPY . .

# Set environment variables
ENV PORT=3000
EXPOSE 3000

# Start command
CMD ["node", "index.js"]

Python (CrewAI)

Project Structure

my-agent/
├── main.py           # Entry file
├── requirements.txt  # Dependency configuration
└── Dockerfile        # Container configuration

Entry File

# main.py
from cloudbase_agent.crewai import CrewAIAgent
from cloudbase_agent.server import create_agent_server
from crewai import Agent, Task, Crew
import os

# Create Agent
researcher = Agent(
    role="Researcher",
    goal="Conduct in-depth research on a given topic",
    backstory="You are an experienced researcher.",
    verbose=True,
)

research_task = Task(
    description="Research the latest developments in {topic}",
    expected_output="Research report",
    agent=researcher,
)

crew = Crew(
    agents=[researcher],
    tasks=[research_task],
    verbose=True,
)

agent = CrewAIAgent(
    name="ResearchAgent",
    description="Research assistant",
    crew=crew,
)

app = create_agent_server(agent)

if __name__ == "__main__":
    import uvicorn
    port = int(os.environ.get("PORT", 3000))
    uvicorn.run(app, host="0.0.0.0", port=port)

Dependency Configuration

# requirements.txt
cloudbase-agent-crewai
cloudbase-agent-server
crewai
crewai-tools
uvicorn
langchain-openai

Dockerfile

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt ./
RUN pip install -r requirements.txt --no-cache-dir

# Copy source code
COPY . .

# Set environment variables
ENV PORT=3000
EXPOSE 3000

# Start command
CMD ["python", "main.py"]

Deployment Methods

Method 1: Console Deployment

1. Go to the CloudBase Console
2. Select CloudBase Run → Create Service
3. Choose Local Code as the upload method
4. Upload the project code package (including the Dockerfile)
5. Configure service parameters:
   • Service Name: A custom name, e.g., my-agent
   • Access Type: Select WEB (public network access)
   • CPU: Choose based on your needs; 0.5–2 cores recommended
   • Memory: CPU × 2, e.g., 0.5 cores → 1 GB
   • Minimum Instances: Set to 0 for development, 1 for production
   • Maximum Instances: Set based on concurrency needs; 5–20 recommended
6. Click Confirm to start deployment

Method 2: CLI Deployment

Use the CloudBase CLI to quickly deploy a CloudBase Run service:

# Install CLI (if not already installed)
npm install -g @cloudbase/cli

# Log in to CloudBase
tcb login

# Run deployment from the project directory
tcb cloudrun deploy

The CLI will automatically detect the Dockerfile in your project, build the image, and deploy it to CloudBase Run. During the process, you will be prompted to provide:

• Environment ID
• Service name
• Access type and other configuration

Configuration Reference

Resource Configuration

Parameter	Description	Recommended Value
CPU	Number of CPU cores	0.5–2
Memory	Memory size	CPU × 2
Minimum Instances	Minimum running instances	0 (on-demand) or 1 (avoid cold starts)
Maximum Instances	Maximum running instances	5–20

tip

Resource constraint: Memory = 2 × CPU. For example, 0.5 vCPU corresponds to 1 GB of memory.

Access Configuration

Access Type	Description	Use Case
WEB	Public network access	Web applications
VPC	VPC private network access	Inter-service calls
PRIVATE	Mini Program private direct connection	Mini Programs

Environment Variables

Set environment variables in the console under Service Configuration:

Variable	Description
TCB_ENV_ID	CloudBase environment ID
TCB_API_KEY	API key
TCB_AI_MODEL	Large model name, e.g., hunyuan-turbos-latest

tip

CloudBase has built-in support for Tencent Hunyuan and DeepSeek large models — no external API key required. For the list of supported models, refer to the Model Configuration Guide.

Local Debugging

Before deploying, it is recommended to develop and debug locally. For detailed guidance, refer to:

👉 Local Development Guide

The local development guide covers:

• Getting the project code (GitHub template / syncing from an online service)
• Installing dependencies and configuring environment variables
• Starting the local service (including Docker)
• Debugging with cURL or a proxy
• Troubleshooting common issues

Monitoring & Operations

Viewing Logs

View service logs through the CloudBase console:

1. Go to CloudBase Run → select the corresponding service
2. Click Logs to view runtime logs

Performance Monitoring

Monitoring metrics:

• Request volume
• Response time
• Error rate
• CPU/memory utilization

Elastic Scaling

CloudBase Run supports automatic scaling:

• Auto scale-out based on request volume
• Auto scale-in to 0 when idle
• Configurable minimum/maximum instance counts

Best Practices

1. Resource Configuration

   • Configure CPU/memory based on Agent complexity
   • Set minimum instances ≥ 1 in production to avoid cold starts

2. Access Control

   • Use PRIVATE private direct connection for Mini Programs
   • Use WEB + SDK authentication for web applications

3. Environment Isolation

   • Use separate environments for development, testing, and production
   • Configure sensitive information via environment variables

4. Image Optimization

   • Use lightweight base images
   • Use multi-stage builds to reduce image size
   • Optimize dependencies to reduce cold start time

Related Documentation

• HTTP Cloud Function Deployment
• LangChain Development Guide
• CrewAI Development Guide