> ## 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 エージェントをアプリケーションやスクリプトに組み込めます。

<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 認証](/ja/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 を起動する前にこの環境変数を読み取り、解析済みのアクセストークンを一回限りの auth payload に書き込みます。通常、`env` オプションで PAT を渡す必要はありません。`options.env` を明示的に指定した場合、SDK はそちらから同名の変数を優先的に読み取ります。

> **セキュリティに関する注意**: PAT をコードリポジトリにハードコードしないでください。環境変数またはシークレット管理サービスを通じて注入することを推奨します。

<div id="query-と-qodersdkclient-の選択" />

<div id="queryとqodersdkclientの選択" />

## `query()` と `QoderSDKClient` の選択

| シナリオ                             | 使うもの             | 理由                            |
| -------------------------------- | ---------------- | ----------------------------- |
| 一回限りでステートレスなタスク (単一プロンプト → 結果取得) | `query()`        | 非同期ジェネレータ、即座に呼び出し可能、プロセス終了で完了 |
| マルチターン会話、応答に基づいて次の手順を決定          | `QoderSDKClient` | 永続接続、ステートフル                   |

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

<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" />

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

エージェントは自律的にプロジェクトを探索し、テストカバレッジが不足している関数を見つけ、テストファイルを生成して検証を実行します。

<div id="次のステップ" />

## 次のステップ

* [SDK 認証](/ja/cli/sdk/python/authentication) — PAT、環境変数、認証エラーハンドリング
* [マルチターン会話](/ja/cli/sdk/python/multi-turn-conversation) — マルチメッセージセッション、セッションライフサイクルの管理
* [ストリーミング出力](/ja/cli/sdk/python/streaming-output) — 増分コンテンツのリアルタイム受信、タイプライター効果
* [Hooks](/ja/cli/sdk/python/hooks) と [パーミッション制御](/ja/cli/sdk/python/permissions) — エージェントループ内でツール呼び出しを傍受・承認