Skip to content

Commit 43e7294

Browse files
wenxinaxwenxinax
committed
feat: add Qoder Agent SDK samples
Add TypeScript and Python examples covering core SDK workflows, model interaction, hooks, tools, permissions, and subagents.
0 parents  commit 43e7294

77 files changed

Lines changed: 7278 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
name: Sample bug report
2+
description: Report a sample that fails to run, is unclear, or drifts from current SDK behavior.
3+
title: "[bug] <sample>: <short summary>"
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for the report. This tracker is for the **samples** in this
10+
repository. For questions about the SDK itself, see the
11+
[Qoder Agent SDK documentation](https://docs.qoder.com/en/cli/sdk).
12+
- type: input
13+
id: sample
14+
attributes:
15+
label: Sample
16+
description: Which sample is affected?
17+
placeholder: quickstart
18+
validations:
19+
required: true
20+
- type: dropdown
21+
id: language
22+
attributes:
23+
label: Language
24+
options:
25+
- TypeScript
26+
- Python
27+
- Both
28+
validations:
29+
required: true
30+
- type: input
31+
id: sdk-version
32+
attributes:
33+
label: SDK version
34+
description: The installed SDK version.
35+
placeholder: "TypeScript 1.0.15 / Python 1.0.9"
36+
validations:
37+
required: true
38+
- type: textarea
39+
id: command
40+
attributes:
41+
label: Command run
42+
description: The exact command you ran.
43+
render: bash
44+
placeholder: npm start -- /path/to/repository
45+
validations:
46+
required: true
47+
- type: textarea
48+
id: expected
49+
attributes:
50+
label: Expected behavior
51+
validations:
52+
required: true
53+
- type: textarea
54+
id: actual
55+
attributes:
56+
label: Actual behavior and output
57+
description: What happened, including any error output. Do not include credentials or tokens.
58+
validations:
59+
required: true
60+
- type: textarea
61+
id: environment
62+
attributes:
63+
label: Environment
64+
description: OS, and Node.js or Python version.
65+
placeholder: "macOS 14, Node.js 20.11 / Python 3.12"
66+
validations:
67+
required: false

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Qoder Agent SDK documentation
4+
url: https://docs.qoder.com/en/cli/sdk
5+
about: Questions about the SDK itself (not these samples) are answered in the SDK docs.
6+
- name: Qoder CLI
7+
url: https://qoder.com/cli
8+
about: Product information and downloads for the Qoder CLI.

‎.github/ISSUE_TEMPLATE/new_sample.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: New sample proposal
2+
description: Propose a new sample before writing code, so the concept and scope are agreed first.
3+
title: "[sample] <proposed name>"
4+
labels: ["new-sample"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
New samples are welcome. Please propose the idea here first so we can
10+
agree on scope. See `CONTRIBUTING.md` for the sample requirements and the
11+
steps to add one.
12+
- type: input
13+
id: name
14+
attributes:
15+
label: Proposed sample name
16+
description: Kebab-case, matching the directory name.
17+
placeholder: streaming-tool-use
18+
validations:
19+
required: true
20+
- type: textarea
21+
id: concept
22+
attributes:
23+
label: SDK concept demonstrated
24+
description: The single primary SDK concept this sample teaches.
25+
validations:
26+
required: true
27+
- type: textarea
28+
id: why
29+
attributes:
30+
label: Why it's useful
31+
description: What a reader learns and why it isn't already covered by an existing sample.
32+
validations:
33+
required: true
34+
- type: textarea
35+
id: outline
36+
attributes:
37+
label: Outline
38+
description: The prompt or flow, the tools/permissions used, and any inputs the sample needs.
39+
validations:
40+
required: false
41+
- type: checkboxes
42+
id: parity
43+
attributes:
44+
label: Requirements
45+
options:
46+
- label: I plan to provide both TypeScript and Python versions with equivalent behavior.
47+
required: true
48+
- label: The sample uses only public SDK exports and the smallest practical tool set.
49+
required: true

‎.github/workflows/ci.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
typescript:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
- uses: actions/setup-node@v4
17+
with:
18+
node-version: 20
19+
cache: npm
20+
cache-dependency-path: typescript/package-lock.json
21+
- run: npm ci
22+
working-directory: typescript
23+
- run: npm run check --workspaces
24+
working-directory: typescript
25+
26+
python:
27+
runs-on: ubuntu-latest
28+
steps:
29+
- uses: actions/checkout@v4
30+
- uses: actions/setup-python@v5
31+
with:
32+
python-version: "3.12"
33+
- uses: astral-sh/setup-uv@v6
34+
- run: uv sync
35+
working-directory: python
36+
- run: uv run ruff check .
37+
working-directory: python
38+
- run: uv run ruff format --check .
39+
working-directory: python
40+
- name: Type-check samples
41+
run: |
42+
for sample in quickstart multi-turn-conversation streaming-chat code-review tool-permissions ask-user-question model-selection hooks custom-tools subagents; do
43+
uv run mypy "$sample/main.py"
44+
done
45+
working-directory: python

‎.gitignore‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# OS
2+
.DS_Store
3+
4+
# Secrets
5+
.env
6+
.env.*
7+
!.env.example
8+
9+
# Node / TypeScript
10+
node_modules/
11+
dist/
12+
*.tsbuildinfo
13+
14+
# Python
15+
.venv/
16+
venv/
17+
env/
18+
.checkenv/
19+
__pycache__/
20+
*.py[cod]
21+
.mypy_cache/
22+
.pytest_cache/
23+
.ruff_cache/
24+
25+
# Editors
26+
.idea/
27+
.vscode/

‎CONTRIBUTING.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Contributing
2+
3+
Thanks for helping improve the Qoder Agent SDK samples. This repository is a set
4+
of focused, runnable examples, so contributions are judged first on clarity: a
5+
reader should be able to open one sample and understand a single SDK concept.
6+
7+
## Ways to contribute
8+
9+
- **Report a problem.** Open an issue if a sample fails to run, is unclear, or
10+
drifts from current SDK behavior. Include the sample, language, SDK version,
11+
and the exact command and output.
12+
- **Improve docs.** Fix or clarify READMEs, comments, and diagrams.
13+
- **Add a new sample.** New samples are welcome. Please open an issue first to
14+
agree on the concept and scope before writing code, so your effort lands.
15+
16+
Issues about the SDK itself (rather than these samples) belong in the
17+
[Qoder Agent SDK documentation](https://docs.qoder.com/en/cli/sdk) channels, not
18+
this repository.
19+
20+
## Development setup
21+
22+
- TypeScript: Node.js 18 or later. From `typescript/`, run `npm install` to
23+
install every sample workspace, then `npm start` inside a sample directory.
24+
- Python: Python 3.10 or later. Each sample runs from its own virtual
25+
environment (see the sample README). Maintainer checks use
26+
[`uv`](https://docs.astral.sh/uv/); contributors do not need `uv` to run a
27+
sample.
28+
29+
## Sample requirements
30+
31+
Every sample must:
32+
33+
- Demonstrate one primary SDK concept.
34+
- Ship in both TypeScript and Python with equivalent behavior.
35+
- Use only public exports from the released SDK package.
36+
- Use a documented SDK authentication helper and never hard-code credentials.
37+
- Never log credentials or accept them as command-line arguments.
38+
- Default to the smallest practical tool set and permission scope.
39+
- Include a README with prerequisites, setup, run commands, and safety notes.
40+
- Avoid shared source modules that hide the SDK calls being demonstrated.
41+
- Keep generated files and expected model output out of the sample directory.
42+
43+
## Adding a new sample
44+
45+
Use an existing sample (for example, `quickstart`) as a template, then register
46+
the new sample everywhere it needs to appear. Replace `<sample>` with your
47+
kebab-case sample name.
48+
49+
1. **Create the TypeScript sample** at `typescript/<sample>/` with `index.ts`,
50+
`README.md`, and `package.json`. Copy `package.json` from an existing sample
51+
and update the `name` field to `@qoder-samples/typescript-<sample>`.
52+
2. **Create the Python sample** at `python/<sample>/` with `main.py`,
53+
`README.md`, and `requirements.txt`.
54+
3. **Register the TypeScript workspace:** add `<sample>` to the `workspaces`
55+
array in `typescript/package.json`.
56+
4. **Register the Python type check:** add `<sample>` to the `for sample in ...`
57+
loop in `.github/workflows/ci.yml` and to the matching loop in this file.
58+
5. **List it in both READMEs:** add a row to the sample table in `README.md` and
59+
in `README.zh-CN.md`.
60+
61+
Keep the TypeScript and Python versions behaviorally equivalent so readers can
62+
switch between languages.
63+
64+
## Running the checks
65+
66+
Run the same checks CI runs, and make sure they pass before opening a pull
67+
request:
68+
69+
```bash
70+
cd typescript && npm ci && npm run check --workspaces
71+
cd ../python && uv sync && uv run ruff check . && uv run ruff format --check .
72+
for sample in quickstart multi-turn-conversation streaming-chat code-review tool-permissions ask-user-question model-selection hooks custom-tools subagents; do
73+
uv run mypy "$sample/main.py"
74+
done
75+
```
76+
77+
If `ruff format --check` reports changes, run `uv run ruff format .` to apply
78+
them.
79+
80+
## Pull requests
81+
82+
- Keep each pull request focused on one sample or one concern.
83+
- Explain what the sample demonstrates and how you verified it.
84+
- Ensure CI is green; pull requests are not merged with failing checks.
85+
86+
## Contributor terms
87+
88+
By submitting a pull request, you agree that your contribution is provided under
89+
the repository's [MIT License](LICENSE) and that you have the right to submit it.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Qoder
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Qoder Agent SDK Samples
2+
3+
Runnable, focused examples for building applications with the Qoder Agent SDK.
4+
Every sample is available in TypeScript and Python.
5+
6+
## Samples
7+
8+
| Sample | What it demonstrates | TypeScript | Python |
9+
| --- | --- | --- | --- |
10+
| Quickstart | Run one repository-aware query and handle the result | [Open](typescript/quickstart) | [Open](python/quickstart) |
11+
| Multi-turn conversation | Control the query lifecycle and resume context after closing | [Open](typescript/multi-turn-conversation) | [Open](python/multi-turn-conversation) |
12+
| Streaming chat | Stream output while keeping one live session open | [Open](typescript/streaming-chat) | [Open](python/streaming-chat) |
13+
| Code review | Review a Git diff with read-only repository tools | [Open](typescript/code-review) | [Open](python/code-review) |
14+
| Tool permissions | Separate tool visibility, pre-approval, and runtime authorization | [Open](typescript/tool-permissions) | [Open](python/tool-permissions) |
15+
| Ask user question | Render structured questions and return user answers | [Open](typescript/ask-user-question) | [Open](python/ask-user-question) |
16+
| Model selection | List models and select context-window and reasoning parameters | [Open](typescript/model-selection) | [Open](python/model-selection) |
17+
| Hooks | Add lifecycle observation, context injection, and tool policy | [Open](typescript/hooks) | [Open](python/hooks) |
18+
| Custom tools | Expose application functions as in-process MCP tools | [Open](typescript/custom-tools) | [Open](python/custom-tools) |
19+
| Subagents | Delegate a task to specialized SDK-defined agents | [Open](typescript/subagents) | [Open](python/subagents) |
20+
21+
## Setup
22+
23+
These samples read a Personal Access Token from the environment. See
24+
[SDK Authentication](https://docs.qoder.com/en/cli/sdk/authentication) for the
25+
setup and other supported authentication methods.
26+
27+
```bash
28+
export QODER_PERSONAL_ACCESS_TOKEN="<your-token>"
29+
```
30+
31+
For the complete API guide, see the
32+
[Qoder Agent SDK documentation](https://docs.qoder.com/en/cli/sdk).
33+
34+
## Prerequisites
35+
36+
- TypeScript samples: Node.js 18 or later
37+
- Python samples: Python 3.10 or later
38+
- Qoder authentication configured as described above
39+
40+
Each sample is self-contained. Open its README for installation and run
41+
commands.
42+
43+
## Compatibility
44+
45+
The sample manifests declare compatible SDK version ranges, while the
46+
repository lockfiles record the exact versions used by CI.
47+
48+
Last verified on July 20, 2026:
49+
50+
- TypeScript SDK 1.0.15
51+
- Python SDK 1.0.9
52+
53+
## License and terms
54+
55+
The sample source code is licensed under the [MIT License](LICENSE). Use of the
56+
Qoder Agent SDK and Qoder services is governed by the
57+
[Qoder Product Service Terms](https://qoder.com/product-service).

0 commit comments

Comments
 (0)