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-python
3description: "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.21.1
5alwaysApply: true
6metadata:
7 source: https://skillmd.com/skills/ahang1598/cloudbase-agent-python
8---
9
10# CloudBase Agent Python SDK
11
12Build production-ready AI agent backends with multi-framework support, streaming
13protocol, rich tools, persistent memory, and full observability.
14
15> **Note:** This skill is for **Python** projects only.
16
17## When to use this skill
18
19Use this skill for **AI agent development** when you need to:
20
21- Deploy AI agents as HTTP services with AG-UI protocol support
22- Build agent backends using LangGraph, CrewAI, or LlamaIndex frameworks
23- Create custom agent adapters implementing the AbstractAgent interface
24- Understand AG-UI protocol events and message streaming
25- Build production-ready agent servers with FastAPI
26
27**Do NOT use for:**
28- Simple AI model calling without agent capabilities (use `ai-model-*` skills)
29- CloudBase cloud functions (use `cloud-functions` skill)
30- CloudRun backend services without agent features (use `cloudrun-development` skill)
31- TypeScript/JavaScript agent projects (use `cloudbase-agent` skill, refer to the `ts/` sub-directory)
32
33## How to use this skill (for a coding agent)
34
351. **Choose the right adapter**
36 - Use LangGraph adapter for stateful, graph-based workflows
37 - Use CrewAI adapter for multi-agent collaboration patterns
38 - Build custom adapter for specialized agent logic
39
402. **Write agent code** — follow the adapter-specific doc from the Routing table
41
423. **Deploy the agent server** — follow the **blocking deployment pipeline** in [agent-deployment](agent-deployment.md)
43
44## Routing (Execution Order)
45
46> ⚠️ **Deployment is a BLOCKING 4-step pipeline.** Steps marked ✅ BLOCKING
47> must be completed AND verified before proceeding to the next step.
48> Do NOT call `manageAgent` until all blocking steps pass.
49
50| Step | Task | Document | Blocking? |
51|------|------|----------|-----------|
52| 0 | **Choose adapter & write agent code** | See "Adapter Selection" below | — |
53| 1 | **Ensure Python 3.10** | [agent-deployment](agent-deployment.md) § Step 1 | ✅ BLOCKING |
54| 2 | **Build env/ (one-shot)** | [agent-deployment](agent-deployment.md) § Step 2 | ✅ BLOCKING |
55| 3 | **Verify env/ integrity** | [agent-deployment](agent-deployment.md) § Step 3 | ✅ BLOCKING |
56| 4 | **Deploy with manageAgent** | [agent-deployment](agent-deployment.md) § Step 4 | — |
57
58### Adapter Selection (Step 0)
59
60| Framework | Read | Install |
61|-----------|------|---------|
62| LangGraph (stateful graphs) | [adapter-langgraph](adapter-langgraph.md) | `cloudbase-agent-langgraph` |
63| CrewAI (multi-agent crews) | [adapter-development](adapter-development.md) | `cloudbase-agent-crewai` |
64| Coze platform | [adapter-coze](adapter-coze.md) | `cloudbase-agent-coze` |
65| Custom / raw FastAPI | [server-quickstart](server-quickstart.md) + [adapter-development](adapter-development.md) | `cloudbase-agent-server` |
66
67### Additional References (read on demand, NOT required for deployment)
68
69| Task | Read |
70|------|------|
71| Server setup, middleware, multi-agent, CORS | [server-quickstart](server-quickstart.md) |
72| Authentication and user context | [authentication](authentication.md) |
73
74## Quick Start (Framework-Agnostic)
75
76**Prerequisites:** Python >= 3.10 is required.
77
78**1. Install dependencies (pick ONE adapter):**
79
80```bash
81# Option A: LangGraph-based agent
82pip install cloudbase-agent-langgraph
83
84# Option B: CrewAI-based agent
85pip install cloudbase-agent-crewai
86
87# Option C: Custom / minimal
88pip install cloudbase-agent-server
89```
90
91**2. Create server entry point:**
92
93```python
94# server.py — this pattern works with ANY adapter
95import os
96from dotenv import load_dotenv
97load_dotenv()
98
99from cloudbase_agent.server import AgentServiceApp, AgentCreatorResult
100
101# Import your agent (framework-specific, see adapter docs)
102# from agents.chat.agent import create_my_agent
103
104def create_agent() -> AgentCreatorResult:
105 agent = create_my_agent() # Your agent factory
106 return {"agent": agent}
107
108app = AgentServiceApp()
109app.set_cors_config(allow_origins=["*"])
110
111if __name__ == "__main__":
112 port = int(os.environ.get("SCF_RUNTIME_PORT", "9000"))
113 app.run(create_agent, port=port, host="0.0.0.0")
114```
115
116**3. Deploy to CloudBase:**
117
118Follow the **4-step deployment pipeline** in [agent-deployment](agent-deployment.md).
119
120---
121
122## Architecture
123
124```
125Client (React / MiniProgram / curl)
126 │ HTTP POST + SSE streaming
127 ▼
128┌─────────────────────────────────────────────┐
129│ AgentServiceApp (FastAPI) │
130│ ├─ /send-message ← AG-UI SSE │
131│ ├─ /chat/completions ← OpenAI-compat │
132│ └─ Middleware chain (onion model) │
133├─────────────────────────────────────────────┤
134│ Agent Layer │
135│ ├─ LangGraphAgent ├─ CrewAIAgent │
136│ ├─ LlamaIndexAgent ├─ CozeAgent/DifyAgent │
137│ └─ BaseAgent (extend for custom) │
138├──────────────────┬──────────────────────────┤
139│ Tools │ Storage │
140│ Bash/FS/Code/MCP│ Memory + LongTermMemory │
141├─────────────────────────────────────────────┤
142│ Observability (OpenTelemetry + Langfuse) │
143└─────────────────────────────────────────────┘
144```
145
146## Installation
147
148CloudBase 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.*`)**.
149
150```bash
151# Core + Server + LangGraph (most common)
152pip install cloudbase-agent-langgraph
153
154# Individual packages
155pip install cloudbase-agent-core # Core framework
156pip install cloudbase-agent-server # FastAPI server
157pip install cloudbase-agent-langgraph # LangGraph integration
158pip install cloudbase-agent-tools # Tool system
159pip install cloudbase-agent-storage # Memory/Storage
160pip install cloudbase-agent-observability # OpenTelemetry/Langfuse
161pip install cloudbase-agent-coze # Coze platform
162pip install cloudbase-agent-crewai # CrewAI integration
163```
164
165**Import Note**: All packages share the `cloudbase_agent` namespace:
166```python
167# After installing cloudbase-agent-langgraph, import from cloudbase_agent
168from cloudbase_agent.langgraph import LangGraphAgent
169from cloudbase_agent.server import AgentServiceApp
170from cloudbase_agent.tools import create_bash_tool
171```
172
173## Reference Documents
174
175Based on what the user needs, read the corresponding reference document.
176**Only read the relevant reference — don't load all of them.**
177
178| User Need | Reference | What It Covers |
179|-----------|-----------|---------------|
180| **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 |
181| 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 |
182| 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 |
183| 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 |
184| Memory, persistence, short/long-term, MySQL, MongoDB | Read `references/storage.md` | InMemoryMemory, TDAIMemory, MySQLMemory, MongoDBMemory, TDAILongTermMemory, Mem0LongTermMemory, LangGraph checkpoint |
185| Tracing, monitoring, Langfuse, OpenTelemetry | Read `references/observability.md` | ConsoleTraceConfig, OTLPTraceConfig, setup_observability, env vars, manual observation spans |
186| Common patterns, JWT auth, MCP integration, production | Read `references/recipes.md` | JWT middleware, MCP + LangGraph, production deployment, adding tools to agents, client-defined tools |
187
188## Key Imports Quick Reference
189
190```python
191# Server
192from cloudbase_agent.server import AgentServiceApp, AgentCreatorResult
193from cloudbase_agent.server import create_send_message_adapter, create_openai_adapter
194from cloudbase_agent.server import RunAgentInput, OpenAIChatCompletionRequest
195
196# Agents
197from cloudbase_agent.langgraph import LangGraphAgent
198from cloudbase_agent.crewai import CrewAIAgent
199
200# Tools
201from cloudbase_agent.tools import create_bash_tool, create_read_tool, create_write_tool
202from cloudbase_agent.tools import MCPToolkit, CloudBaseMCPServer, CloudBaseTool
203from cloudbase_agent.tools import tool, BaseTool # custom tools
204
205# Storage
206from cloudbase_agent.storage import InMemoryMemory, TDAIMemory
207from cloudbase_agent.storage import TDAILongTermMemory, Mem0LongTermMemory
208from cloudbase_agent.langgraph import TDAICheckpointSaver, TDAIStore
209
210# Observability
211from cloudbase_agent.observability import ConsoleTraceConfig, OTLPTraceConfig, setup_observability
212
213# Schemas
214from cloudbase_agent.schemas import Message, MessageRole, StreamEvent, EventType
215```
216
217## Project Structure Convention
218
219```
220my-agent-project/
221├── agents/
222│ ├── agentic_chat/agent.py # build_workflow() → agent instance
223│ ├── human_in_the_loop/agent.py
224│ └── __init__.py
225├── server.py # Main entry: AgentServiceApp().run(...)
226├── scf_bootstrap # CloudBase startup script (required for deployment)
227├── .env # OPENAI_API_KEY, etc.
228└── requirements.txt
229```
230
231## Environment Variables
232
233| Variable | Purpose |
234|----------|---------|
235| `OPENAI_API_KEY` | OpenAI API key |
236| `AUTO_TRACES_STDOUT` | Enable console tracing (`true`) |
237| `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` | Langfuse keys |
238| `TDAI_ENDPOINT` / `TDAI_API_KEY` | TDAI memory/checkpoint endpoint |
239| `SCF_RUNTIME_PORT` | CloudBase runtime port (set automatically during deployment) |
240
241## Key Design Decisions
242
2431. **Agent Creator Pattern**: Every request creates a fresh agent via factory function. Supports cleanup callbacks for resource release.
2442. **Dual Protocol**: Every agent supports both AG-UI native (SSE + rich events) and OpenAI-compatible (`/chat/completions`).
2453. **Middleware = Generator**: Use `yield` — pre-yield = pre-processing, post-yield = post-processing (onion model).
2464. **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 ...`.
2475. **Observability Auto-Integration**: Install `cloudbase-agent-observability` and tracing works automatically — zero config needed.
2486. **Deploy with manageAgent**: Always use the `manageAgent` MCP tool for CloudBase deployment. Follow the **4-step blocking pipeline** in [agent-deployment](agent-deployment.md).