Quick Start - Qoder CN

Qoder Agent SDK lets you call Qoder AI capabilities from TypeScript or Python—reading and writing files, searching code, running commands, and more—embedding an AI agent into your app or script with just a few lines of code.

Prerequisites

TypeScript: Node.js 18+
Python: Python 3.10+

Install

npm install @qodercn-ai/qodercn-agent-sdk

Authentication

The SDK authenticates via a Personal Access Token (PAT), ideal for scripts, CI pipelines, and third-party integration scenarios. Generate a PAT at qoder.cn/account/integrations (copy it immediately — the value cannot be retrieved again after the page is closed). For full steps, custom environment variables, and reusing local qoderclicn credentials, see SDK Authentication. Once you have a PAT, set the environment variable first:

export QODERCN_PERSONAL_ACCESS_TOKEN="<your-qoder-personal-access-token>"
node agent.mjs

Then configure authentication with accessTokenFromEnv() (TypeScript) / access_token_from_env() (Python):

import { accessTokenFromEnv, query } from '@qodercn-ai/qodercn-agent-sdk';

const stream = query({
  prompt: 'Hello',
  options: {
    auth: accessTokenFromEnv(),
  },
});

The SDK reads this environment variable before starting qoderclicn and writes the parsed access token into a one-time auth payload. You typically don't need to pass the PAT via the env option; if options.env is explicitly provided, the SDK reads the same-named variable from it first.

Security Note: Do not hard-code PATs in your code repository. Inject them via environment variables or a secrets management service.

One-shot query vs multi-turn conversation

Both SDKs use query() as the core entry point: submit one user message, and the SDK closes the session after the turn completes—ideal for one-off, stateless tasks. To send multiple messages within the same session and decide the next step based on responses: TypeScript passes an async message stream to query(); Python uses QoderSDKClient to maintain a long-lived connection. See Multi-turn conversation.

Complete Example

Create agent.mjs (TypeScript) or agent.py (Python):

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
  }
}

Run it:

node agent.mjs

The Agent will autonomously browse the project, find functions lacking test coverage, generate test files, and run them for verification.

Next Steps

SDK Authentication — PAT, environment variables, and auth error handling
Multi-turn Conversation — Multi-message session, managing the session lifecycle
Streaming Output — Receive incremental content in real time, typewriter effect
SDK References — Complete SDK reference

​Prerequisites

​Install

​Authentication

​One-shot query vs multi-turn conversation