Skip to main content
快速开始

概述

Qoder Agent SDK 让 TypeScript 或 Python 应用能够以编程方式运行 Qoder 编程 Agent。它不只是返回生成的文本，还能检查项目、使用经过授权的工具、修改文件、执行命令，并返回结构化结果。 Agent SDK 适合为脚本、服务、CI 任务、开发者工具或内部工作流加入编程 Agent 能力，无需自动操作交互式终端。

SDK 与 qodercli 的职责

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

选择 SDK

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

编程模型

一次典型集成包含四个部分：
  1. 描述任务。 发送任务文本，并按需设置工作目录、模型、系统提示词和最大轮数。
  2. 设置边界。 选择允许使用的工具和权限模式，或通过回调让应用处理需要确认的操作。
  3. 消费消息流。 处理 Agent 文本、工具活动、进度事件以及最终的 result 消息。
  4. 按需控制会话。 长会话可以继续发送消息、中断任务、调整部分运行参数或查询会话状态。
一次性任务可以给 query() 传入字符串。如果后续输入依赖前面的输出，请使用输入模式中的语言专属多轮方式。

可以配置什么

能力范围应用可以获得什么
输入与输出一次性或多轮输入、结构化消息和增量流式事件
工具内置文件与命令工具、自定义工具，以及外部或进程内 MCP 服务
Agent 行为系统提示词、模型、技能、插件、可复用 Agent 定义和子 Agent
安全与控制工具白名单、权限模式、审批回调、Hooks、中断和轮数限制
会话管理工作目录、持久化会话、恢复、Checkpoint、用量和上下文信息
SDK References列出了通用概念与两种语言 API 的对应关系。

执行边界

Agent 可能产生真实改动。工作目录、工具、凭据和权限策略都应视为应用安全边界的一部分。
  • SDK 与 qodercli 默认在本机通信，但 qodercli 会访问 Qoder 模型服务。任务文本以及推理所需的上下文可能发送到该服务。
  • 文件修改和命令在 qodercli 所在环境执行。请明确设置 cwd，并通过权限控制限制操作范围。
  • 模型不会直接访问文件或运行命令。模型提出工具调用请求，由 qodercli 按配置的策略校验和执行。
  • 跳过权限确认的模式只适合已经由外部机制提供充分隔离的运行环境。

下一步

快速开始
核心概念
对话与会话
扩展能力
控制与可观测性
参考