クイックスタート - - Alibaba Cloud ドキュメントセンター

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

重要

新しい Qoder CN のドキュメントサイトが利用可能になりました。このサイトのコンテンツは、最新の製品機能や変更点を反映していない場合があります。最新の製品ドキュメントについては、docs.qoder.cn をご覧ください。

前提条件

Qoder アカウント
ターミナル環境 (macOS、Linux、または WSL)
curl と jq (任意、JSON 出力のフォーマット用)

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

ステップ 1：PAT の取得

Qoder コンソールにサインインします。
[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 イベントを送信します。 agent.message イベントの content フィールドは、配列形式 [{"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 の説明に従って作成してください。