Quickstart - AI Coding Assistant Lingma - Alibaba Cloud ドキュメントセンター

5 つのステップで初めての Qoder Cloud Agent を実行します。トークンの取得、環境の選択、エージェントの作成、セッションの作成、メッセージの送受信を行います。必要なのは curl だけで、SDK のインストールは不要です。

前提条件

Qoder アカウント
ターミナル環境 (macOS、Linux、または WSL)
curl および jq (オプション、JSON 出力の整形用)

Windows ユーザー向け: このドキュメントのコマンドは bash 構文を使用しています。Git for Windows に同梱の Git Bash、または WSL (wsl --install でインストール) の使用を推奨します。PowerShell を使用する場合は、コマンドを適宜変更する必要があります。環境変数は $env:QODER_PAT="your-token" で設定し、PowerShell の curl エイリアスを回避するために curl.exe を使用し、jq を別途インストールします (例: winget install jqlang.jq)。

ステップ1：PAT の取得

Qoder Console にサインインします。
[Settings] > [Personal Access Tokens] に移動します。
[Create Token] をクリックし、名前と有効期限を設定します。
トークンをコピーし、環境変数として設定します。

export QODER_PAT="your-token-here"

トークンは作成時に一度しか表示されません。すぐに安全な場所に保存してください。利便性のために、export コマンドを ~/.bashrc や ~/.zshrc などのシェルの起動ファイルに追加することをお勧めします。

ステップ2：環境の選択

利用可能な環境を一覧表示して、環境 ID を取得します。

curl -s https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" | jq .

レスポンスで "data": [] (空の配列) が返された場合、アカウントにはまだ環境がありません。次のように作成します。

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name": "default", "config": {"type": "cloud", "networking": {"type": "unrestricted"}}}' | jq .

ステップ3：エージェントの作成

シェルツールを備えた汎用エージェントを定義します。

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quickstart-agent",
    "model": "ultimate",
    "instructions": "You are a helpful coding assistant.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ]
  }' | jq .

レスポンスの id フィールド (例: agent_019e...) を控えておいてください。次のステップでセッションを作成する際に必要になります。

ステップ4：セッションの作成

セッションの作成には、agent (エージェント ID またはオブジェクト) と environment_id (環境 ID) の 2 つのパラメーターが必要です。

エージェントを環境にバインドして、実行中のインスタンスを作成します。

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_YOUR_AGENT_ID",
    "environment_id": "env_YOUR_ENV_ID"
  }' | jq .

作成後、セッションは idle 状態になります。エージェントは、次のステップでメッセージを送信した後にのみ実行を開始します。

ステップ5：メッセージの送信とイベントの受信

セッションにユーザーメッセージを送信し、SSE ストリームからエージェントのレスポンスをリアルタイムで受信します。

# メッセージの送信
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_YOUR_SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user.message",
    "content": [{"type": "text", "text": "Write a Python function that calculates fibonacci numbers"}]
  }'

# SSE イベントストリームの受信
curl -sN "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_YOUR_SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_PAT"

API は、接続を維持するために、約 15 秒ごとに heartbeat イベントを送信します。content フィールドは、agent.message イベントでは配列形式 [{"type":"text","text":"..."}] を使用します。

よくある質問

Q: 401 Unauthorized エラーが発生した場合はどうすればよいですか?

A: $QODER_PAT 環境変数が正しく設定されていること、およびトークンの有効期限が切れていないことを確認してください。必要に応じて、新しいトークンを作成し、環境変数を更新してください。

Q: エージェントの作成時に 400 Bad Request エラーが発生するのはなぜですか?

A: リクエストボディが有効な JSON であること、model フィールドが有効な値 (例: "ultimate") であること、および tools フィールドが配列であることを確認してください。

Q: セッションがアイドル状態のままで、イベントを受信しないのはなぜですか?

A：セッションは作成後、デフォルトで idle 状態です。エージェントをトリガーするには、user.message イベントを送信する必要があります。手順 5 が正しく実行されていることを確認してください。

Q: SSE ストリーム接続が中断された場合はどうすればよいですか?

A: 切断前に受信した最後のイベントの id (例: evt_...) を保存することをお勧めします。再接続する際は、?after_id=<last_event_id> クエリパラメーターを含めてください。そうすることで、サーバーは中断したところからイベントの送信を再開します。

Q: GET /environments が空の配列を返すのはなぜですか?

A: 新しいアカウントには、事前構成された環境がない場合があります。ステップ 2 の説明に従って環境を作成してください。