KsADK

快速开始

本页会创建一个本地 LangGraph Agent，配置 OpenAI 兼容模型 provider，在终端运行它， 并打开本地 Web UI。

整个流程以本地开发为中心，不需要内部 Kingsoft Cloud 账号、私有网关、内部对象存储或私有 Kubernetes 集群。

准备条件

  • Python 3.10 或更新版本。
  • 可使用 python 和 pip 的 shell。
  • 一个你自己控制的 OpenAI 兼容聊天模型 endpoint 和 API Key。

可选框架依赖按需安装。本快速开始使用 LangGraph。

创建干净工作区

shell
mkdir ksadk-quickstart
cd ksadk-quickstart

学习阶段建议把虚拟环境放在工作区内。生产项目可以使用团队已有的 Python 环境管理方式。

安装

  1. 创建并激活虚拟环境，安装 ksadk：

    shell
    python -m venv .venv
source .venv/bin/activate
pip install ksadk

  2. 安装 LangGraph extra：

    shell
    pip install "ksadk[langgraph]"

  3. 确认 CLI 可用：

    shell
    agentengine --help
agentengine --version

创建项目

shell
agentengine init my-agent -f langgraph
cd my-agent

生成项目会包含 Agent 入口文件和项目配置文件。更多细节见 项目结构。

预期文件：

agent.py
agentengine.yaml

配置模型

使用非交互命令可以让设置可复现：

shell
agentengine config set \
  OPENAI_API_KEY=sk-test \
  OPENAI_BASE_URL=https://api.example.com/v1 \
  OPENAI_MODEL_NAME=my-model

真实 provider 值只放在本地 .env。不要提交 .env。

检查生效配置：

shell
agentengine config show

也可以使用交互式向导：

shell
agentengine config

检查 Agent

打开 agent.py，确认配置的 Agent 变量存在。默认 LangGraph 项目应导出：

agent.py
root_agent = graph.compile()

打开 agentengine.yaml，确认：

agentengine.yaml
framework: langgraph
entry_point: agent.py
agent_variable: root_agent

终端运行

shell
agentengine run . -i

常用参数：

参数作用
--model <name>为本次运行覆盖配置模型
--show-thinkingprovider 返回 reasoning 时展示推理输出
--no-stream等完整响应后再渲染
--no-trace禁用 tracing

发送一个基础 prompt：

prompt
What can this agent do?

如果模型 provider 可访问，CLI 会流式输出或打印响应。失败时看 故障排查。

启动本地 Web UI

shell
agentengine web . --no-open

命令会打印一个本地 URL。用浏览器打开后发送测试消息。agentengine web 使用 Python 包内置的静态资源，终端用户不需要 Node.js。

本地 UI 默认把调试状态写入 .agentengine/。不要提交这个目录。

本地运行流程

启动本地 API Server

shell
agentengine run . --port 8080

调用 Chat Completions endpoint：

shell
curl http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "my-agent",
    "messages": [
      {"role": "user", "content": "Say hello from KsADK"}
    ],
    "stream": false
}'

调用 Responses endpoint：

shell
curl http://127.0.0.1:8080/v1/responses \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "my-agent",
    "input": "Return a one sentence status.",
    "stream": false
  }'

只有当客户端能消费 server-sent events 时，才使用 stream: true。

停止本地进程

终端交互或本地 server 可以用 Ctrl-C 停止。重置本地 UI 状态时删除：

shell
rm -rf .agentengine/

下一步

本页导航

准备条件创建干净工作区安装创建项目配置模型检查 Agent终端运行启动本地 Web UI启动本地 API Server停止本地进程下一步