Claude Codeに頼むだけで、Pythonの自作AIエージェントはどこまで作れる？

この記事では、Windows環境のClaude Codeで実際に試した結果をもとにまとめています。

「PythonでAIエージェントを自作したい」——そう思ったとき、LangChainやAutoGenのようなフレームワークが目に入る。便利そうだが、中身がどう動いているか見えにくい。じゃあClaude Codeに「ゼロから作って」と頼んだら、どこまでできるのだろう。Windows 11のターミナルから自然文で依頼し、メインループもツール呼び出しも全部生成させてみた。

この記事で確かめること

Claude Codeに自然文で依頼するだけで、Pythonの自作AIエージェントをどこまで構築できるかを確かめる。

検証条件は次のとおり。Windows 11環境で、ターミナルからClaude Codeに自然文で依頼する。作るのは単一スクリプトのエージェントで、Anthropic APIを呼び出してユーザーの指示に応じる仕組み。Web検索やファイル読み書きのツールも持たせる。

フレームワークは使わない。Claude Codeにゼロからコードを書かせることにフォーカスする。

前提：やっておくこと

検証を再現するには、以下の準備が必要。

Windows 11が動いていること
Python 3.10以上がインストール済みであること（python --versionで確認）
Claude Codeがターミナルで使える状態であること
Anthropic APIキーを取得し、環境変数に設定しておくこと

APIキーの設定はコマンドプロンプトで次のように実行する。

set ANTHROPIC_API_KEY=sk-ant-xxxxx

PowerShellの場合は $env:ANTHROPIC_API_KEY="sk-ant-xxxxx" とする。Claude Code自体のセットアップ手順は、はじめ方の記事を参照してほしい。

やりたいこと：Pythonの自作AIエージェント

今回作るのは、ユーザーの指示を受け取ってツールを使いながら自律的にタスクをこなすPythonプログラム。

具体的には、「Webで検索して」「このファイルを読んで」「計算して」といった指示に対し、エージェントが自分で判断してツールを呼び出し、結果を返す仕組みを作る。LangChainやCrewAIのようなフレームワークを使わず、Anthropic Python SDKのtool_use機能をベースにゼロから組む。

フレームワークを使わない理由は、中身の仕組みを理解するため。エージェントがどう動くかを知っておけば、後からフレームワークに乗り換えたときにも挙動が予想しやすい。

Step 1：最初の依頼文

最初の依頼文は、用途・環境・使いたいAPIの3点を明示した。これはClaude Codeに最初の依頼をしてみようでも触れているように、前提条件をはっきりさせることで認識ズレを防ぐ効果がある。

Windows 11環境で、Anthropic Python SDKを使ったAIエージェントを作って。

エージェントにやらせたいこと：
- ユーザーからの自然言語の指示を受け取る
- 必要に応じてツール（Web検索、ファイル読み書き、計算）を呼び出す
- ツールの結果をもとに回答を組み立てる

条件：
- 単一のPythonスクリプトで完結させる
- anthropicライブラリを使う
- エラーハンドリングを含める

この依頼文にした理由は、アーキテクチャを指定しすぎず、かつAPIと環境を明示したかったため。「単一スクリプト」「anthropicライブラリ」を書いたことで、Claude Codeが出力の前提を取り違えにくくなる。

Step 2：最初の結果

Claude Codeは約300行のPythonスクリプトを生成した。主な構造は次のとおり。

メインループ：ユーザー入力 → LLM呼び出し → ツール実行 → 結果表示のサイクル
ツール定義：web_search、read_file、write_file、calculateの4つ
エラーハンドリング：API呼び出しのtry-except、ツール実行時の例外キャッチ

生成されたツール定義の部分を抜粋する。

tools = [
    {
        "name": "web_search",
        "description": "Webで情報を検索する",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "検索クエリ"}
            },
            "required": ["query"]
        }
    },
    # read_file, write_file, calculate も同様に定義
]

構造はAnthropic SDKのtool_useパターンに沿っており、メインループの流れが公式の推奨する形に近かった。ただしweb_searchの中身がダミー実装（実際には検索しない）だった点と、エラーハンドリングが大ざっぱだった点は気になった。

人が確認したポイントは、APIキーの取り扱い。環境変数から読み込む形になっていたため、ハードコードされていないかを確認した。

Step 3：修正指示

次の修正指示を出した。

いい線いってるけど、2点直して。

1. web_searchツールの中身を実装して。requestsライブラリでDuckDuckGoの検索結果ページを取得する形で。
   今回は検証用としてDuckDuckGoのHTML版を使う前提にする。ただし本格運用では仕様変更や利用条件の確認が必要。
2. エラーハンドリングを細かくして。
   API呼び出しがタイムアウトした場合と、ツール実行で例外が出た場合を分けて扱って。

修正の狙いは、ツールを実際に動く形にすることと、エラーハンドリングの粒度を上げること。特にWeb検索は、エージェントの実用性を試すために外せない機能だった。

修正指示のコツは、何を追加したいかを具体的に書くこと。「検索を動くようにして」だけだと実装がブレるため、「DuckDuckGo」「requests」という前提まで添えた。

Step 4：修正後の結果

修正後のスクリプトは約420行に増え、次の変化があった。

追加された機能：
– web_searchがDuckDuckGoのHTML版をスクレイピングする実装になった
– ファイル読み書きにパスのバリデーションが追加された（指定ディレクトリ外へのアクセスを防ぐ）

改善された点：
– API呼び出しにタイムアウト（30秒）が設定された
– ツール実行時の例外とAPI呼び出し時の例外が別のexcept節で処理されるようになった

try:
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=4096,
        tools=tools,
        messages=messages,
        timeout=30.0
    )
except anthropic.APITimeoutError:
    print("API呼び出しがタイムアウトしました。もう一度試してください。")
    continue
except anthropic.APIError as e:
    print(f"APIエラー: {e}")
    break

残っている懸念は、DuckDuckGoのスクレイピングがサイト側の仕様変更で壊れる可能性があること。検索APIを本格的に使うなら、安定したAPIサービスの利用を検討した方がよい。修正前後で比較すると、ツールの中身がダミーから動く実装に変わり、エラーハンドリングの粒度も上がった。

Step 5：どこまで頼むだけでできた？

2回のやり取りで、Claude Codeがどこまで担当し、どこから人が確認したかを整理する。

比較的任せやすい：
– エージェントの基本構造（メインループ、ツール定義、SDK呼び出し）
– ツールの追加（名前、説明、スキーマの定義）
– コードの修正（指示通りに追記・変更）

条件付きで使える：
– エラーハンドリングの設計（指示の具体性に依存。「タイムアウトとAPIエラーを分けて」と書けば反映されたが、出負けすると大ざっぱになる）
– 外部サービスとの連携（DuckDuckGoのスクレイピングは動いたが、仕様変更に弱い）。MCPサーバーを使った外部ツール連携の方が安定性は高いが、今回は学習目的に敢えてスクレイピングを採用した。

必ず確認：
– APIキーの取り扱い（ハードコードされていないか）
– 外部APIの仕様（正しいエンドポイントか、レート制限はあるか）
– エージェントの設計方針（どういうツールを何個持たせるか、セキュリティ上の懸念はないか）

最初の生成で骨組みができ、1回の修正指示で実用的な中身に変わった。やり取りは計2回。

この検証の振り返り

依頼文の書き方で一番効いたのは、「用途・環境・使いたいAPI」を明示したこと。この3点が揃っていると、Claude Codeが前提を取り違えにくくなり、修正の手間も減る。

修正指示は「何を追加したいか」を具体的に書くことが鍵だった。「エラーハンドリングを細かく」だけより「タイムアウトとAPIエラーを分けて」と書いた方が、狙い通りの出力に近づいた。プログラムのエラー修正の経験がある人なら、この具体性の差がよく分かるはずだ。

フレームワークを使わずにゼロから組む意義は、仕組みが見えることにある。生成されたコードを読めば、メインループがどう回り、ツールがどう呼ばれるかが分かる。この理解は、後からLangChain等に乗り換えるときにも生きる。

エージェントの仕組みを知りたい人や、小規模なエージェントを手元で動かしたい人にはこの構成が向いている。本格的なプロダクション運用や複数エージェントの協調がしたい場合は、フレームワークの導入を検討した方がよい。

次に試すなら

読者が次に試すときのコツをいくつか挙げる。

依頼文には必ず「環境（Windows等）」「使いたいAPI」「エージェントにやらせたいこと」の3点を書く
最初は少ないツールで始め、動いたら追加する方が安定する
生成されたコードは必ず目を通す。特にAPIキーの取り扱いとインポート部分

追加できそうな機能のアイデア：
– 記憶機能（会話履歴をファイルに保存して、次回起動時に読み込む）
– 複数LLMの切り替え（用途に応じてモデルを変える）
– スケジュール実行（Windowsのタスクスケジューラと組み合わせる）

Claude Codeをまだ使ったことがなければ、はじめ方の記事から読むのがよい。そこから環境を整え、今回の依頼文をベースに自分好みのエージェントを作ってみると、手応えが掴みやすい。

環境やSDKのバージョンによっては、今回の検証よりもさらに進められる可能性がある。

まとめ

Claude Codeに頼むだけで、Pythonの自作AIエージェントの基本構造は2回のやり取りで組み上がった。メインループ、ツール定義、エラーハンドリング——ゼロから書くには設計の負担が大きい部分を、自然文の指示で出力してくれる。ただしAPIキーの取り扱い、外部サービスの仕様確認、設計方針の決定は人が担当した。骨組みが短時間でできるので、合わない部分だけ後から直せばいい。

今回の結果は、利用モデル、接続先、時期、環境によって変わる可能性があります。再現する時は検証条件もあわせて確認してください。

Claude Codeでどこまでできる？