agent 講座を見ても動かない？1つの Key でサンプルを動かそう

X にこんな投稿がある：500ドル出して AI Agent 講座を買った人は、今なら無料で見られる、という自虐だ。元ポスト：https://x.com/deanwperkins/status/2116911546282733623（作者 Dean W. Perkins、@deanwperkins）。下の議論で一致していたのは、講座自体は希少ではなく、希少なのは講座の中身を動かすことだ、という点だ。

まさに核心を突いている。多くの人がつまずくのは agent ループが分からないからではなく、最初の一歩で動かせないからだ：サンプルコードが使うモデル Key がない、別のモデルに変えたらプロトコルが合わない、動かせないから検証もできない。

この記事では最小限の動く構成を説明する。agent の理論は扱わない。

最小の agent は3つだけでできている

フレームワークや抽象化を脇に置けば、実際に仕事をする agent は3つの部品でできている：

1. ツールを呼び出せるモデル
2. ツール定義のセット（名前、パラメータ、説明）
3. ループ：モデルがどのツールを呼ぶか決め、あなたが実行し、結果をモデルに返す。モデルが終わったと言うまで繰り返す

講座で扱うマルチエージェント、メモリ、プランニングは、すべてこの3つに何かを足したものだ。まずこの3つを動かそう。

ステップ1：Key を用意する

ほとんどの講座の最初の課題は「某モデルの API Key を申請しに行く」ことだ。この時点で挫折する人は少なくない：登録、カード紐付け、審査待ち、中には枠の申請が必要なものもある。

統一された入口を使えばこの工程を丸ごと飛ばせる。HiAPI の Key は1つの認証で、Claude、GPT、Kimi、Grok、DeepSeek などのテキストモデルをカバーし、標準の Chat Completions プロトコルで動く。

Key を取得したら、まず疎通を確認する：

curl -s https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "messages": [{"role": "user", "content": "一句你好"}]
  }'

内容が返ってくれば、Key は問題ない。

ステップ2：ツールを定義する

ツール定義はモデルに見せる説明書だ。どんなツールがあり、各ツールがどんなパラメータを必要とするかを知らせる。

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "指定された都市の現在の天気を照会する",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "都市名、例：北京"}
            },
            "required": ["city"]
        }
    }
}]

書くべき説明は一言だけ：モデルは description によって、いつこのツールを使うべきかを判断する。明確に書くほど、呼び間違える確率は下がる。

ステップ3：ループを書く

import json, requests

API = "https://api.hiapi.ai/v1/chat/completions"
KEY = "YOUR_HIAPI_API_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def run_weather(city):
    return {"city": city, "temp": 18, "condition": "晴"}  # サンプル実装

messages = [{"role": "user", "content": "北京は今日何度？"}]

for _ in range(5):  # 無限ループ防止
    resp = requests.post(API, headers=HEADERS, json={
        "model": "gpt-6.1-sol",
        "messages": messages,
        "tools": tools,
    }).json()

    msg = resp["choices"][0]["message"]
    messages.append(msg)

    if not msg.get("tool_calls"):
        print(msg["content"])
        break

    for call in msg["tool_calls"]:
        args = json.loads(call["function"]["arguments"])
        result = run_weather(args["city"])
        messages.append({
            "role": "tool",
            "tool_call_id": call["id"],
            "content": json.dumps(result, ensure_ascii=False),
        })

これを実行すると、モデルがまず get_weather を呼ぶと決め、結果を受け取ってから一文にまとめて回答するのが分かる。これが完全な agent ループだ。

モデルの選び方

同じループでも、model フィールドを変えるだけでモデルを切り替えられる。コスト差は大きい：

モデル	入力	出力	向いている用途
GPT-6 Luna	$0.025	$0.125	簡単なツール呼び出し、分類、抽出
GPT-6.1 Terra	$0.25	$1.25	日常的な agent、コードタスク
GPT-6.1 Sol	$0.50	$2.50	複雑な多段タスク
Claude Opus 5.5	$2.02	$10.08	長時間タスク、深い推論が必要な場面

1回のツール呼び出しループはだいたい数千トークン、最安の Luna で計算すると1回1厘未満だ。講座で実験する分にはコストは無視できる。

講座で特定のモデルが指定されているならそれに従えばいい。指定がない、あるいは使えない場合は、同価格帯の代替を使っても学習効果に影響はない。ループのロジックは同じだからだ。

講座で最もつまずきやすい3つのポイント

ツール呼び出しの返却フォーマットが合わない。 モデルベンダーによって tool_calls のフィールド構成に違いがある。Chat Completions 互換プロトコルのモデルならフォーマットが統一されているので、モデルを変えてもパースコードを直す必要はない。

コンテキストがどんどん長くなる。 毎ターン履歴を全部持たせると、30ターン目で上限に達する。講座の後半で切り詰め戦略を扱うが、前半ではまずこの落とし穴の存在を知っておこう。

モデルがツールを呼ばずテキストだけ返す。 たいていはツールの説明が曖昧すぎるか、プロンプトで「使えるツールがある」と明確に伝えていないのが原因だ。説明を具体的にするか、システムプロンプトで明示しよう。

動いた後にやること

すぐにフレームワークに手を出さないこと。

最小ループが動くようになったら、次の順番で足していく：

1. エラー処理を追加：ツール実行が失敗したらエラー情報をモデルに返し、リトライさせるか別の道を選ばせる
2. 使用量の統計を追加：呼び出しごとのトークン数を記録して、コストがどこに消えているかを知る
3. タイムアウトとリトライを追加：ネットワークの揺らぎは常態だ
4. その後にフレームワークを検討：タスクがマルチエージェントや複雑なステートマシンを必要とするほど複雑なら、フレームワーク導入は遅くない

講座で教えるアーキテクチャは通常、本番向けだ。そのまま真似て組むと最初の一歩でつまずきやすい。まず3つの部品を動かし、残りは必要に応じて足していこう。

よくある質問

特定のモデルを使わないといけないのか？

いいえ。ツール呼び出し（function calling）に対応していれば、ループのロジックは共通だ。講座指定のモデルが使えない場合、同価格帯の代替でも理解に影響はない。

無料講座と有料講座の違いはどこにある？

X のその議論によれば、違いは知識そのものよりも構成や質疑応答にある。サンプルを動かすという作業は、どちらでも自分でやる必要がある。

ツールから実際の API を呼べる？

呼べる。run_weather を実際の HTTP リクエストに置き換えるだけだ。ツール関数内の例外はすべて捕捉すること。そうしないと1回の失敗でループ全体が止まってしまう。

1回動かすのにいくらかかる？

最小サンプルは数千トークン、最安のモデルなら1回1厘未満、高いものでも数分程度だ。実験に使う分にはコストを気にしなくていい。

重要な結論

agent 講座のつまずきは決して理論ではなく、最初のサンプルが動かないことにある。完全なループは3つで動く：使える Key 1つ、ツール定義1つ、結果をフィードバックするループ1つ。動いてからエンジニアリングの細部を埋めるほうが、逆の順序より10倍簡単だ。

利用可能なテキストモデルと価格を見る

---

出典

• 話題の発端：Dean W. Perkins（@deanwperkins）、https://x.com/deanwperkins/status/2116911546282733623
• 当該ポストには具体的な講座リンクが添付されていないため、本記事は特定の講座を指さず、サンプルを動かすための汎用構成のみを扱う
• コード例と価格データは本サイトがまとめたもので、価格は HiAPI 本番環境（2026-11-02）による