> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始

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

<div id="前置条件" />

## 前置条件

* Python 3.10+

<div id="安装" />

## 安装

```bash theme={null}
pip install qoder-agent-sdk
```

<div id="认证" />

## 认证

SDK 通过 Personal Access Token (PAT) 认证身份，适用于脚本、CI 流水线和第三方集成场景。

到 [qoder.com/account/integrations](https://qoder.com/account/integrations) 生成 PAT（生成后立即复制，页面关闭后无法再次查看）。详细步骤、自定义环境变量、复用本机 `qodercli` 登录态等，见 [SDK 认证](/zh/cli/sdk/python/authentication)。

拿到 PAT 后，推荐先设置环境变量：

```bash theme={null}
export QODER_PERSONAL_ACCESS_TOKEN="<your-qoder-personal-access-token>"
python agent.py
```

然后用 `access_token_from_env()` 配置认证：

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, access_token_from_env, query

options = QoderAgentOptions(auth=access_token_from_env())

async for message in query(prompt="Hello", options=options):
    print(message)
```

SDK 会在启动 qodercli 前读取该环境变量，并把解析后的 access token 写入一次性的 auth payload。通常不需要再通过 `env` 选项传 PAT；如果显式提供了 `options.env`，SDK 会优先从其中读取同名变量。

> **安全提示**：不要把 PAT 硬编码在代码仓库中。推荐通过环境变量或密钥管理服务注入。

<div id="选择-query-还是-qodersdkclient" />

<div id="选择query还是qodersdkclient" />

## 选择 `query()` 还是 `QoderSDKClient`

| 场景                         | 用                | 为什么               |
| -------------------------- | ---------------- | ----------------- |
| 一次性、无状态的任务（单 prompt → 拿结果） | `query()`        | 异步生成器，调用即用，进程结束即了 |
| 多轮对话、根据回复决定下一步             | `QoderSDKClient` | 长连接、有状态           |

<div id="最小示例query" />

### 最小示例：`query()`

```python theme={null}
import anyio

from qoder_agent_sdk import (
    AssistantMessage,
    QoderAgentOptions,
    TextBlock,
    access_token_from_env,
    query,
)


async def main():
    options = QoderAgentOptions(auth=access_token_from_env())

    async for msg in query(prompt="What is 2 + 2?", options=options):
        if isinstance(msg, AssistantMessage):
            for block in msg.content:
                if isinstance(block, TextBlock):
                    print(block.text)


anyio.run(main)
```

<div id="最小示例qodersdkclient" />

### 最小示例：`QoderSDKClient`

```python theme={null}
import anyio

from qoder_agent_sdk import (
    AssistantMessage,
    QoderAgentOptions,
    QoderSDKClient,
    TextBlock,
    access_token_from_env,
)


async def main():
    options = QoderAgentOptions(auth=access_token_from_env())

    async with QoderSDKClient(options=options) as client:
        await client.query("What's the capital of France?")
        async for msg in client.receive_response():
            if isinstance(msg, AssistantMessage):
                for block in msg.content:
                    if isinstance(block, TextBlock):
                        print(block.text)

        # Decide the next turn from what we just heard
        await client.query("What's the population of that city?")
        async for msg in client.receive_response():
            if isinstance(msg, AssistantMessage):
                for block in msg.content:
                    if isinstance(block, TextBlock):
                        print(block.text)


anyio.run(main)
```

<div id="完整示例" />

## 完整示例

创建 `agent.py`：

```python theme={null}
import anyio

from qoder_agent_sdk import (
    AssistantMessage,
    QoderAgentOptions,
    ResultMessage,
    TextBlock,
    ToolUseBlock,
    access_token_from_env,
    query,
)


async def main():
    options = QoderAgentOptions(
        auth=access_token_from_env(),
        allowed_tools=["Read", "Write", "Edit", "Glob", "Grep", "Bash"],
        permission_mode="acceptEdits",  # Auto-approve file edits
    )

    async for message in query(
        prompt=(
            "Analyze the codebase, find functions without test coverage, "
            "and write unit tests for them."
        ),
        options=options,
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)              # AI text response
                elif isinstance(block, ToolUseBlock):
                    print(f"Tool: {block.name}")   # Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")      # Final result


anyio.run(main)
```

```bash theme={null}
python agent.py
```

Agent 会自主浏览项目、找到缺少测试覆盖的函数、生成测试文件并运行验证。

<div id="下一步" />

## 下一步

* [SDK 认证](/zh/cli/sdk/python/authentication) — PAT、环境变量和认证错误处理
* [多轮对话](/zh/cli/sdk/python/multi-turn-conversation) — 多消息会话、管理会话生命周期
* [流式输出](/zh/cli/sdk/python/streaming-output) — 实时接收增量内容、打字机效果
* [Hooks](/zh/cli/sdk/python/hooks) 与 [权限控制](/zh/cli/sdk/python/permissions) — 在 agent loop 中拦截、审批工具调用