Metadata-Version: 2.4
Name: ksadk
Version: 0.3.0
Summary: Kingsoft Cloud Agent Development Kit - 支持 LangChain/LangGraph/DeepAgents/ADK 的本地运行与云端部署
Author-email: KsADK Team <xiayu@kingsoft.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/kingsoftcloud/ksadk-python
Project-URL: Repository, https://github.com/kingsoftcloud/ksadk-python
Project-URL: Documentation, https://ksadk.kingsoft.com/docs
Keywords: agent,langchain,langgraph,deepagents,adk,faas,kingsoft cloud,ai,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: questionary>=2.0.0
Requires-Dist: textual>=0.50.0
Requires-Dist: fastapi<0.124.0,>=0.100.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: requests>=2.28.0
Requires-Dist: requests-aws4auth>=1.2.0
Requires-Dist: ks3sdk>=1.15.0
Requires-Dist: langchain<2.0.0,>=0.3.0
Requires-Dist: langchain-openai<2.0.0,>=0.2.0
Requires-Dist: langchain-core<2.0.0,>=0.3.0
Requires-Dist: langgraph<2.0.0,>=0.2.0
Requires-Dist: chainlit>=1.0.0
Requires-Dist: opentelemetry-api==1.37.0
Requires-Dist: opentelemetry-sdk==1.37.0
Requires-Dist: opentelemetry-exporter-otlp==1.37.0
Provides-Extra: adk
Requires-Dist: google-adk>=1.0.0; extra == "adk"
Requires-Dist: litellm>=1.0.0; extra == "adk"
Requires-Dist: json_repair>=0.25.0; extra == "adk"
Provides-Extra: langchain
Requires-Dist: langchain>=0.3.0; extra == "langchain"
Requires-Dist: langchain-openai>=0.2.0; extra == "langchain"
Requires-Dist: langchain-core>=0.3.0; extra == "langchain"
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2.0; extra == "langgraph"
Requires-Dist: langchain>=0.3.0; extra == "langgraph"
Requires-Dist: langchain-openai>=0.2.0; extra == "langgraph"
Requires-Dist: protobuf>=6.32.1; extra == "langgraph"
Provides-Extra: deepagents
Requires-Dist: deepagents>=0.3.0; python_version >= "3.11" and extra == "deepagents"
Requires-Dist: langgraph>=0.2.0; extra == "deepagents"
Requires-Dist: langchain>=0.3.0; extra == "deepagents"
Requires-Dist: langchain-openai>=0.2.0; extra == "deepagents"
Provides-Extra: tracing
Requires-Dist: openinference-instrumentation-langchain>=0.1.0; extra == "tracing"
Provides-Extra: kb
Requires-Dist: kingsoftcloud-sdk-python>=1.5.8.71; extra == "kb"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: ksadk[adk,deepagents,dev,kb,langchain,langgraph,tracing]; extra == "all"

# ksadk (AgentEngine CLI)

`ksadk` 是金山云 Agent 开发与部署工具链，提供统一的 CLI 体验，覆盖本地开发、构建、部署、调用、版本管理与 MCP Server 管理。

当前版本：`0.3.0`

## 核心能力

- 多框架支持：DeepAgents、LangGraph、LangChain、Google ADK。
- ADK 增强能力：支持短期/长期记忆体（STM/LTM）与知识库工具注入。
- 本地开发：`run`（API/TUI）与 `web`（本地 Invoke 调试 UI）。
- 云端部署：`build`、`deploy`、`launch`，支持 `Code` / `Container` 两种制品模式。
- 云端 UI 访问：`dashboard` 统一打开已部署 Agent 的 Web UI（含 OpenClaw）。
- 统一控制面：通过 `AgentEngine Server` 进行 Agent/MCP 管理。
- 状态持久化：部署后保存 `.agentengine.state`，供后续 `status/invoke/destroy/version` 复用。
- 版本管理：`version list/release/rollback`。
- MCP 管理：`mcp deploy/list/status/delete`。

## 安装

```bash
pip install -U ksadk
```

可选依赖：

```bash
pip install "ksadk[langgraph]"
pip install "ksadk[langchain]"
pip install "ksadk[deepagents]"
pip install "ksadk[adk]"
pip install "ksadk[kb]"
```

安装后可使用以下命令入口（等价）：

```bash
agentengine --help
ksadk --help
```

## 快速开始

### 1) 初始化项目

```bash
agentengine init my_agent -f langgraph
cd my_agent
```

DeepAgents 模板：

```bash
agentengine init my_deep_agent -f deepagents
cd my_deep_agent
```

也可包装已有代码：

```bash
agentengine init --from-agent ./my_agent.py
agentengine init --from-agent ./my_agent_dir
```

### 2) 交互式配置

```bash
agentengine config
```

会生成或更新：

- `agentengine.yaml`
- `.env`

### 3) 本地调试

```bash
agentengine run -i
```

或启动 Web UI：

```bash
agentengine web --port 8080
```

### 4) 一键构建+部署

```bash
export KSYUN_ACCESS_KEY=your-ak
export KSYUN_SECRET_KEY=your-sk
export KSYUN_ACCOUNT_ID=your-account-id
export KSYUN_REGION=cn-beijing-6

agentengine launch . --target serverless
```

### 5) 打开云端已部署 Agent UI

```bash
# 目录内自动解析 agent（.agentengine.state -> agentengine.yaml/ksadk.yaml）
agentengine dashboard

# 显式指定 Agent
agentengine dashboard --agent ar-xxxx

# OpenClaw 也走统一入口
agentengine dashboard --agent openclaw-gateway-xxxx
```

### 6)（可选）启用 ADK 记忆与知识库

```bash
# 记忆体后端: local | http | sdk
export KSADK_LTM_BACKEND=local

# 配置知识库后，Runner 会自动注入 search_knowledge_base 工具
export KSADK_KB_DATASET_ID=your_dataset_id
```

## 命令总览

- `agentengine init`：创建新项目（支持 `--from-agent`）。
- `agentengine config`：交互式配置 `agentengine.yaml` + `.env`。
- `agentengine model`：从模型服务拉取模型列表并更新 `.env` 的 `OPENAI_MODEL_NAME`。
- `agentengine run`：本地运行 Agent（支持 `-i` TUI）。
- `agentengine web`：启动本地调试 UI（ADK 项目用 ADK Web，其他用 Chainlit）。
- `agentengine dashboard`：打开云端已部署 Agent 的 Dashboard/WebUI。
- `agentengine build`：构建制品（`code` 或 `container`）。
- `agentengine deploy`：部署到 `serverless` / `kcf` / `kce`。
- `agentengine launch`：`build + deploy` 一条命令完成。
- `agentengine status`：查看运行状态与 endpoint。
- `agentengine invoke`：调用远端或本地 Agent。
- `agentengine destroy`：销毁 Agent。
- `agentengine version`：版本管理（`list/release/rollback`）。
- `agentengine mcp`：MCP Server 管理。
- `agentengine openclaw`：一键拉起 OpenClaw（部署/状态/删除等）。
- `agentengine completion`：Shell 补全脚本与自动安装。

说明：
- `agentengine openclaw dashboard` 已收敛为统一命令 `agentengine dashboard`。
- `dashboard` 默认通过 `CreateDashboardTicket` 直开浏览器；`CreateDashboardTicket` 不可用时不会回退 API Key URL 票据。

## Agent 指定规则（统一）

适用于：`status`、`invoke`、`destroy`、`version` 子命令。

支持三种写法：

- 推荐：`--agent <id-or-name>`
- 兼容：`--agent-id <id-or-name>`
- 位置参数：`<id-or-name>`

示例：

```bash
agentengine status --agent ar-xxxx
agentengine status ar-xxxx
agentengine invoke --agent my_agent -m "你好"
agentengine destroy my_agent
agentengine version list --agent ar-xxxx
```

未显式传 Agent 时，自动解析顺序为：

1. `.agentengine.state`（优先 `agent_id`，其次 `name`）
2. `agentengine.yaml` / `ksadk.yaml` 的 `name`

## 构建与部署

### build

```bash
# 1) 默认构建 (code 模式)
agentengine build .

# 2) 显式指定构建参数
agentengine build . --mode container --push --registry hub-cn-beijing-6.kce.ksyun.com
# 3) 显式指定区域
KSYUN_REGION=cn-beijing-6 agentengine build . --mode code --push --no-cache
```

### deploy

```bash
# 1) 默认部署 (serverless)
agentengine deploy .
# 2) 显式指定部署参数
agentengine deploy . --target kcf --account-id X-Ksc-Account-Id
# 3) 显式指定区域
KSYUN_REGION=cn-beijing-6 agentengine deploy . --target serverless --dry-run
```

常用参数：

- `--artifact-type [Code|Container]`
- `--region`
- `--account-id`
- `--observability/--no-observability`
- `--no-version`
- `--auto-rollback`

### launch

```bash
# 1) 默认一键部署 (serverless)
agentengine launch .
# 2) 显式指定部署参数
agentengine launch . --target kce --artifact-type Container
# 3) 显式指定区域
KSYUN_REGION=cn-beijing-6 agentengine launch . --target serverless --no-cache
```

## 版本管理

```bash
# 1) 目录内自动解析 agent（优先 .agentengine.state）
agentengine version list

# 2) 显式指定 agent
agentengine version list --agent ar-xxxx
agentengine version release --agent ar-xxxx --tag v1.0.1 --description "release note"
agentengine version rollback --agent ar-xxxx --to v1.0.0 -y

# 3) 显式指定区域
KSYUN_REGION=cn-beijing-6 agentengine version list --agent ar-xxxx
KSYUN_REGION=cn-beijing-6 agentengine version release --agent ar-xxxx --tag v1.0.1
KSYUN_REGION=cn-beijing-6 agentengine version rollback --agent ar-xxxx --to v1.0.0 -y
```

## MCP Server 管理

```bash
# 1) 默认部署
agentengine mcp deploy .
# 2) 常用查询
agentengine mcp list
# 3) 显式指定区域
KSYUN_REGION=cn-beijing-6 agentengine mcp status <mcp_id>
# 删除
agentengine mcp delete <mcp_id> --yes
```

## 关键文件

- `agentengine.yaml`：项目配置（name/framework/entry_point 等）。
- `.env`：模型、云凭证、可观测性配置。
- `.agentengine.state`：部署后本地状态（`agent_id` / `endpoint` / `api_key` / `region`）。
- `~/.agentengine/settings.json`：全局配置（可被 `config --global` 更新）。

## 环境变量

| 变量名 | 说明 |
|---|---|
| `OPENAI_API_KEY` | 模型 API Key |
| `OPENAI_BASE_URL` | 模型 API Base URL |
| `OPENAI_MODEL_NAME` | 模型名称 |
| `KSYUN_ACCESS_KEY` | 金山云 AK |
| `KSYUN_SECRET_KEY` | 金山云 SK |
| `KSYUN_ACCOUNT_ID` | 金山云账号 ID |
| `KSYUN_REGION` | 默认区域 |
| `LANGFUSE_PUBLIC_KEY` | Langfuse 公钥 |
| `LANGFUSE_SECRET_KEY` | Langfuse 私钥 |
| `LANGFUSE_BASE_URL` / `LANGFUSE_HOST` | Langfuse 地址 |
| `KSADK_LTM_BACKEND` | ADK 长期记忆后端（`local/http/sdk`） |
| `KSADK_LTM_HTTP_URL` | LTM HTTP 后端地址（当 `KSADK_LTM_BACKEND=http`） |
| `KSADK_KB_DATASET_ID` | 知识库 Dataset ID（配置后启用知识库检索） |

兼容别名仍可识别：`OPENAI_API_BASE`、`MODEL_NAME`。

## 架构说明

云端链路：

```text
CLI (ksadk) -> AgentEngine Server (控制面) -> Serverless/KCF/KCE
```

本地链路：

```text
CLI (run/web) -> Unified Runner -> 本地 Agent 进程
```

## 补全

```bash
agentengine completion install --shell auto
```

## 示例项目

见 [examples](./examples) 目录。

## 进阶文档

- [DeepAgents 框架支持说明](./docs/deepagents.md)
- [ADK 记忆能力使用说明](./docs/memory_usage_guide.md)
- [知识库与记忆能力示例](./docs/knowledge_base_and_memory_examples.md)
