A best-practice reference for building useful products with Qoder Cloud Agents (QCA).
一个展示如何基于 Qoder Cloud Agents（QCA）快速搭建可用产品的最佳实践项目。
Operra is the reference application in this repository: an OPC workspace built as a thin product layer on top of QCA. The point of this project is not to introduce another agent runtime. It is to show how QCA's sessions, cloud execution, GitHub collaboration, event stream, and deployments can be assembled into a complete product experience.
Qoder Cloud Agents already provides the difficult execution layer:
- persistent agent sessions;
- managed cloud sandboxes;
- native collaboration with GitHub repositories;
- streaming execution events and human-in-the-loop interactions;
- deployments for work that should run in the cloud without keeping a local process alive.
Operra demonstrates the product layer that can be built around those capabilities:
- turn a user's goal into a durable Task;
- translate QCA events into readable plans, activity, review requests, and outcomes;
- make files and artifacts the primary deliverables;
- reconnect to an existing QCA session after a restart or network interruption;
- use a second QCA agent as a conversational workspace operator through custom tools;
- keep credentials, local state, and approval boundaries explicit.
The result is a working OPC workspace, but the patterns are reusable for research tools, content workflows, internal operations, customer-support workbenches, and other agent products.
flowchart LR
U["User"] --> UI["Operra product UI"]
UI --> O["Oopz · QCA workspace operator"]
O --> CT["Operra custom tools"]
CT --> T["Projects, Tasks & Schedules"]
T --> A["Task QCA session / deployment"]
A <--> G["User GitHub repository"]
A --> E["Streamed events & artifacts"]
E --> UI
Each Task is backed by a QCA session or deployment. QCA works in the connected GitHub repository, streams its progress, requests input when needed, and leaves deliverables in a durable, versioned workspace.
Oopz is another QCA-powered agent. Instead of directly doing project work, it calls a small set of Operra custom tools to create projects, start Tasks, inspect status, and manage resources. This keeps the product conversation natural without putting business state inside a prompt.
Operra does not build its own agent loop, sandbox, model router, or local coding runtime. The QCA adapter stays narrow; the rest of the code focuses on product concerns:
| Concern | Reference implementation |
|---|---|
| QCA session, SSE, follow-up, interruption | app/engine/qca.py |
| QCA endpoint and region handling | app/engine/qca_endpoint.py |
| QCA deployments and provisioning | app/engine/qca_provision.py |
| Task state and normalized events | app/domain/, app/services/task_service.py |
| Dispatch, reconnect, repository sync | app/dispatch/, app/engine/resilience.py |
| QCA-powered workspace operator | app/operator/cloud_xiaoO.py |
| Custom-tool registry | app/api/server.py |
| Product UI and streamed experience | app/api/static/ |
See QCA runtime and Architecture for the complete boundary.
Requirements:
- Python 3.11 or newer
- A QCA run token from Qoder integrations
- A GitHub account; use a fine-grained personal access token in Settings, or configure your own OAuth app
macOS / Linux:
git clone https://github.com/QoderAI/oder-cloud-agents-opc.git
cd oder-cloud-agents-opc
./start.shWindows PowerShell:
git clone https://github.com/QoderAI/oder-cloud-agents-opc.git
cd oder-cloud-agents-opc
.\start.ps1Open http://127.0.0.1:8848, add your QCA token and GitHub connection, create a project, and start a Task. The launcher creates an isolated .venv; workspace data is stored outside the repository in ~/Operra or %USERPROFILE%\Operra.
Optional:
OPERRA_HOME=/path/to/workspace PORT=9000 ./start.shSet OPERRA_GITHUB_CLIENT_ID only if you operate your own GitHub OAuth App. A fine-grained GitHub token can always be entered in Settings.
- Let QCA own execution. Keep your adapter focused on authentication, sessions, event streaming, follow-ups, and deployments.
- Define a product-level Task. Do not expose transport payloads or agent internals as the user's primary mental model.
- Use a repository as durable context. Let QCA work with real files, version history, and artifacts.
- Normalize events before rendering them. Translate the QCA stream into product concepts such as plan, activity, review, failure, and outcome.
- Design for reconnect and replay. A local process restart should reconnect to the same cloud work instead of starting it again.
- Keep consequential actions reviewable. Human approval belongs in the product workflow.
- Make artifacts first-class. A useful product delivers files and outcomes, not only a transcript.
- Use QCA custom tools for the control plane. A conversational operator can manage real application state without hiding that state in model context.
python3.11 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
python -m pytest -q
python scripts/e2e_ui.pyThe default suite uses fixtures and does not require a live QCA token.
Operra is a reference implementation rather than an official QCA SDK. QCA API behavior and authentication should follow the current Qoder documentation. Contributions that make the QCA integration patterns clearer, safer, or easier to reuse are especially welcome. See CONTRIBUTING.md, SECURITY.md, and PRIVACY.md.
Apache License 2.0. See LICENSE.
Qoder Cloud Agents 已经提供了搭建 Agent 产品最困难的执行层：
- 可持续的 Agent Session；
- 托管的云端沙箱；
- 与 GitHub 仓库的原生协作；
- 流式执行事件与 Human-in-the-loop 交互；
- 无需本地进程常驻的云端 Deployment。
Operra 是这套能力之上的一个参考应用。它用很薄的产品层展示如何：
- 把用户目标组织成可持续的 Task；
- 将 QCA 事件翻译为人能理解的计划、活动、审核请求和结果；
- 把文件与 Artifact 作为首要交付物；
- 在应用重启或网络中断后接回原有 QCA Session；
- 让另一个 QCA Agent 通过 custom tools 成为工作台的对话式运营入口；
- 明确处理凭证、本地状态与人工审批边界。
最终得到的是一个面向 OPC 的可用工作台，但这些模式同样适用于研究工具、内容工作流、内部运营、客户支持工作台和其他 Agent 产品。
每个 Task 对应一个 QCA Session 或 Deployment。QCA 在用户连接的 GitHub 仓库中工作，持续回传进展，在需要时请求输入，并把交付物留在可版本化、可持续使用的真实工作空间里。
Oopz 本身也是一个由 QCA 驱动的 Agent。它不直接完成项目任务，而是调用一组小而明确的 Operra custom tools，负责创建项目、启动 Task、查询状态和管理资源。这样既能保持自然对话，又不会把业务状态藏进 prompt。
Operra 不自研 Agent loop、沙箱、模型路由或本地 Coding Runtime。QCA adapter 保持狭窄，其余代码集中解决产品层问题：
| 关注点 | 参考实现 |
|---|---|
| QCA Session、SSE、追问与中断 | app/engine/qca.py |
| QCA Endpoint 与区域处理 | app/engine/qca_endpoint.py |
| QCA Deployment 与资源准备 | app/engine/qca_provision.py |
| Task 状态与事件归一化 | app/domain/、app/services/task_service.py |
| 派发、断线恢复与仓库同步 | app/dispatch/、app/engine/resilience.py |
| QCA 驱动的工作台运营入口 | app/operator/cloud_xiaoO.py |
| Custom-tool 注册表 | app/api/server.py |
| 产品界面与流式体验 | app/api/static/ |
你需要：
- Python 3.11 或更高版本
- 从 Qoder integrations 获取 QCA run token
- GitHub 账号；可在设置中使用 fine-grained personal access token，或配置自己的 OAuth App
macOS / Linux：
git clone https://github.com/QoderAI/oder-cloud-agents-opc.git
cd oder-cloud-agents-opc
./start.shWindows PowerShell：
git clone https://github.com/QoderAI/oder-cloud-agents-opc.git
cd oder-cloud-agents-opc
.\start.ps1打开 http://127.0.0.1:8848，填写 QCA token、连接 GitHub、创建项目并启动一个 Task。启动脚本会创建隔离的 .venv；工作区数据位于源码仓库之外的 ~/Operra 或 %USERPROFILE%\Operra。
需要自定义工作区或端口时：
OPERRA_HOME=/path/to/workspace PORT=9000 ./start.sh只有在你运营自己的 GitHub OAuth App 时才需要设置 OPERRA_GITHUB_CLIENT_ID；也可以直接在设置页使用 fine-grained GitHub token。
- 让 QCA 负责执行。 Adapter 只处理认证、Session、事件流、追问、中断与 Deployment。
- 定义产品级 Task。 不要把传输 payload 或 Agent 内部机制当成用户的第一心智。
- 把仓库作为持久上下文。 让 QCA 面向真实文件、版本历史与 Artifact 工作。
- 先归一化事件，再渲染界面。 把 QCA 事件流翻译为计划、活动、审核、失败与结果。
- 把断线恢复作为默认路径。 本地应用重启后应接回同一份云端工作，而不是重新执行。
- 关键动作保留人工审核。 Human-in-the-loop 应进入产品工作流。
- 让 Artifact 成为一等公民。 好用的产品交付文件与结果，而不只是一段对话。
- 用 QCA custom tools 构建控制面。 对话式运营 Agent 可以管理真实应用状态，不需要把状态隐藏在模型上下文中。
python3.11 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
python -m pytest -q
python scripts/e2e_ui.py默认测试使用 fixture，不要求真实 QCA token。
Operra 是 QCA 的参考实现，而不是官方 QCA SDK。QCA API 行为和认证方式应以 Qoder 最新文档为准。我们尤其欢迎能够让 QCA 集成模式更清晰、更安全、更容易复用的贡献。详见 CONTRIBUTING.md、SECURITY.md 和 PRIVACY.md。
本项目采用 Apache License 2.0，详见 LICENSE。