Skip to main content
はじめに

クイックスタート

5 ステップで最初の Qoder Cloud Agent を動かします。

5 つのステップで最初の Qoder Cloud Agent を動かしましょう：トークンの取得、環境の選択、Agent の作成、Session の作成、メッセージの送受信。全工程 curl のみで完結し、SDK のインストールは不要です。
このガイドでは curl による API 呼び出しを説明します。AI ツールや SDK から Cloud Agents を利用する場合は、先に次の案内を確認してください： 接続方法を選ぶ。

前提条件

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

Windows ユーザー

本ガイドのコマンドは bash 構文を使用しています。Windows ユーザーは以下のいずれかをご利用ください：
  • Git Bash（推奨）：Git for Windows に同梱
  • WSL：wsl --install でインストール
PowerShell を使用する場合は、以下の違いにご注意ください：
  • 環境変数の設定：$env:QODER_ACCESS_TOKEN="your-token"（export ではなく）
  • 実際の curl を呼び出す：curl.exe を使用（PowerShell の curl は Invoke-WebRequest のエイリアス）
  • jq は別途インストール：winget install jqlang.jq

ステップ 1：アクセストークンを取得する

呼び出し元の ID に応じて PAT または SAT を選択します。以降の手順では共通の QODER_ACCESS_TOKEN 環境変数を使用します。 最初にサービスエンドポイントを設定します。SAT の交換と業務 API のリクエストでは、同じリージョンのエンドポイントを使用する必要があります。 
export QODER_OPENAPI_BASE_URL="https://openapi.qoder.sh"
export QODER_API_BASE_URL="https://api.qoder.com"

オプション 1：PAT（個人ユーザー）

  1. Qoder コンソールにサインインします。
  2. 設定 → Personal Access Tokens を開きます。
  3. Token の作成をクリックし、名前と有効期限を設定します。
  4. Token をコピーし、環境変数に設定します。
export QODER_PAT="your-personal-access-token"
export QODER_ACCESS_TOKEN="$QODER_PAT"
PAT は作成時に一度だけ表示されます。すぐに安全な場所へ保存してください。

オプション 2：SAT（Service Account Token）

  1. 組織管理者として Qoder コンソールにサインインします。
  2. 組織管理で Service Account を作成または選択します。
  3. Service Account の詳細ページで API Key を作成します。作成時にスコープを選択する必要はありません。必要なスコープは SAT に交換するときに指定します。
  4. SA Key をコピーし、SAT に交換します。
export QODER_SA_KEY="sa-key"

SAT_RESPONSE=$(curl --silent --show-error --location "$QODER_OPENAPI_BASE_URL/api/v1/serviceToken/exchange" \
  --header "Authorization: Bearer $QODER_SA_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "client_credentials",
    "audience": "qoder",
    "scope": "qca.access",
    "ttl_seconds": 43200
  }')

export QODER_SAT="$(printf '%s' "$SAT_RESPONSE" | jq -r '.access_token')"
export QODER_ACCESS_TOKEN="$QODER_SAT"
SA Key は SAT との交換にのみ使用し、Cloud Agents の業務 API に直接送信しないでください。SAT の有効期間は最大 12 時間です。SAT の有効期限が切れたら、SA Key を再度交換してください。
同じサーバー側連携で Forward API も呼び出す場合は、交換リクエストで "scope": "qca.access forward.access" を使用します。この SAT は、Service Account に関連付けられたアカウントの Forward リソースに対する管理者権限を持つため、信頼できるサーバー側環境でのみ使用してください。詳しくは、認証をご参照ください。

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

利用可能な環境の一覧を取得し、環境 ID を確認します： 
curl -s "$QODER_API_BASE_URL/api/v1/cloud/environments" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"
レスポンス例： 
{
  "data": [
    {
      "id": "env_019e44eb66bb748cabcd1489f6fa4428",
      "type": "environment",
      "name": "default",
      "description": "",
      "config": {
        "type": "cloud",
        "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 "$QODER_API_BASE_URL/api/v1/cloud/environments" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"default"}'

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

echo "環境 ID: $ENV_ID"

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

シェルツールを備えた汎用 Agent を定義します： 
AGENT_RESPONSE=$(curl -s -X POST "$QODER_API_BASE_URL/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -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 "$QODER_API_BASE_URL/api/v1/cloud/sessions" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -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 "$QODER_API_BASE_URL/api/v1/cloud/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [{"type": "text", "text": "Python でフィボナッチ数列を計算する関数を書いて、テストを実行してください。"}]
      }
    ]
  }' | jq .

# SSE ストリームでイベントをリアルタイム受信
curl -s -N "$QODER_API_BASE_URL/api/v1/cloud/sessions/$SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"
イベントストリームの出力例： 
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_ACCESS_TOKEN="your-token" && bash quickstart.sh
set -euo pipefail

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

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"}' | 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_ACCESS_TOKEN が正しく設定され、有効期限内であることを確認してください。PAT ユーザーは新しい Token を作成し、Service Account ユーザーは SA Key で新しい SAT を取得してください。 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 にドメイン専門知識を付与し、タスクのパフォーマンスを向上させる。
はじめに
Agent の定義
Agent 環境の設定
Agent にタスクを委任する
Agent 連携
Agent コンテキストの管理
アカウント
ベストプラクティス
お知らせ
API リファレンス
クイックスタート - Qoder