クイックスタート

5 つのステップで最初の Qoder Cloud Agent を動かしましょう：トークンの取得、環境の選択、Agent の作成、Session の作成、メッセージの送受信。全工程 curl のみで完結し、SDK のインストールは不要です。

前提条件

Qoder アカウント
ターミナル環境（macOS / Linux / WSL）
curl および jq（オプション、JSON の整形に使用）

Windows ユーザー

本ガイドのコマンドは bash 構文を使用しています。Windows ユーザーは以下のいずれかをご利用ください：

Git Bash（推奨）：Git for Windows に同梱
WSL：wsl --install でインストール

PowerShell を使用する場合は、以下の違いにご注意ください：

環境変数の設定：$env:QODER_PAT="your-token"（export ではなく）
実際の curl を呼び出す：curl.exe を使用（PowerShell の curl は Invoke-WebRequest のエイリアス）
jq は別途インストール：winget install jqlang.jq

ステップ 1：PAT を取得する

Qoder コンソールにサインインします。
「設定 → 個人アクセストークン」を開きます。
「トークン作成」をクリックし、名前と有効期限を設定します。
トークンをコピーし、環境変数として設定します：

export QODER_PAT="your-personal-access-token"

トークンは作成時に一度だけ表示されます。すぐに保存してください。~/.bashrc または ~/.zshrc に追記することを推奨します。

ステップ 2：環境を選択する

利用可能な環境の一覧を取得し、環境 ID を確認します：

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

レスポンス例：

{
  "data": [
    {
      "id": "env_019e44eb66bb748cabcd1489f6fa4428",
      "type": "environment",
      "name": "default",
      "description": "",
      "config": {
        "type": "cloud",
        "networking": {
          "type": "unrestricted",
          "allowed_hosts": [],
          "allow_package_managers": false,
          "allow_mcp_servers": false
        },
        "packages": {
          "type": "packages",
          "apt": [],
          "npm": [],
          "pip": []
        }
      },
      "metadata": {},
      "archived_at": null,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "first_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "last_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "has_more": false,
  "next_page": null
}

レスポンスが "data": []（空配列）の場合、アカウントにまだ環境がありません。先に環境を作成してください：

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

# 環境 ID を抽出（jq を使うことで長い ID の手動コピーによるミスを防ぎます）
ENV_ID=$(curl -s https://api.qoder.com/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" | jq -r '.data[0].id')

echo "環境 ID: $ENV_ID"

ステップ 3：Agent を作成する

シェルツールを備えた汎用 Agent を定義します：

AGENT_RESPONSE=$(curl -s -X POST https://api.qoder.com/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "model": "ultimate",
    "system": "あなたは効率的なプログラミングアシスタントです。コード作成と問題のトラブルシューティングを得意としています。",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ]
  }')
echo "$AGENT_RESPONSE" | jq .
AGENT_ID=$(echo "$AGENT_RESPONSE" | jq -r '.id')
echo "Agent ID: $AGENT_ID"

レスポンス例：

{
  "id": "agent_019e451902fe7a2ca42c2dfc62d9320e",
  "type": "agent",
  "name": "my-first-agent",
  "description": "",
  "model": "ultimate",
  "system": "あなたは効率的なプログラミングアシスタントです。コード作成と問題のトラブルシューティングを得意としています。",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ],
  "mcp_servers": [],
  "skills": [],
  "metadata": {},
  "multiagent": null,
  "version": 1,
  "archived_at": null,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

ステップ 4：Session を作成する

Session の作成には 2 つの必須パラメータが必要です：agent（Agent ID またはオブジェクト）と environment_id（Environment ID）。 Agent を環境にバインドし、ランタイムインスタンスを作成します：

SESSION_RESPONSE=$(curl -s -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent\": \"$AGENT_ID\",
    \"environment_id\": \"$ENV_ID\"
  }")
echo "$SESSION_RESPONSE" | jq .
SESSION_ID=$(echo "$SESSION_RESPONSE" | jq -r '.id')
echo "Session ID: $SESSION_ID"

レスポンス例：

{
  "id": "sess_019e451b146470cda02c560bf019fb37",
  "type": "session",
  "agent": {
    "id": "agent_019e451902fe7a2ca42c2dfc62d9320e",
    "type": "agent",
    "name": "my-first-agent",
    "model": {"id": "ultimate", "effective_context_window": 200000},
    "version": 1
  },
  "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "status": "idle",
  "title": null,
  "metadata": {},
  "resources": [],
  "vault_ids": [],
  "deployment_id": null,
  "outcome_evaluations": [],
  "stats": {"active_seconds": 0, "duration_seconds": 0},
  "environment_variables": {},
  "archived_at": null,
  "created_at": "2026-05-18T10:01:00Z",
  "updated_at": "2026-05-18T10:01:00Z"
}

Session は作成直後は idle 状態です。次のステップでメッセージを送信して初めて Agent が実行を開始します。

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

Session にユーザーメッセージを送信し、SSE ストリームで Agent のレスポンスをリアルタイムに受信します：

# メッセージを送信（注意：リクエストボディは events 配列でラップします）
curl -s -X POST "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [{"type": "text", "text": "Python でフィボナッチ数列を計算する関数を書いて、テストを実行してください。"}]
      }
    ]
  }' | jq .

# SSE ストリームでイベントをリアルタイム受信
curl -s -N "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_PAT"

イベントストリームの出力例：

id: evt_019ef515680d7a0ebd3160ca45ec5484
event: user.message
data: {"content":[{"text":"Python でフィボナッチ数列を計算する関数を書いて、テストを実行してください。","type":"text"}],"id":"evt_019ef515680d7a0ebd3160ca45ec5484","processed_at":"2026-06-23T15:24:41.357659669Z","type":"user.message"}

id: evt_019ef515681a7c52a0b45aa87625f121
event: session.status_running
data: {"id":"evt_019ef515681a7c52a0b45aa87625f121","processed_at":"2026-06-23T15:24:41.357659669Z","type":"session.status_running"}

event: heartbeat
data: {}

id: evt_49dce735a4ab4fc4
event: agent.thinking
data: {"id":"evt_49dce735a4ab4fc4","processed_at":"2026-06-23T15:24:49.357659Z","type":"agent.thinking"}

id: evt_02f80c5a8c245e04
event: agent.message
data: {"content":[{"text":"フィボナッチ関数と包括的なテストを含む Python モジュールを作成します。","type":"text"}],"id":"evt_02f80c5a8c245e04","processed_at":"2026-06-23T15:24:49.357659Z","type":"agent.message"}

id: evt_50739b167fb7c6d3
event: agent.tool_use
data: {"evaluated_permission":"allow","id":"evt_50739b167fb7c6d3","input":{"content":"def fibonacci(n): ...","file_path":"/data/fibonacci.py"},"name":"Write","processed_at":"2026-06-23T15:24:49.357659Z","type":"agent.tool_use"}

id: evt_e7c375f3605ff156
event: agent.tool_result
data: {"content":[{"text":"Write file /data/fibonacci.py successfully","type":"text"}],"id":"evt_e7c375f3605ff156","is_error":false,"processed_at":"2026-06-23T15:25:01.853844Z","type":"agent.tool_result"}

id: evt_60eba1483797a419
event: session.status_idle
data: {"id":"evt_60eba1483797a419","processed_at":"2026-06-23T15:25:24.436729Z","stop_reason":{"type":"end_turn"},"type":"session.status_idle"}

heartbeat を除くすべてのイベントには id: 行があり、JSON ペイロードには id、type、processed_at フィールドが含まれます。
heartbeat イベントは約 15 秒ごとに送信され、接続を維持します。
agent.message の content フィールドは [{"type":"text","text":"..."}] の配列形式を使用します。
session.status_running / session.status_idle は id、type、processed_at（idle の場合は stop_reason も）以外のフィールドを持ちません。
agent.thinking はモデルが推論中であることを示しますが、content や text フィールドは含みません。

エンドツーエンドスクリプト

上記の全ステップを 1 つの実行可能なスクリプトにまとめたものです：

#!/bin/bash
# Qoder Cloud Agents クイックスタートスクリプト
# 使用方法：export QODER_PAT="your-token" && bash quickstart.sh

set -euo pipefail

BASE_URL="https://api.qoder.com/api/v1/cloud"
HEADERS=(
  -H "Authorization: Bearer $QODER_PAT"
)

echo "=== ステップ 1：環境を取得 ==="
ENV_ID=$(curl -s "$BASE_URL/environments" "${HEADERS[@]}" | jq -r '.data[0].id')
if [ "$ENV_ID" = "null" ] || [ -z "$ENV_ID" ]; then
  echo "環境が見つかりません。デフォルト環境を作成します..."
  ENV_ID=$(curl -s -X POST "$BASE_URL/environments" \
    "${HEADERS[@]}" \
    -H "Content-Type: application/json" \
    -d '{"name":"default","config":{"type":"cloud","networking":{"type":"unrestricted"}}}' | jq -r '.id')
fi
echo "環境 ID: $ENV_ID"

echo "=== ステップ 2：Agent を取得または作成 ==="
AGENT_ID=$(curl -s "$BASE_URL/agents" "${HEADERS[@]}" | jq -r '.data[0].id')
if [ "$AGENT_ID" = "null" ] || [ -z "$AGENT_ID" ]; then
  AGENT_ID=$(curl -s -X POST "$BASE_URL/agents" \
    "${HEADERS[@]}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "quickstart-agent",
      "model": "ultimate",
      "system": "あなたは効率的なプログラミングアシスタントです。",
      "tools": [
        {
          "type": "agent_toolset_20260401",
          "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
        }
      ]
    }' | jq -r '.id')
fi
echo "Agent ID: $AGENT_ID"

echo "=== ステップ 3：Session を作成 ==="
SESSION_ID=$(curl -s -X POST "$BASE_URL/sessions" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d "{\"agent\": \"$AGENT_ID\", \"environment_id\": \"$ENV_ID\"}" | jq -r '.id')
echo "Session ID: $SESSION_ID"

echo "=== ステップ 4：メッセージを送信 ==="
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "user.message", "content": [{"type": "text", "text": "Hello World を出力し、現在のシステム時刻を教えてください。"}]}
    ]
  }' | jq .

echo "=== ステップ 5：イベントストリームを受信 ==="
echo "（Ctrl+C で終了）"
curl -s -N "$BASE_URL/sessions/$SESSION_ID/events/stream" "${HEADERS[@]}"

よくある質問

Q: 401 Unauthorized エラーが表示されます。 A: $QODER_PAT が正しく設定されているか、トークンが期限切れになっていないか確認してください。トークンを再作成し、環境変数を更新してください。 Q: Agent の作成で 400 Bad Request が返されます。 A: リクエスト JSON の形式を確認してください。model フィールドは有効な値（例："ultimate"）である必要があり、tools は配列でなければなりません。 Q: Session が idle のままでイベントが受信できません。 A: Session は作成直後は idle 状態です。Agent の実行を開始するには、user.message イベントを送信する必要があります（ステップ 5）。 Q: SSE ストリームの接続が切断されました。 A: ストリームエンドポイントは Last-Event-ID ヘッダーによる再接続リプレイをサポートしています。最後に受信したイベントの id をリクエストヘッダーに含めると、そのイベント以降からストリームが再開されます。イベントタイプによるクエリフィルターは現在サポートされていません。 Q: GET /api/v1/cloud/environments が空配列を返します。 A: 新しいアカウントには事前にプロビジョニングされた環境がない場合があります。ステップ 2 のヒントに従って手動で環境を作成してください。

次のステップ

Agent の定義

Agent 設定の全フィールドを確認する。

クラウド環境設定

実行環境をカスタマイズする。

Session の開始

セッション管理の詳細。

Agent スキル

Agent にドメイン専門知識を付与し、タスクのパフォーマンスを向上させる。

​前提条件

​ステップ 1：PAT を取得する

​ステップ 2：環境を選択する

​ステップ 3：Agent を作成する

​ステップ 4：Session を作成する

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

​エンドツーエンドスクリプト

​よくある質問

​次のステップ

Agent の定義

クラウド環境設定

Session の開始

Agent スキル

前提条件

ステップ 1：PAT を取得する

ステップ 2：環境を選択する

ステップ 3：Agent を作成する

ステップ 4：Session を作成する

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

エンドツーエンドスクリプト

よくある質問

次のステップ