Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions content/zh-CN/recipes/litellm-qoder-cloud-agents/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
schema_version: 1
slug: litellm-qoder-cloud-agents
title: 通过 LiteLLM 接入 Qoder Cloud Agents
summary: 使用一个轻量兼容网关,把现有 LiteLLM、OpenAI SDK 和 Agent API 客户端接入 Qoder Cloud Agents,并按任务需求选择会话延续或 Chat Completions 兼容模式。
type: recipe
category: enterprise-integration
tags:
- agent
- api
- sdk
- session
- authentication
author:
name: 安辰
github: hellomypastor
locale: zh-CN
---

## 目标与适用场景

Qoder Cloud Agents 使用 Agent、Environment、Session 和事件流组织长时间运行的代码任务。很多应用则已经围绕 LiteLLM、OpenAI Python SDK 或 Chat Completions API 建立了模型调用层。本文使用一个轻量兼容网关连接两套接口,让现有客户端无需自行实现 Session 创建、消息发送和 SSE 事件消费。

网关提供两种接入方式:

| 场景 | 推荐接口 | 原因 |
| --- | --- | --- |
| 已有 LiteLLM 或 OpenAI SDK 客户端 | Model API | 保留熟悉的 Chat Completions 调用方式 |
| 一次性请求并需要标准模型响应 | Model API | 返回 OpenAI-compatible 响应 |
| 长时间代码任务 | Agent API | 保留 Agent 和 Session 语义 |
| 继续上一次任务 | Agent API | 使用 `previous_interaction_id` 继续原 Session |
| 实时展示执行结果 | Agent API | 可直接消费 SSE 事件流 |

当前 Model API 每次请求都会创建新的 Qoder Session。需要多轮复用同一工作目录和任务上下文时,应使用 Agent API。

## 操作步骤

先在 Qoder Cloud Agents 中准备一个 Agent、一个 Environment 和用于本地验证的 PAT。然后进入 Demo 目录,复制示例配置:

```bash
cd demos/litellm-qoder-cloud-agents
cp .env.example .env
```

在 `.env` 中填写 `QODER_PAT`、`QODER_AGENT_ID`、`QODER_ENVIRONMENT_ID`,并为 `GATEWAY_API_KEY` 和 `LITELLM_MASTER_KEY` 分别生成高熵随机值。不要把 `.env` 提交到版本库。

使用 Docker Compose 启动 Qoder 兼容网关和 LiteLLM:

```bash
docker compose up --build
```

Agent API 默认监听网关服务的 `4001` 端口,路径为 `/v1/interactions`。第一次请求创建 Qoder Session,响应中的 `id` 是不透明的续接标识;把它原样作为下一次请求的 `previous_interaction_id`,即可继续原 Session。请求体增加 `"stream": true` 后,响应改为 SSE 事件流。

LiteLLM 默认监听模型服务的 `4000` 端口,路径为 `/v1/chat/completions`。Demo 中的 `config/litellm.yaml` 注册了 `qoder-cloud-agent` 模型,并通过 OpenAI-compatible provider 把请求转发到网关。现有 OpenAI SDK 客户端只需替换 `base_url`、API Key 和模型名。

## 验证结果

先检查网关健康状态:

```bash
curl "$QODER_GATEWAY_URL/health/liveliness"
```

预期返回 `{"status":"ok"}`。随后分别调用 Agent API 和 LiteLLM Model API:前者应返回以 `qca1.` 开头的 `id` 和文本输出,后者应返回 `object: "chat.completion"` 以及非空的 `choices[0].message.content`。

Demo 还包含不访问外部网络的单元测试,用模拟 Runner 验证 API 鉴权、Session 延续、流式响应和新 Session 的来源标记。完整的配置、调用命令、清理步骤与生产安全边界见 Demo README。

[查看 Demo 源码](https://github.com/QoderAI/cloud-agents-cookbook/tree/main/demos/litellm-qoder-cloud-agents)

## 常见问题与生产边界

如果 LiteLLM 找不到 `qoder-cloud-agent`,确认容器已加载 Demo 中的 `config/litellm.yaml`,并且 `QODER_GATEWAY_BASE_URL` 在容器网络内指向网关服务。若请求返回 401,分别检查调用网关时使用的 `GATEWAY_API_KEY` 和调用 LiteLLM 时使用的 `LITELLM_MASTER_KEY`,两者用途不同。

这个示例是单 Agent、单 Environment 的兼容层,不是生产就绪的多租户网关。生产部署至少需要 TLS、网络访问控制、限流、审计、集中式密钥管理和凭据轮换。真实请求会创建或继续 Qoder Session 并消耗额度;Agent 也可能读取或修改 Environment 中可访问的数据和代码,因此应使用隔离环境并审查产出。
7 changes: 7 additions & 0 deletions demos/litellm-qoder-cloud-agents/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
.venv/
.env
__pycache__/
.pytest_cache/
.ruff_cache/
*.egg-info/
dist/
10 changes: 10 additions & 0 deletions demos/litellm-qoder-cloud-agents/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
FROM python:3.12.12-slim@sha256:f3fa41d74a768c2fce8016b98c191ae8c1bacd8f1152870a3f9f87d350920b7c

WORKDIR /app
COPY pyproject.toml README.md ./
COPY src ./src
RUN pip install --no-cache-dir .

USER 65532:65532
EXPOSE 4001
ENTRYPOINT ["litellm-qoder-cloud-agents"]
121 changes: 121 additions & 0 deletions demos/litellm-qoder-cloud-agents/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
# LiteLLM 接入 Qoder Cloud Agents Demo

这个 Demo 提供一个可独立部署的兼容网关,把 LiteLLM、OpenAI Python SDK 或直接的 HTTP 请求转换为 Qoder Cloud Agents Session API 调用。它支持两条路径:

- Agent API:调用 `POST /v1/interactions`,并通过 `previous_interaction_id` 继续同一个 Qoder Session。
- Model API:调用 LiteLLM 的 `POST /v1/chat/completions`,由 LiteLLM 通过 OpenAI-compatible provider 路由到网关。

## 对应文章

- 标题:通过 LiteLLM 接入 Qoder Cloud Agents
- Slug:`litellm-qoder-cloud-agents`

## 前置条件

- Docker Engine 24 或更高版本,以及 Docker Compose v2。
- 一个可用的 Qoder Cloud Agents Agent 和 Environment。
- 本地验证使用 Qoder 个人访问令牌(PAT);生产环境应使用适合服务端的短期凭证或 Service Account Token 流程。
- 如需直接运行或测试 Python 项目,安装 Python 3.10 或更高版本。

## 安装与配置

在本目录复制示例配置:

```bash
cp .env.example .env
```

编辑 `.env`,把所有占位符替换为自己的值:

```text
QODER_PAT=replace-me
QODER_AGENT_ID=agent_replace_me
QODER_ENVIRONMENT_ID=env_replace_me
GATEWAY_API_KEY=replace-me
LITELLM_MASTER_KEY=replace-me
QODER_GATEWAY_BASE_URL=http://qoder-cloud-agents:4001/v1
```

`GATEWAY_API_KEY` 和 `LITELLM_MASTER_KEY` 应使用不同的高熵随机值。不要提交 `.env`;它已被 `.gitignore` 排除。

## 运行

启动网关和 LiteLLM:

```bash
docker compose up --build
```

另开一个终端,根据 Compose 发布的端口设置下面调用所用的基地址:

```bash
QODER_GATEWAY_URL="http://$(docker compose port qoder-cloud-agents 4001)"
LITELLM_URL="http://$(docker compose port litellm 4000)"
export QODER_GATEWAY_URL LITELLM_URL
```

直接调用 Agent API:

```bash
curl "$QODER_GATEWAY_URL/v1/interactions" \
-H "Authorization: Bearer $GATEWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": "qca/agent_replace_me/env_replace_me",
"input": "检查代码并给出修改建议"
}'
```

保存返回的 `id`,可在下一次请求中作为 `previous_interaction_id` 继续同一个 Session。要实时接收结果,在请求体中加入 `"stream": true`。

通过 LiteLLM 调用 Model API:

```bash
curl "$LITELLM_URL/v1/chat/completions" \
-H "Authorization: Bearer $LITELLM_MASTER_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qoder-cloud-agent",
"messages": [{"role": "user", "content": "检查代码并给出修改建议"}]
}'
```

Model API 当前每次请求都会创建新的 Qoder Session。需要连续使用同一个工作目录和任务上下文时,请使用 Agent API。

## 验证结果

先验证服务存活:

```bash
curl "$QODER_GATEWAY_URL/health/liveliness"
```

预期返回 `{"status":"ok"}`。Agent API 成功响应的 `id` 以 `qca1.` 开头;Model API 成功响应包含 `object: "chat.completion"` 和非空的 `choices[0].message.content`。

单元测试使用模拟 Runner,不调用 Qoder,也不消耗额度:

```bash
python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/ruff check .
.venv/bin/pytest
```

## 清理资源

停止并删除本地容器和网络:

```bash
docker compose down --remove-orphans
```

删除本地 `.env` 和虚拟环境;不再使用的 PAT 与 API Key 应在对应平台吊销或轮换。通过本 Demo 创建的 Qoder Session 可在 Qoder 控制台中归档或删除。

## 成本与安全

- 真实的 Agent API 和 Model API 请求会创建或继续 Qoder Session,并消耗 Qoder 额度;单元测试不会。
- 网关能代表调用者向绑定的 Agent 和 Environment 发起任务。只授予必要权限,并使用独立、可轮换的凭据。
- `GATEWAY_API_KEY` 未设置时,网关的 `/v1` 接口不会执行应用层鉴权。不要在公网或共享网络中以这种方式运行。
- 示例将端口绑定到本机所有接口。生产部署应增加 TLS、网络访问控制、请求限流、审计与集中式密钥管理。
- Agent 可能读取或修改 Environment 中可访问的数据和代码。使用隔离环境,并在合并或发布前审查结果。
- 此 Demo 是兼容层示例,不是生产就绪的多租户网关。
9 changes: 9 additions & 0 deletions demos/litellm-qoder-cloud-agents/config/litellm.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
model_list:
- model_name: qoder-cloud-agent
litellm_params:
model: openai/qoder-cloud-agent
api_base: os.environ/QODER_GATEWAY_BASE_URL
"api_key": os.environ/GATEWAY_API_KEY

general_settings:
master_key: os.environ/LITELLM_MASTER_KEY
17 changes: 17 additions & 0 deletions demos/litellm-qoder-cloud-agents/docker-compose.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
services:
qoder-cloud-agents:
build: .
env_file: .env
ports:
- "4001:4001"

litellm:
image: ghcr.io/berriai/litellm:main-stable@sha256:c560d317136880ea92d62334d4367ab10955b1af189dd3ea24f6551290b1d6c1
command: ["--config", "/app/config.yaml", "--port", "4000"]
env_file: .env
volumes:
- ./config/litellm.yaml:/app/config.yaml:ro
ports:
- "4000:4000"
depends_on:
- qoder-cloud-agents
41 changes: 41 additions & 0 deletions demos/litellm-qoder-cloud-agents/pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
[build-system]
requires = ["hatchling==1.28.0"]
build-backend = "hatchling.build"

[project]
name = "litellm-qoder-cloud-agents"
version = "0.1.0"
description = "LiteLLM-compatible Agent API and Model API gateway for Qoder Cloud Agents"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
"fastapi==0.121.3",
"pydantic-settings==2.12.0",
"qca-sdk==0.15.0",
"uvicorn[standard]==0.38.0",
]

[project.optional-dependencies]
dev = [
"httpx==0.28.1",
"pytest==9.0.1",
"pytest-asyncio==1.3.0",
"ruff==0.14.5",
]

[project.scripts]
litellm-qoder-cloud-agents = "litellm_qoder_cloud_agents.main:run"

[tool.hatch.build.targets.wheel]
packages = ["src/litellm_qoder_cloud_agents"]

[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]

[tool.ruff]
line-length = 120
target-version = "py310"

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
from litellm_qoder_cloud_agents.app import create_app

__all__ = ["create_app"]
Loading
Loading