クイックスタート

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

GUI で操作したい場合は Cloud Agents コンソールへ

Qoder Cloud Agents コンソールでクイックスタート。

前提条件

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

PAT を取得する

Qoder コンソールにログイン

Qoder コンソールを開きます。

パーソナルアクセストークン画面を開く

設定 → パーソナルアクセストークン へ移動します。

トークンを作成

トークンを作成 をクリックし、名前と有効期限を設定します。

環境変数として書き出す

トークンをコピーして実行します：

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

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

最初の Session を作成する

環境を選択する

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

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

レスポンス例:

{
  "data": [
    {
      "id": "env_019e44eb66bb748cabcd1489f6fa4428",
      "name": "default",
      "config": {
        "type": "cloud",
        "networking": {
          "type": "unrestricted"
        }
      },
      "status": "ready",
      "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
}

レスポンスが "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 を抽出（長い ID の手動コピーミスを防ぐため jq を推奨）
ENV_ID=$(curl -s https://api.qoder.com/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" | jq -r '.data[0].id')

echo "Environment ID: $ENV_ID"

Agent を作成する

shell ツールを備えた汎用 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": {},
  "version": 1,
  "archived": false,
  "archived_at": null,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

Session を作成する

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

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",
  "agent": {
    "id": "agent_019e451902fe7a2ca42c2dfc62d9320e",
    "name": "my-first-agent",
    "model": "ultimate",
    "system": "あなたは効率的なプログラミングアシスタントです。コード作成と問題解決が得意です。",
    "tools": [
      {"type": "agent_toolset_20260401", "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]}
    ],
    "mcp_servers": [],
    "description": "",
    "skills": [],
    "metadata": {},
    "type": "agent",
    "version": 1,
    "created_at": "2026-05-18T10:00:00Z",
    "updated_at": "2026-05-18T10:00:00Z"
  },
  "agent_id": "agent_019e451902fe7a2ca42c2dfc62d9320e",
  "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "status": "idle",
  "title": "",
  "turn_status": "idle",
  "memory_store_ids": [],
  "resources": [],
  "vault_ids": [],
  "type": "session",
  "created_at": "2026-05-18T10:01:00Z",
  "updated_at": "2026-05-18T10:01:00Z"
}

Session は作成直後 idle 状態です。次のステップでメッセージを送信すると Agent が処理を開始します。

メッセージ送信とイベントストリーム受信

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"

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

event: user.message
data: {"type":"user.message","content":"Python でフィボナッチ数列を計算する関数を書いて、テストを実行してください。"}

event: session.status_running
data: {"type":"session.status_running","status":"running"}

event: heartbeat
data: {}

event: span.model_request_start
data: {"type":"span.model_request_start"}

event: agent.thinking
data: {"type":"agent.thinking","content":"フィボナッチ関数を書きます..."}

event: agent.message
data: {"type":"agent.message","content":[{"type":"text","text":"以下がフィボナッチ数列の実装です: ..."}]}

event: agent.tool_use
data: {"type":"agent.tool_use","name":"Bash","input":{"command":"python3 fib.py"}}

event: agent.tool_result
data: {"type":"agent.tool_result","output":"..."}

event: span.model_request_end
data: {"type":"span.model_request_end"}

event: session.status_idle
data: {"type":"session.status_idle","status":"idle"}

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

処理の流れ

user.message イベントを送信すると、プラットフォームは以下の処理を行います：

メッセージを受信 し、Session を idle から processing に遷移させます（session.status_running を発行）。
モデルリクエストを開始 し、バインドされた Agent を呼び出します（span.model_request_start を発行）。
Agent の出力をストリーム配信 —— agent.thinking は推論過程、agent.message は返信本文、agent.tool_use と agent.tool_result は各ツール呼び出しに対応します。
接続を維持 するため、約 15 秒間隔で heartbeat を送信します。
ターンを終了、span.model_request_end と session.status_idle を発行します。Session は再利用可能で、別の user.message を送信すれば継続できます。

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

上記の手順を、そのまま実行できるスクリプトにまとめます。

#!/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 "Environment 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 状態です。ステップ 4 で user.message イベントを送信して、Agent の実行をトリガーしてください。 Q: SSE ストリームが切断された場合は? A: 推奨：切断前の最後のイベントの id フィールド（例：evt_…）を保存し、再接続時に ?after_id=<last_event_id> クエリパラメータを付けます。サーバーはそのイベント以降からプッシュを再開し、中間イベントを失いません。保存していない場合は GET /sessions//events?order=desc で最近のイベントを再生してからストリームを開いてください。 Q: GET /environments が空の配列を返す? A: 新規アカウントには環境が事前作成されていない場合があります。「環境を選択する」のヒントに従って手動で作成してください。

次のステップ

Agent の定義

Agent 構成のすべてのフィールドを把握する。

クラウド環境

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

Session 管理

セッション管理を深掘りする。

Agent Skills

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

GUI で操作したい場合は Cloud Agents コンソールへ

​前提条件

​PAT を取得する

​最初の Session を作成する

​処理の流れ

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

​よくある質問

​次のステップ

Agent の定義

クラウド環境

Session 管理

Agent Skills

前提条件

PAT を取得する

最初の Session を作成する

処理の流れ

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

よくある質問

次のステップ