PythonでClaude Agent SDKの最小エージェントを作る

Pythonエージェントの最初の目標は、複雑な自律システムではなく「入力を受け、許可したツールだけを使い、結果を表示する」ことです。公式Quickstartに沿って、小さなタスクから実装します。

準備

最初はREADMEを読んで結果を表示する範囲に絞ります。

1. 1入力資料と環境練習用README、仮想環境、認証の準備。
2. 2queryを実行Read・Globに絞った設定で読み取りを依頼。
3. 3メッセージを受け取る回答と終了状態を区別して処理。
4. 4原文と照合READMEの目的・対象が正しく含まれるか確認。

起動できたことだけで完了にはしません。ファイル変更の有無と、失敗した場合の結果も確認します。

公式QuickstartはPython 3.10以上を前提に、Windowsでは仮想環境を作り、pip install claude-agent-sdk を実行します。APIキーはエージェントを起動するプロセスの環境変数から読み込まれ、.envを自動で読むわけではありません。 Quickstart

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

APIキーは、実行前に安全な方法で ANTHROPIC_API_KEY 環境変数へ設定済みとします。ソースコードやログへキーを書きません。まず query() で短い指示を送り、返るメッセージの種類、終了状態、エラーを記録します。Python SDKの query() は非同期イテレーターで、新しいセッションを開始する使い方が基本です。 Python SDKリファレンス

読み取り用の資料を用意する

実行するフォルダーにREADME.mdが必要です。なければ、エディターで次の架空の練習資料を保存します。既存のREADMEがある場合は上書きせず、練習用の別フォルダーを使ってください。

# 練習用プロジェクト
目的：短い資料を読み、内容を整理する練習。
対象：このREADMEのみ。ファイルは変更しない。
完了条件：目的と対象が回答に正しく含まれている。

読み取り専用の最小コード

agent.pyを作業フォルダーに保存し、ReadとGlobだけを使えるようにします。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    options = ClaudeAgentOptions(
        tools=["Read", "Glob"],
        allowed_tools=["Read", "Glob"],
    )
    async for message in query(
        prompt="README.mdを読み、要点を3つだけ説明して。ファイルを変更しないで。",
        options=options,
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"result: {message.subtype}")

asyncio.run(main())

PowerShellでは python agent.py を実行します。終了状態が成功でも、出力とアクセスしたファイルを確認します。APIキーをまだ設定していない場合は実行せず、公式Quickstartの認証説明を確認します。

ツールを絞る

このフォルダーのREADME.mdだけを読み、改善点を箇条書きで返して。
ファイル編集、コマンド実行、外部通信はしない。根拠のない提案には要確認を付けて。

最初は読み取りだけを許可し、編集は別の実行で承認します。ツールを追加したら、入力スキーマ、許可リスト、タイムアウト、失敗結果、個人情報の扱いを確認します。Client SDKはAPIを直接呼びツールループを自分で書くものなので、Agent SDKとの違いを明記します。 SDK概要

TypeScript版は実装例、構造化結果はJSON出力、独自ツールはCustom Toolsへ進みます。

限界

コードが起動しても、ツールの権限やAPI費用、実際の編集結果が安全とは限りません。テスト用フォルダーで、ログ・終了状態・差分・復旧方法を確認してから対象を広げます。

最小の検査では、正常な入力、空入力、長すぎる入力、ツール拒否、APIエラーを別々に試します。返されたメッセージを文字列として表示するだけでなく、成功・失敗の状態と使用量を保存します。エージェントが書いたコードをそのまま本番へ置かず、依存関係のライセンス、ファイル権限、ネットワーク先、再実行時の重複を確認してから運用へ進みます。