Skip to main content
快速开始

概述

Qoder Agent SDK 正式开放，可快速构建生产级别 Agent。

Qoder Agent SDK 把驱动 Qoder 系列产品的 Harness 以 SDK 的形式开放。任务规划、工具调用、上下文和会话管理、权限管控、长短期记忆能力，这一整套运行时能力现在可直接嵌入 TypeScript 或 Python 应用。

可以构建什么

Qoder Agent SDK 提供成熟的 Agent 运行底座和灵活的接入能力。通过 SDK 集成，你可以把自有工具、内部数据和业务系统接入 Agent 的执行流程，在自己的产品里获得一个能端到端完成任务的生产级别 Agent。
Agent 形态典型场景
编程 Agent嵌在 IDE 或自研开发工具里，让 Agent 读懂整个仓库后写代码、改 Bug、跑测试，开发者只验收结果
终端 Agent登到服务器上排查线上故障、批量修改配置、执行运维脚本，危险命令逐步报人工审批
办公 Agent从多个内部系统拉数据汇总周报、整理表格、按公司模板产出文档，交付可直接使用的文件
研发流水线集成在 CI 里自动修复测试、补全注释、对每个提交做代码评审，以只读方式跑完就退出
垂直行业 Agent金融、医疗等行业内的专用助手，接入行业系统与专有数据，在合规边界内完成专业任务

Qoder Agent SDK 与 QoderCN CLI 的职责

Qoder Agent SDK 是面向应用的接口；QoderCN CLI 是 Agent 运行时，负责任务规划、模型通信，以及在目标环境里执行工具。 
TypeScript 或 Python 应用
                 |
                 |  Qoder Agent SDK
                 |  任务、选项、事件、控制指令
                 v
             qoderclicn
                 |
                 +-- Qoder 模型服务
                 +-- 文件、命令、MCP 工具和子 Agent
正式发布的 Qoder Agent SDK 包已内置兼容的 QoderCN CLI 运行时，通常不需要单独安装 QoderCN CLI。如果运行时由你自己管理，也可以指定 qoderclicn 可执行文件的路径。 如需了解启动过程、通信协议和 Agent 循环，请阅读工作原理。

选择 SDK

选择与宿主应用相同的语言。
TypeScriptPython
安装包@qodercn-ai/qodercn-agent-sdkqodercn-agent-sdk
运行环境Node.js 18+Python 3.10+
一次性任务query()query()
多轮会话向 query() 传入异步消息流QoderSDKClient
输出带类型的异步消息流带类型消息对象的异步流
npm install @qodercn-ai/qodercn-agent-sdk
两种语言的完整可运行示例见快速开始。

集成流程

一次典型集成包含四个部分：
  1. 描述任务。 发送提示词，按需设置工作目录、模型、系统提示词和轮次上限。
  2. 划定边界。 选定可用工具和权限模式；需要应用侧批准的操作，用回调交给应用决定。
  3. 消费消息流。 处理模型回复、工具活动、进度事件，以及最终的 result 消息。
  4. 按需控制会话。 长期运行的集成可以追加消息、中断执行、调整部分运行时设置，或查询会话状态。
一次性任务直接给 query() 传字符串即可。如果下一轮输入要看上一轮的输出，就用多轮对话里对应语言的多轮写法。

可配置能力

能力分类具体能力
输入与输出一次性或多轮输入、图片输入、结构化消息、增量流式事件
工具内置文件与命令工具、自定义工具、外部或进程内 MCP 服务
Agent 行为系统提示词与输出风格、模型、Skills、插件、可复用 Agent 定义、子 Agent
安全与控制工具白名单、权限模式、审批回调、Hooks、中断、轮次上限
代码安全对 Agent 自身改动的静态检查，以及仓库级轻量扫描与深度扫描
记忆原生用户级与项目级记忆，或由应用接管生成与消费 （仅 TypeScript）
会话管理工作目录、持久会话、恢复与派生、检查点、外部会话存储、用量与上下文信息
任务执行后台任务、任务列表与取消、单任务中断
配置内联设置、文件系统设置来源、已解析设置的查看
各语言 API 的概念对照见 SDK 参考。少数能力只在一种语言里提供，正文会就地标注，也在语言差异中集中列出。

执行边界

Agent 会对环境产生真实改动，它的工作目录、工具、凭证和权限策略都属于应用安全边界的一部分。
  • SDK 与 QoderCN CLI 之间默认走本地通道，但 QoderCN CLI 需要访问 Qoder 模型服务，提示词和推理所需的上下文会发送到该服务。
  • 文件写入和命令执行都发生在 QoderCN CLI 所在的环境里。cwd 要明确设置，可执行的动作用权限控制收紧。
  • 模型不会直接读写文件或执行命令，它只发出工具调用请求，由 QoderCN CLI 按既定策略校验后执行。
  • 跳过权限校验的模式，只适用于已有外部隔离手段的环境。

下一步

快速开始
核心概念
对话与会话
工具与扩展
控制与安全
参考