CloudBase Agent Python SDK
Build production-ready AI agent backends with multi-framework support, streaming
protocol, rich tools, persistent memory, and full observability.
Note: This skill is for Python projects only.
When to use this skill
Use this skill for AI agent development when you need to:
- Deploy AI agents as HTTP services with AG-UI protocol support
- Build agent backends using LangGraph, CrewAI, or LlamaIndex frameworks
- Create custom agent adapters implementing the AbstractAgent interface
- Understand AG-UI protocol events and message streaming
- Build production-ready agent servers with FastAPI
Do NOT use for:
- Simple AI model calling without agent capabilities (use
ai-model-* skills)
- CloudBase cloud functions (use
cloud-functions skill)
- CloudRun backend services without agent features (use
cloudrun-development skill)
- TypeScript/JavaScript agent projects (use
cloudbase-agent skill, refer to the ts/ sub-directory)
How to use this skill (for a coding agent)
Choose the right adapter
- Use LangGraph adapter for stateful, graph-based workflows
- Use CrewAI adapter for multi-agent collaboration patterns
- Build custom adapter for specialized agent logic
Write agent code — follow the adapter-specific doc from the Routing table
Deploy the agent server — follow the blocking deployment pipeline in agent-deployment
Routing (Execution Order)
⚠️ Deployment is a BLOCKING 4-step pipeline. Steps marked ✅ BLOCKING
must be completed AND verified before proceeding to the next step.
Do NOT call manageAgent until all blocking steps pass.
| Step |
Task |
Document |
Blocking? |
| 0 |
Choose adapter & write agent code |
See "Adapter Selection" below |
— |
| 1 |
Ensure Python 3.10 |
agent-deployment § Step 1 |
✅ BLOCKING |
| 2 |
Build env/ (one-shot) |
agent-deployment § Step 2 |
✅ BLOCKING |
| 3 |
Verify env/ integrity |
agent-deployment § Step 3 |
✅ BLOCKING |
| 4 |
Deploy with manageAgent |
agent-deployment § Step 4 |
— |
Adapter Selection (Step 0)
| Framework |
Read |
Install |
| LangGraph (stateful graphs) |
adapter-langgraph |
cloudbase-agent-langgraph |
| CrewAI (multi-agent crews) |
adapter-development |
cloudbase-agent-crewai |
| Coze platform |
adapter-coze |
cloudbase-agent-coze |
| Custom / raw FastAPI |
server-quickstart + adapter-development |
cloudbase-agent-server |
Additional References (read on demand, NOT required for deployment)
| Task |
Read |
| Server setup, middleware, multi-agent, CORS |
server-quickstart |
| Authentication and user context |
authentication |
Quick Start (Framework-Agnostic)
Prerequisites: Python >= 3.10 is required.
1. Install dependencies (pick ONE adapter):
# Option A: LangGraph-based agent
pip install cloudbase-agent-langgraph
# Option B: CrewAI-based agent
pip install cloudbase-agent-crewai
# Option C: Custom / minimal
pip install cloudbase-agent-server
2. Create server entry point:
# server.py — this pattern works with ANY adapter
import os
from dotenv import load_dotenv
load_dotenv()
from cloudbase_agent.server import AgentServiceApp, AgentCreatorResult
# Import your agent (framework-specific, see adapter docs)
# from agents.chat.agent import create_my_agent
def create_agent() -> AgentCreatorResult:
agent = create_my_agent() # Your agent factory
return {"agent": agent}
app = AgentServiceApp()
app.set_cors_config(allow_origins=["*"])
if __name__ == "__main__":
port = int(os.environ.get("SCF_RUNTIME_PORT", "9000"))
app.run(create_agent, port=port, host="0.0.0.0")
3. Deploy to CloudBase:
Follow the 4-step deployment pipeline in agent-deployment.
Architecture
Client (React / MiniProgram / curl)
│ HTTP POST + SSE streaming
▼
┌─────────────────────────────────────────────┐
│ AgentServiceApp (FastAPI) │
│ ├─ /send-message ← AG-UI SSE │
│ ├─ /chat/completions ← OpenAI-compat │
│ └─ Middleware chain (onion model) │
├─────────────────────────────────────────────┤
│ Agent Layer │
│ ├─ LangGraphAgent ├─ CrewAIAgent │
│ ├─ LlamaIndexAgent ├─ CozeAgent/DifyAgent │
│ └─ BaseAgent (extend for custom) │
├──────────────────┬──────────────────────────┤
│ Tools │ Storage │
│ Bash/FS/Code/MCP│ Memory + LongTermMemory │
├─────────────────────────────────────────────┤
│ Observability (OpenTelemetry + Langfuse) │
└─────────────────────────────────────────────┘
Installation
CloudBase Agent Python SDK is published to PyPI as separate packages. Note: PyPI package names use hyphens (cloudbase-agent-*), and Python imports use the same namespace (cloudbase_agent.*).
# Core + Server + LangGraph (most common)
pip install cloudbase-agent-langgraph
# Individual packages
pip install cloudbase-agent-core # Core framework
pip install cloudbase-agent-server # FastAPI server
pip install cloudbase-agent-langgraph # LangGraph integration
pip install cloudbase-agent-tools # Tool system
pip install cloudbase-agent-storage # Memory/Storage
pip install cloudbase-agent-observability # OpenTelemetry/Langfuse
pip install cloudbase-agent-coze # Coze platform
pip install cloudbase-agent-crewai # CrewAI integration
Import Note: All packages share the cloudbase_agent namespace:
# After installing cloudbase-agent-langgraph, import from cloudbase_agent
from cloudbase_agent.langgraph import LangGraphAgent
from cloudbase_agent.server import AgentServiceApp
from cloudbase_agent.tools import create_bash_tool
Reference Documents
Based on what the user needs, read the corresponding reference document.
Only read the relevant reference — don't load all of them.
| User Need |
Reference |
What It Covers |
| Deploying agent to CloudBase |
Read agent-deployment |
manageAgent MCP tool (MUST USE), 4-step blocking pipeline, Python 3.10, env/ build, verification |
| Server setup, deployment, middleware, multi-agent, CORS |
Read references/server.md |
AgentServiceApp 3 deployment methods, middleware (generator/yield/onion model), multi-agent server, Agent Creator pattern, health checks |
| LangGraph agent, callbacks, tool proxy, HITL, checkpoints |
Read adapter-langgraph |
LangGraphAgent constructor, AgentCallback protocol, ToolProxy, human-in-the-loop with interrupt(), TDAICheckpointSaver, client-defined tools |
| Tools: bash, filesystem, code execution, MCP, custom tools |
Read references/tools.md |
create_bash_tool, 8 file tools, code executors, MCPToolkit/CloudBaseMCPServer, @tool decorator, BaseTool, framework adapters |
| Memory, persistence, short/long-term, MySQL, MongoDB |
Read references/storage.md |
InMemoryMemory, TDAIMemory, MySQLMemory, MongoDBMemory, TDAILongTermMemory, Mem0LongTermMemory, LangGraph checkpoint |
| Tracing, monitoring, Langfuse, OpenTelemetry |
Read references/observability.md |
ConsoleTraceConfig, OTLPTraceConfig, setup_observability, env vars, manual observation spans |
| Common patterns, JWT auth, MCP integration, production |
Read references/recipes.md |
JWT middleware, MCP + LangGraph, production deployment, adding tools to agents, client-defined tools |
Key Imports Quick Reference
# Server
from cloudbase_agent.server import AgentServiceApp, AgentCreatorResult
from cloudbase_agent.server import create_send_message_adapter, create_openai_adapter
from cloudbase_agent.server import RunAgentInput, OpenAIChatCompletionRequest
# Agents
from cloudbase_agent.langgraph import LangGraphAgent
from cloudbase_agent.crewai import CrewAIAgent
# Tools
from cloudbase_agent.tools import create_bash_tool, create_read_tool, create_write_tool
from cloudbase_agent.tools import MCPToolkit, CloudBaseMCPServer, CloudBaseTool
from cloudbase_agent.tools import tool, BaseTool # custom tools
# Storage
from cloudbase_agent.storage import InMemoryMemory, TDAIMemory
from cloudbase_agent.storage import TDAILongTermMemory, Mem0LongTermMemory
from cloudbase_agent.langgraph import TDAICheckpointSaver, TDAIStore
# Observability
from cloudbase_agent.observability import ConsoleTraceConfig, OTLPTraceConfig, setup_observability
# Schemas
from cloudbase_agent.schemas import Message, MessageRole, StreamEvent, EventType
Project Structure Convention
my-agent-project/
├── agents/
│ ├── agentic_chat/agent.py # build_workflow() → agent instance
│ ├── human_in_the_loop/agent.py
│ └── __init__.py
├── server.py # Main entry: AgentServiceApp().run(...)
├── scf_bootstrap # CloudBase startup script (required for deployment)
├── .env # OPENAI_API_KEY, etc.
└── requirements.txt
Environment Variables
| Variable |
Purpose |
OPENAI_API_KEY |
OpenAI API key |
AUTO_TRACES_STDOUT |
Enable console tracing (true) |
LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY |
Langfuse keys |
TDAI_ENDPOINT / TDAI_API_KEY |
TDAI memory/checkpoint endpoint |
SCF_RUNTIME_PORT |
CloudBase runtime port (set automatically during deployment) |
Key Design Decisions
- Agent Creator Pattern: Every request creates a fresh agent via factory function. Supports cleanup callbacks for resource release.
- Dual Protocol: Every agent supports both AG-UI native (SSE + rich events) and OpenAI-compatible (
/chat/completions).
- Middleware = Generator: Use
yield — pre-yield = pre-processing, post-yield = post-processing (onion model).
- Namespace Package:
cloudbase_agent spans multiple PyPI packages (cloudbase-agent-core, cloudbase-agent-server, cloudbase-agent-langgraph, etc.). PyPI names use hyphens, but all imports use from cloudbase_agent.xxx import ....
- Observability Auto-Integration: Install
cloudbase-agent-observability and tracing works automatically — zero config needed.
- Deploy with manageAgent: Always use the
manageAgent MCP tool for CloudBase deployment. Follow the 4-step blocking pipeline in agent-deployment.
1---2name: cloudbase-agent-python3description: "Build production-ready AI agent backends using the CloudBase Agent Python SDK — create agents with LangGraph/CrewAI/LlamaIndex, serve them via FastAPI with AG-UI protocol streaming + OpenAI-compatible endpoints, add tools (bash, filesystem, MCP, code execution), memory (in-memory, TDAI, MySQL, MongoDB), observability (OpenTelemetry/Langfuse), and middleware (auth, logging). Use this skill when the user wants to create an AI agent server, build a chatbot backend, set up human-in-the-loop workflows, integrate MCP tools, add agent observability, or deploy an agent API — even if they don't explicitly mention 'CloudBase Agent.'"4version: 2.37.65license: MIT6alwaysApply: true7metadata:8 source: https://skillmd.com/skills/tencentcloudbase/cloudbase-agent-python9---1011# CloudBase Agent Python SDK1213Build production-ready AI agent backends with multi-framework support, streaming14protocol, rich tools, persistent memory, and full observability.1516> **Note:** This skill is for **Python** projects only.1718## When to use this skill1920Use this skill for **AI agent development** when you need to:2122- Deploy AI agents as HTTP services with AG-UI protocol support23- Build agent backends using LangGraph, CrewAI, or LlamaIndex frameworks24- Create custom agent adapters implementing the AbstractAgent interface25- Understand AG-UI protocol events and message streaming26- Build production-ready agent servers with FastAPI2728**Do NOT use for:**29- Simple AI model calling without agent capabilities (use `ai-model-*` skills)30- CloudBase cloud functions (use `cloud-functions` skill)31- CloudRun backend services without agent features (use `cloudrun-development` skill)32- TypeScript/JavaScript agent projects (use `cloudbase-agent` skill, refer to the `ts/` sub-directory)3334## How to use this skill (for a coding agent)35361. **Choose the right adapter**37 - Use LangGraph adapter for stateful, graph-based workflows38 - Use CrewAI adapter for multi-agent collaboration patterns39 - Build custom adapter for specialized agent logic40412. **Write agent code** — follow the adapter-specific doc from the Routing table42433. **Deploy the agent server** — follow the **blocking deployment pipeline** in [agent-deployment](agent-deployment.md)4445## Routing (Execution Order)4647> ⚠️ **Deployment is a BLOCKING 4-step pipeline.** Steps marked ✅ BLOCKING48> must be completed AND verified before proceeding to the next step.49> Do NOT call `manageAgent` until all blocking steps pass.5051| Step | Task | Document | Blocking? |52|------|------|----------|-----------|53| 0 | **Choose adapter & write agent code** | See "Adapter Selection" below | — |54| 1 | **Ensure Python 3.10** | [agent-deployment](agent-deployment.md) § Step 1 | ✅ BLOCKING |55| 2 | **Build env/ (one-shot)** | [agent-deployment](agent-deployment.md) § Step 2 | ✅ BLOCKING |56| 3 | **Verify env/ integrity** | [agent-deployment](agent-deployment.md) § Step 3 | ✅ BLOCKING |57| 4 | **Deploy with manageAgent** | [agent-deployment](agent-deployment.md) § Step 4 | — |5859### Adapter Selection (Step 0)6061| Framework | Read | Install |62|-----------|------|---------|63| LangGraph (stateful graphs) | [adapter-langgraph](adapter-langgraph.md) | `cloudbase-agent-langgraph` |64| CrewAI (multi-agent crews) | [adapter-development](adapter-development.md) | `cloudbase-agent-crewai` |65| Coze platform | [adapter-coze](adapter-coze.md) | `cloudbase-agent-coze` |66| Custom / raw FastAPI | [server-quickstart](server-quickstart.md) + [adapter-development](adapter-development.md) | `cloudbase-agent-server` |6768### Additional References (read on demand, NOT required for deployment)6970| Task | Read |71|------|------|72| Server setup, middleware, multi-agent, CORS | [server-quickstart](server-quickstart.md) |73| Authentication and user context | [authentication](authentication.md) |7475## Quick Start (Framework-Agnostic)7677**Prerequisites:** Python >= 3.10 is required.7879**1. Install dependencies (pick ONE adapter):**8081```bash82# Option A: LangGraph-based agent83pip install cloudbase-agent-langgraph8485# Option B: CrewAI-based agent86pip install cloudbase-agent-crewai8788# Option C: Custom / minimal89pip install cloudbase-agent-server90```9192**2. Create server entry point:**9394```python95# server.py — this pattern works with ANY adapter96import os97from dotenv import load_dotenv98load_dotenv()99100from cloudbase_agent.server import AgentServiceApp, AgentCreatorResult101102# Import your agent (framework-specific, see adapter docs)103# from agents.chat.agent import create_my_agent104105def create_agent() -> AgentCreatorResult:106 agent = create_my_agent() # Your agent factory107 return {"agent": agent}108109app = AgentServiceApp()110app.set_cors_config(allow_origins=["*"])111112if __name__ == "__main__":113 port = int(os.environ.get("SCF_RUNTIME_PORT", "9000"))114 app.run(create_agent, port=port, host="0.0.0.0")115```116117**3. Deploy to CloudBase:**118119Follow the **4-step deployment pipeline** in [agent-deployment](agent-deployment.md).120121---122123## Architecture124125```126Client (React / MiniProgram / curl)127 │ HTTP POST + SSE streaming128 ▼129┌─────────────────────────────────────────────┐130│ AgentServiceApp (FastAPI) │131│ ├─ /send-message ← AG-UI SSE │132│ ├─ /chat/completions ← OpenAI-compat │133│ └─ Middleware chain (onion model) │134├─────────────────────────────────────────────┤135│ Agent Layer │136│ ├─ LangGraphAgent ├─ CrewAIAgent │137│ ├─ LlamaIndexAgent ├─ CozeAgent/DifyAgent │138│ └─ BaseAgent (extend for custom) │139├──────────────────┬──────────────────────────┤140│ Tools │ Storage │141│ Bash/FS/Code/MCP│ Memory + LongTermMemory │142├─────────────────────────────────────────────┤143│ Observability (OpenTelemetry + Langfuse) │144└─────────────────────────────────────────────┘145```146147## Installation148149CloudBase Agent Python SDK is published to PyPI as separate packages. **Note: PyPI package names use hyphens (`cloudbase-agent-*`), and Python imports use the same namespace (`cloudbase_agent.*`)**.150151```bash152# Core + Server + LangGraph (most common)153pip install cloudbase-agent-langgraph154155# Individual packages156pip install cloudbase-agent-core # Core framework157pip install cloudbase-agent-server # FastAPI server158pip install cloudbase-agent-langgraph # LangGraph integration159pip install cloudbase-agent-tools # Tool system160pip install cloudbase-agent-storage # Memory/Storage161pip install cloudbase-agent-observability # OpenTelemetry/Langfuse162pip install cloudbase-agent-coze # Coze platform163pip install cloudbase-agent-crewai # CrewAI integration164```165166**Import Note**: All packages share the `cloudbase_agent` namespace:167```python168# After installing cloudbase-agent-langgraph, import from cloudbase_agent169from cloudbase_agent.langgraph import LangGraphAgent170from cloudbase_agent.server import AgentServiceApp171from cloudbase_agent.tools import create_bash_tool172```173174## Reference Documents175176Based on what the user needs, read the corresponding reference document.177**Only read the relevant reference — don't load all of them.**178179| User Need | Reference | What It Covers |180|-----------|-----------|---------------|181| **Deploying agent to CloudBase** | Read [agent-deployment](agent-deployment.md) | **manageAgent MCP tool (MUST USE)**, 4-step blocking pipeline, Python 3.10, env/ build, verification |182| Server setup, deployment, middleware, multi-agent, CORS | Read `references/server.md` | AgentServiceApp 3 deployment methods, middleware (generator/yield/onion model), multi-agent server, Agent Creator pattern, health checks |183| LangGraph agent, callbacks, tool proxy, HITL, checkpoints | Read [adapter-langgraph](adapter-langgraph.md) | LangGraphAgent constructor, AgentCallback protocol, ToolProxy, human-in-the-loop with interrupt(), TDAICheckpointSaver, client-defined tools |184| Tools: bash, filesystem, code execution, MCP, custom tools | Read `references/tools.md` | create_bash_tool, 8 file tools, code executors, MCPToolkit/CloudBaseMCPServer, @tool decorator, BaseTool, framework adapters |185| Memory, persistence, short/long-term, MySQL, MongoDB | Read `references/storage.md` | InMemoryMemory, TDAIMemory, MySQLMemory, MongoDBMemory, TDAILongTermMemory, Mem0LongTermMemory, LangGraph checkpoint |186| Tracing, monitoring, Langfuse, OpenTelemetry | Read `references/observability.md` | ConsoleTraceConfig, OTLPTraceConfig, setup_observability, env vars, manual observation spans |187| Common patterns, JWT auth, MCP integration, production | Read `references/recipes.md` | JWT middleware, MCP + LangGraph, production deployment, adding tools to agents, client-defined tools |188189## Key Imports Quick Reference190191```python192# Server193from cloudbase_agent.server import AgentServiceApp, AgentCreatorResult194from cloudbase_agent.server import create_send_message_adapter, create_openai_adapter195from cloudbase_agent.server import RunAgentInput, OpenAIChatCompletionRequest196197# Agents198from cloudbase_agent.langgraph import LangGraphAgent199from cloudbase_agent.crewai import CrewAIAgent200201# Tools202from cloudbase_agent.tools import create_bash_tool, create_read_tool, create_write_tool203from cloudbase_agent.tools import MCPToolkit, CloudBaseMCPServer, CloudBaseTool204from cloudbase_agent.tools import tool, BaseTool # custom tools205206# Storage207from cloudbase_agent.storage import InMemoryMemory, TDAIMemory208from cloudbase_agent.storage import TDAILongTermMemory, Mem0LongTermMemory209from cloudbase_agent.langgraph import TDAICheckpointSaver, TDAIStore210211# Observability212from cloudbase_agent.observability import ConsoleTraceConfig, OTLPTraceConfig, setup_observability213214# Schemas215from cloudbase_agent.schemas import Message, MessageRole, StreamEvent, EventType216```217218## Project Structure Convention219220```221my-agent-project/222├── agents/223│ ├── agentic_chat/agent.py # build_workflow() → agent instance224│ ├── human_in_the_loop/agent.py225│ └── __init__.py226├── server.py # Main entry: AgentServiceApp().run(...)227├── scf_bootstrap # CloudBase startup script (required for deployment)228├── .env # OPENAI_API_KEY, etc.229└── requirements.txt230```231232## Environment Variables233234| Variable | Purpose |235|----------|---------|236| `OPENAI_API_KEY` | OpenAI API key |237| `AUTO_TRACES_STDOUT` | Enable console tracing (`true`) |238| `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` | Langfuse keys |239| `TDAI_ENDPOINT` / `TDAI_API_KEY` | TDAI memory/checkpoint endpoint |240| `SCF_RUNTIME_PORT` | CloudBase runtime port (set automatically during deployment) |241242## Key Design Decisions2432441. **Agent Creator Pattern**: Every request creates a fresh agent via factory function. Supports cleanup callbacks for resource release.2452. **Dual Protocol**: Every agent supports both AG-UI native (SSE + rich events) and OpenAI-compatible (`/chat/completions`).2463. **Middleware = Generator**: Use `yield` — pre-yield = pre-processing, post-yield = post-processing (onion model).2474. **Namespace Package**: `cloudbase_agent` spans multiple PyPI packages (cloudbase-agent-core, cloudbase-agent-server, cloudbase-agent-langgraph, etc.). PyPI names use hyphens, but all imports use `from cloudbase_agent.xxx import ...`.2485. **Observability Auto-Integration**: Install `cloudbase-agent-observability` and tracing works automatically — zero config needed.2496. **Deploy with manageAgent**: Always use the `manageAgent` MCP tool for CloudBase deployment. Follow the **4-step blocking pipeline** in [agent-deployment](agent-deployment.md).