cloudbase-agent-python

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)

1. 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

2. Write agent code — follow the adapter-specific doc from the Routing table

3. 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.

Adapter Selection (Step 0)

Additional References (read on demand, NOT required for deployment)

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.

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

Key Design Decisions

1. Agent Creator Pattern: Every request creates a fresh agent via factory function. Supports cleanup callbacks for resource release.
2. Dual Protocol: Every agent supports both AG-UI native (SSE + rich events) and OpenAI-compatible (/chat/completions).
3. Middleware = Generator: Use yield — pre-yield = pre-processing, post-yield = post-processing (onion model).
4. 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 ....
5. Observability Auto-Integration: Install cloudbase-agent-observability and tracing works automatically — zero config needed.
6. Deploy with manageAgent: Always use the manageAgent MCP tool for CloudBase deployment. Follow the 4-step blocking pipeline in agent-deployment.