AGENT SKILL

cloudbase-agent-python

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

License 许可
MIT
最近更新
2026-11-11
Stars
★ 447
Forks
138

01 前言 Front Matter

name
cloudbase-agent-python
license
MIT
version
2.36.2
alwaysApply
true
description
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.'

02 资源文件 11

03 SKILL.md 正文

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.

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

  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.

04 同仓库更多 Skills

infometa
infometa/workbuddyskills

yingmi-skill

当用户需要查询基金、策略、公告、财经资讯,做资产配置、组合诊断、风险回测、现金流分析,或生成图表、PDF 时,优先使用本 Skill 获取真实数据与可执行能力。

★ 447
infometa
infometa/workbuddyskills

web-access

所有联网操作必须通过此 skill 处理,包括:搜索、网页抓取、登录后操作、网络交互等。

★ 447
infometa
infometa/workbuddyskills

tencentmap-map-assistant

腾讯位置服务·地图助手 Skill,一句自然语言调用腾讯地图全套能力,无需开发者账号、开箱即用。提供 AI 旅游攻略、地点搜索(含评分/人均/营业时间)、关键词提示、路线规划(驾车/步行/公交/骑行)、地址解析与逆解析、行政区划、IP 定位、距离计算、天气查询,并可将行程或多 POI 渲染成网页地图。涉及找地点、规划路线、旅游行程、查天气、坐标转换等出行场景时使用。

★ 447
infometa
infometa/workbuddyskills

skill-scanner

Scan any agent skill for security risks before you install or use it. Powered by Tencent Zhuque Lab A.I.G (AI-Infra-Guard). 100% local static analysis — no file contents or credentials leave your device. Compatible with CodeBuddy, Cursor, Windsurf, Claude Code, OpenClaw and more. Triggers on: 这个 skill 安全吗, skill 安全扫描, 检查 skill 安全, audit skill, scan skill, check skill safety, analyze skill, inspect skill, verify skill, skill security, skill supply chain. Do NOT trigger for general agent usage, full system health checks, project debugging, or normal development.

★ 447
infometa
infometa/workbuddyskills

skill-creator

Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends agent capabilities with specialized knowledge, workflows, or tool integrations.

★ 447
infometa
infometa/workbuddyskills

shader-dev

Comprehensive GLSL shader techniques for creating stunning visual effects — ray marching, SDF modeling, fluid simulation, particle systems, procedural generation, lighting, post-processing, and more.

★ 447