Skip to main content
快速开始

快速开始

Qoder Agent SDK 让你在 TypeScript、Python 或 Java 中调用 Qoder AI 的能力——读写文件、搜索代码、执行命令等——只需几行代码就能把 AI Agent 嵌入到你的应用或脚本里。

前置条件

  • TypeScript：Node.js 18+
  • Python：Python 3.10+
  • Java：JRE 8+

安装

npm install @qodercn-ai/qodercn-agent-sdk
Java 使用 Gradle 时添加 implementation 'cn.qoder.sdk:qodercn-agent-sdk:VERSION'。Maven 和 Gradle 中的 VERSION 都替换为 Maven Central 上已发布的 SDK 版本。Java SDK 不随包携带 qoderclicn，首次启动时下载本版本锁定的 CLI 并缓存复用，运行环境需要能访问 Qoder 下载站点。离线环境和自行指定 CLI 的做法见托管 CLI（Java）。

认证

SDK 通过 Personal Access Token (PAT) 认证身份，适用于脚本、CI 流水线和第三方集成场景。 到 qoder.cn/account/integrations 生成 PAT（生成后立即复制，页面关闭后无法再次查看）。详细步骤、自定义环境变量、复用本机 qoderclicn 登录态等，见 SDK 认证。 拿到 PAT 后，推荐先设置环境变量： 
export QODERCN_PERSONAL_ACCESS_TOKEN="<your-qoder-personal-access-token>"
node agent.mjs
然后用 accessTokenFromEnv()（TypeScript）/ access_token_from_env()（Python）/ Auth.accessTokenEnv()（Java）配置认证： 
import { accessTokenFromEnv, query } from '@qodercn-ai/qodercn-agent-sdk';

const stream = query({
  prompt: 'Hello',
  options: {
    auth: accessTokenFromEnv(),
  },
});
SDK 会在启动 qoderclicn 前读取该环境变量，并把解析后的 access token 写入一次性的 auth payload。通常不需要再通过 env 选项传 PAT；如果显式提供了 options.env，SDK 会优先从其中读取同名变量。Java 只读取 JVM 进程的环境变量，putEnvironment() 传入的同名变量不参与认证。
安全提示：不要把 PAT 硬编码在代码仓库中。推荐通过环境变量或密钥管理服务注入。

单次查询与多轮对话

TypeScript 和 Python SDK 都以 query() 作为核心入口：一次提交一条用户消息，SDK 完成本轮回复后关闭会话，适合一次性、无状态的任务。Java 的对应入口是 QoderClient.query()，传入 OneShotQueryRequest，CLI 完成本轮回复后退出。 如果要在同一会话里发多条消息、根据回复决定下一步：TypeScript 给 query() 传入异步消息流；Python 使用 QoderSDKClient 维护长连接；Java 用 QoderClient.openSession() 打开 QoderSession，多次调用 send()。详见 多轮对话。

完整示例

创建 agent.mjs（TypeScript）、agent.py（Python）或 Agent.java（Java，放在 Maven 项目的 src/main/java/ 下）： 
import { accessTokenFromEnv, query } from '@qodercn-ai/qodercn-agent-sdk';

for await (const message of query({
  prompt: 'Analyze the codebase, find functions without test coverage, and write unit tests for them.',
  options: {
    auth: accessTokenFromEnv(),
    allowedTools: ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash'],
    permissionMode: 'acceptEdits',  // Auto-approve file edits
  },
})) {
  if (message.type === 'assistant') {
    for (const block of message.message.content) {
      if (block.type === 'text') {
        console.log(block.text);              // AI text response
      } else if (block.type === 'tool_use') {
        console.log(`Tool: ${block.name}`);   // Tool being called
      }
    }
  } else if (message.type === 'result') {
    console.log(`Done: ${message.subtype}`);  // Final result
  }
}
运行： 
node agent.mjs
Agent 会自主浏览项目、找到缺少测试覆盖的函数、生成测试文件并运行验证。

下一步