AgentOS (CloudAgent) 试用指引

AgentOS 是 CodeBuddy 的核心 Agentic 能力 + 企业级云端沙箱运行时环境，为第三方应用提供通过 API 创建和管理 AI Agent 沙箱的能力。本仓库提供开箱即用的试用脚本和文档，帮助企业客户在 30 分钟内跑通完整流程。

快速开始


# 1. 安装依赖（仅需 requests）
pip install requests

# 2. 配置 API Key
export E2E_API_KEY="ck_xxx.yyy"

# 3. 运行基础验证（8 步全流程）
python3 demo_1_full_flow.py

# 4. 运行全部 7 个场景
python3 run_all.py

# 5. 只运行指定场景
python3 run_all.py 1 2 4

项目结构


AgentOS-试用指引/
├── lib/                              # 公共库（所有 Demo 复用）
│   ├── __init__.py
│   ├── logger.py                     # 彩色终端输出
│   ├── utils.py                      # JSON 解析、配置读取、Manifest 工具
│   ├── client.py                     # RuntimeClient — Runtime/envd/Session/Version/Checkpoint/Artifact API
│   ├── acp.py                        # ACPSession — SSE + ACP 协议通信
│   └── manifest.py                   # ManifestBuilder — 链式 Manifest 构建
│
├── demo_1_full_flow.py               # 场景一：基础全流程（8 步）
├── demo_2_manifest.py                # 场景二：Manifest 配置注入 + envd 文件操作
├── demo_3_version_checkpoint.py      # 场景三：Version & Checkpoint 快照管理（12 接口）
├── demo_4_session_acp.py           # 场景四：Session 管理 + ACP 扩展方法
├── demo_5_webhook.py                 # 场景五：Webhook 事件回调
├── demo_6_artifact_release.py        # 场景六：Artifact Release 产物发布
├── demo_7_advanced_runtime.py        # 场景七：Runtime 高级操作（Fork/模板/规格/SSE重连）
│
├── run_all.py                        # 一键运行全部场景 + 汇总报告
├── fixtures/
│   └── manifest-full.json            # 完整 AgentManifest 样本（27 个 skills）
│
├── AgentOS-测试验证方案.md            # 完整测试验证方案文档 (v2.0)
├── api-reference.md                  # 接口参考文档
└── 验证报告-2026-04-04.md            # 历史验证报告

7 个验证场景

#	场景	脚本	验证能力
1	基础全流程	`demo_1_full_flow.py`	Runtime 创建/查询/删除、SSE 连接、ACP 握手、Agent 对话
2	Manifest 配置注入	`demo_2_manifest.py`	rules/skills/mcp/secrets/envs 注入、envd 文件操作
3	快照管理	`demo_3_version_checkpoint.py`	Version × 6 接口 + Checkpoint × 6 接口 = 12 个接口
4	Session 管理 + ACP	`demo_4_session_acp.py`	Session 幂等性、断线重连、session/load 上下文恢复、set_model、cancel
5	Webhook 回调	`demo_5_webhook.py`	HMAC-SHA256 签名、13 种事件类型、本地服务器
6	产物发布	`demo_6_artifact_release.py`	Static/Web 发布、域名验证、取消发布
7	高级运维	`demo_7_advanced_runtime.py`	Runtime Fork、sandboxSpec、SSE 重连

使用示例


# 场景一：基础全流程
python3 demo_1_full_flow.py --prompt "帮我写一个 Hello World"

# 场景二：使用完整 manifest 注入 27 个 skills
python3 demo_2_manifest.py --manifest-file fixtures/manifest-full.json

# 场景二：写入文件到沙箱
python3 demo_2_manifest.py --write-text "/home/user/hello.txt:Hello World"

# 场景三：快照管理验证
python3 demo_3_version_checkpoint.py

# 场景四：Session 管理 + ACP 扩展方法
python3 demo_4_session_acp.py

# 场景五：Webhook 模拟模式
python3 demo_5_webhook.py

# 场景五：Webhook 真实模式（需 ngrok）
python3 demo_5_webhook.py --webhook-url https://xxxx.ngrok.io/webhook

# 场景六：产物发布
python3 demo_6_artifact_release.py

# 场景七：高级运维
python3 demo_7_advanced_runtime.py

# 所有脚本都支持 --no-cleanup 保留沙箱调试
python3 demo_1_full_flow.py --no-cleanup

常见问题

问题	排查方向
`session/new` 拿不到 sessionId	确认 SSE → Initialize → Session/New 顺序正确
SSE 连接失败	确认 `acpUrl` 使用 `https://`，检查网络代理
沙箱一直 CREATING	正常需 30~90s，最长 180s
HTTP 401	检查 API Key 格式和有效性
Manifest 配置未生效	确认 `downloadUrl` 可公网访问