Copy

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 @qoder-ai/qoder-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.com/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 qodercli credentials, see SDK Authentication. Once you have a PAT, set the environment variable first:

export QODER_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 '@qoder-ai/qoder-agent-sdk';

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

The SDK reads this environment variable before starting qodercli 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.

Single-message and streaming input

Both SDKs use query() as the core entry point. When prompt is a string, one call submits one user message, and the SDK closes the session after the turn completes—ideal for one-off, stateless tasks. To send multiple messages in the same session and choose the next step from a response, pass an async message stream to TypeScript query() or maintain a long-lived connection with Python QoderSDKClient. See Input Modes.

Complete Example

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

import { accessTokenFromEnv, query } from '@qoder-ai/qoder-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
Input Modes — Single-message and streaming input, multi-message sessions, and session closure
Approval and User Input — Tool approval, permission modes, and AskUserQuestion
Streaming Output — Receive incremental content in real time, typewriter effect
SDK References — Complete SDK reference

​Prerequisites

​Install

​Authentication

​Single-message and streaming input