Skip to main content

应用集成

按应用场景选择 SDK 运行形态与调用身份,完成基础接入,再按需配置业务能力。

通过 Qoder Agent SDK,可以在自有应用、内部工具或自动化服务中接收任务、调用业务工具并交付结果。SDK 能力与执行机制见概述和工作原理。

集成场景

根据你的需求,选择接入方式并进入对应操作说明:
你的需求接入方式操作入口
开发自有 Agent 应用,或为现有产品增加 Agent 能力在桌面应用、Web 后端或研发工具中集成 SDK确定调用身份、接入步骤
将 Agent 接入业务流程,自动执行任务由脚本、任务服务或流水线调用 SDK接入步骤、按需增加业务能力
统计用户消耗,或按权限、套餐及余额限制使用关联业务用量,按需增加任务启动前检查用量统计与任务准入
在每次模型调用前检查,或接收用量通知通过服务端回调对接业务系统适用条件与开通
以上能力可按需组合,无需全部接入。

确定调用身份

个人调用

个人访问令牌(PAT)代表一个 Qoder 用户,适合使用该用户权限和数据的脚本、CI 或应用。开发工作站也可以复用本机 Qoder CLI 登录态;自动化服务应显式配置凭证。

组织应用

服务账号(Service Account,SA)是组织下的独立应用身份,适用于不应依赖个人账号的后端服务、CI 和定时任务。业务用户继续登录你的应用,无需分别创建 Qoder 账号;应用负责用户认证与任务授权。组织管理见成员和角色及服务账号。

根据部署位置管理 SA 凭证

  • 可信后端运行 SDK:后端保管 SA Key,直接传入 SDK,由 SDK 获取并刷新短期令牌 SAT。
  • 终端应用或集中提供凭证:可信服务端保管 SA Key,校验业务用户后换取 SAT,由宿主应用提供并刷新 SAT。SA Key 不放入分发给用户的客户端。
SA 调用示例:由可信服务端提供 SAT应用向客户凭证服务提交业务登录信息,申请 SAT。 客户凭证服务校验业务用户与取证权限;未通过时返回拒绝原因。 校验通过后,客户凭证服务使用 SA Key 向 Qoder 换取 SAT。 Qoder 返回短期 SAT,客户凭证服务将 SAT 提供给 SDK。 SDK 使用 SAT 发起模型请求,Qoder 返回模型结果。SA 调用示例:由可信服务端提供 SAT客户应用集成 Qoder Agent SDK客户凭证服务保管长期 SA KeyQoder签发 SAT / 处理模型请求① 申请 SAT(携业务登录信息)校验用户与取证权限未通过:返回拒绝原因② 通过:用 SA Key 换取 SAT③ 返回短期 SAT④ 通过回调提供 SAT⑤ SDK 携 SAT 发起模型请求⑥ 返回模型结果或调用错误

开始以服务账号集成

按以下顺序完成配置,已有配置可复用。订阅、计费、服务账号和凭证须对应同一目标组织。

步骤 1:确认组织与订阅

由采购人员使用具备下单权限的阿里云账号,按企业订阅配置流程购买或确认目标组织有效的 Teams、Enterprise 或 Enterprise VPC 订阅。价格与下单要求见计费说明。

步骤 2:开通 SA 按量付费

使用有权管理目标组织的阿里云账号,按开通步骤启用 SA 按量付费,再返回 Qoder 确认状态已同步。 组织订阅与 SA 按量付费分别配置。SA 按实际消耗后付费,用量上限不代表充值;规则见服务账号计费说明。

步骤 3:创建服务账号与凭证

  1. 由组织管理员创建服务账号,按需设置用量上限。
  2. 按凭证管理创建 SA Key,并保存在可信服务端的密钥管理工具中。

步骤 4:安装 SDK 并配置 SA 认证

选择 JavaScript/TypeScript(Node.js)、Python 或 Java SDK,按快速开始的安装说明安装。认证配置使用以下两种方式之一: 具体接口见 TypeScript 参考、Python 参考和 Java 参考,能力差异见 SDK 参考。

步骤 5:运行任务并核对用量

  1. 按快速开始运行首个任务,使用步骤 4 的 SA 认证配置,并指定工作区与工具权限。
  2. 收到最终结果后,按错误处理与错误码确认任务状态,并查看成本和用量。
  3. 在服务账号用量中核对 SA 消耗,通过账单查询核对结算记录。
上线前验证权限、超时、取消和会话恢复。调用异常见问题排查;SA 开通、凭证与限额问题见 SA 故障排查。

按业务需要增加能力

以下能力可按需组合,配置细节见对应文档:
业务需求接入方式与文档
访问业务数据、调用内部系统自定义工具、MCP
提供业务职责、团队规范和工作方法系统提示词、Skills
拆分专门职责、统一分发扩展Subagents、Plugins
操作前审批、执行前后校验与审计权限控制、Hooks
跨实例恢复会话外置会话存储
复用历史经验、恢复文件状态记忆、文件快照与回滚
配置模型策略、检查代码安全模型选择、安全扫描
按用户或客户统计消耗保存用户、任务与会话的对应关系,读取成本和用量并在业务侧记账
根据权限、套餐或余额限制使用在应用侧检查业务权益,通过后启动任务,未通过则返回原因;Qoder 仍校验调用凭证与平台限额
逐次检查模型调用、接收用量通知对接服务端推理回调,仅限 Qoder CN 2.0 VPC(企业独立实例部署)中的服务账号调用;需提供公网 HTTPS 服务并由实施团队开通,与 SDK Hooks 分别配置

常见问题

每位业务用户都需要 Qoder 账号吗?

使用 SA 集成时不需要。业务用户继续使用应用自己的账号,SA 代表应用访问 Qoder。用户登录、数据访问权限和任务授权仍由应用负责,见组织应用。

买了组织订阅,就可以直接使用 SA 调用吗?

还不可以。组织订阅与 SA 按量付费需要分别配置。还需为目标组织开通 SA 按量付费并确认状态同步,再创建 SA、生成凭证并配置 SDK 认证。按开始以服务账号集成依次完成配置后,再运行任务。

任务启动前检查通过,后续模型调用就一定成功吗?

不一定。一次 SDK 任务可能包含多次模型调用,任务启动前的业务检查只决定是否启动任务;调用仍需满足 Qoder 的凭证与限额条件。如需在每次模型调用前检查权限或余额,需满足服务端推理 Hook的条件并完成接入。

保存了会话,就能在另一台机器继续任务吗?

还需保证项目文件可访问,并使用一致的项目目录语义。外置会话存储不会迁移工作区。

记录了用户消耗,平台就会按用户分别出账吗?

不会。平台统计服务账号的消耗,应用关联业务用户并自行分摊记账;最终费用以阿里云账单为准。