Claude Code SDK

 (docs.anthropic.com)
1 ポイント 投稿者 GN⁺ 2025-05-20 | 1件のコメント | WhatsAppで共有
  • Claude Agent SDK は、Claude Code のツール実行、エージェントループ、コンテキスト管理を Python・TypeScript のコードから制御できるようにし、ファイル読み取り、コマンド実行、Web 検索、コード編集を自動化する
  • 基本ツールとして Read, Write, Edit, Bash, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion を提供し、コードベース探索からユーザー確認の質問まで、別個の実行レイヤーなしで処理できる
  • フック、サブエージェント、MCP、権限、セッションを組み合わせることで、ファイル変更の監査ログ、コードレビュー専用サブエージェント、Playwright ベースのブラウザ自動化、読み取り専用の分析エージェントのような構成が可能
  • インストールは @anthropic-ai/claude-agent-sdk または claude-agent-sdk で行い、Python は 3.10 以上 が必要で、TypeScript SDK はプラットフォーム向けネイティブ Claude Code バイナリをオプション依存関係として含む
  • Agent SDK は、ツールループを自前で実装する Anthropic Client SDK と異なり、組み込みツール実行 を提供し、Managed Agents のように Anthropic のインフラではなく、ユーザーのプロセスとインフラ上で実行される

Claude Agent SDK が担う範囲

  • Claude Agent SDK は、Claude Code を動かすツール、エージェントループ、コンテキスト管理を Python と TypeScript で利用可能にする
  • エージェントはファイル読み取り、コマンド実行、Web 検索、コード編集を実行できる
  • 組み込みツール実行が含まれているため、ユーザーが別途ツール実行レイヤーを自作しなくても、エージェントが作業を開始できる
  • 基本例では、auth.py のバグを見つけて修正する作業に Read、Edit、Bash ツールを許可している

インストールと認証フロー

  • 言語ごとのパッケージとしてインストールする
    • TypeScript: npm install @anthropic-ai/claude-agent-sdk
    • Python: pip install claude-agent-sdk
  • Python パッケージには Python 3.10 以上 が必要
    • No matching distribution found for claude-agent-sdk エラーが出る場合、インタープリタが 3.10 より古い可能性がある
    • macOS または Linux では python3 --version、Windows では py --version で確認する
  • TypeScript SDK は、プラットフォーム向けネイティブ Claude Code バイナリ をオプション依存関係として含むため、Claude Code を別途インストールする必要はない
  • API キーは Console で発行し、ANTHROPIC_API_KEY 環境変数として設定する
  • サードパーティ API プロバイダーの認証もサポートする
    • Amazon Bedrock: CLAUDE_CODE_USE_BEDROCK=1 を設定後、AWS 認証情報を構成
    • Claude Platform on AWS: CLAUDE_CODE_USE_ANTHROPIC_AWS=1、ANTHROPIC_AWS_WORKSPACE_ID を設定後、AWS 認証情報を構成
    • Google Vertex AI: CLAUDE_CODE_USE_VERTEX=1 を設定後、Google Cloud 認証情報を構成
    • Microsoft Azure: CLAUDE_CODE_USE_FOUNDRY=1 を設定後、Azure 認証情報を構成
  • Anthropic は事前承認なしに、サードパーティ開発者が Claude Agent SDK ベースの製品に claude.ai ログインやレート制限を提供することを許可していない

基本ツールとエージェント機能

  • SDK は Claude Code の主要機能をコードから扱えるようにする
    • 組み込みツール
    • フック
    • サブエージェント
    • MCP
    • 権限
    • セッション
  • 主な 組み込みツール は次の役割を担う
    • Read: 作業ディレクトリ内のファイルを読み取る
    • Write: 新しいファイルを作成する
    • Edit: 既存ファイルに精密な編集を適用する
    • Bash: ターミナルコマンド、スクリプト、git 操作を実行する
    • Monitor: バックグラウンドスクリプトを監視し、各出力行にイベントとして反応する
    • Glob: **/*.ts、src/**/*.py のようなパターンでファイルを探す
    • Grep: 正規表現でファイル内容を検索する
    • WebSearch: 最新情報を Web で検索する
    • WebFetch: Web ページのコンテンツ取得と解析を行う
    • AskUserQuestion: 複数選択肢でユーザーに確認質問をする
  • 例のエージェントでは Read、Glob、Grep を許可し、コードベース内の TODO コメント を見つけて要約する

フック、サブエージェント、MCP

  • フック(hook) は、エージェントのライフサイクルにおける主要なタイミングでユーザーコードを実行する
    • コールバック関数によってエージェント動作を検証、記録、ブロック、変換できる
    • 利用可能なフックには PreToolUse、PostToolUse、Stop、SessionStart、SessionEnd、UserPromptSubmit などがある
    • 例では PostToolUse で Edit|Write 操作を検知し、audit.log にファイル変更を記録する
  • サブエージェント は、集中的な下位タスクを処理する特化型エージェント
    • メインエージェントが作業を委譲し、サブエージェントが結果を返す
    • カスタムエージェントは説明、プロンプト、使用するツールで定義する
    • サブエージェント呼び出しは Agent ツール経由で行われるため、自動承認したい場合は allowedTools に Agent を含める必要がある
    • サブエージェントのコンテキスト内のメッセージには parent_tool_use_id フィールドが含まれ、どのサブエージェント実行に属するかを追跡できる
  • Model Context Protocol(MCP) により、データベース、ブラウザ、API などの外部システムに接続できる

権限とセッション管理

  • 権限設定は、エージェントが利用できるツールを制限する
    • 安全な作業は許可し、危険な作業はブロックし、機密性の高い動作には承認を求めることができる
    • 例では Read、Glob、Grep のみを事前承認し、コードを分析するが修正はしない 読み取り専用エージェント を構成する
  • AskUserQuestion ツールと対話型の承認プロンプトは、ユーザー入力を処理するフローで併用される
  • セッション は複数回のやり取りにわたってコンテキストを維持する
    • Claude は読んだファイル、実施した分析、会話履歴を記憶する
    • 後で同じセッションを再開したり、別のアプローチを試すためにフォークしたりできる
    • 例では最初のクエリで session_id を取得し、2 回目のクエリで resume=session_id として同じコンテキストを引き継ぐ

Claude Code 設定サポート

  • SDK は Claude Code のファイルシステムベース設定をサポートする
  • デフォルトオプションでは、作業ディレクトリの .claude/ と ~/.claude/ から設定を読み込む
  • 読み込む設定ソースを制限するには、Python では setting_sources、TypeScript では settingSources オプションを使う
  • 対応機能と配置場所は次の通り
    • Skills: Claude が自動利用する、または /name で呼び出す特化機能、.claude/skills/*/SKILL.md
    • Commands: レガシー形式のカスタムコマンド、.claude/commands/*.md
    • Memory: プロジェクトのコンテキストと指示、CLAUDE.md または .claude/CLAUDE.md
    • Plugins: skills、agents、hooks、MCP servers を拡張し、plugins オプションでプログラム的に構成する

他の Claude ツールとの違い

  • Anthropic Client SDK は API への直接アクセスを提供し、ユーザーがプロンプト送信とツール実行を自分で実装する
  • Agent SDK では Claude がツール処理を自律的に実行する
    • Client SDK ではユーザーがツールループを実装する
    • Agent SDK は Claude に組み込みツール実行を提供する
  • 用途別の選択基準は次の通り
    • 対話型開発: CLI
    • CI/CD パイプライン: SDK
    • カスタムアプリケーション: SDK
    • 単発作業: CLI
    • 本番自動化: SDK
  • 多くのチームは日常開発では CLI、本番では SDK を併用しており、ワークフローは相互に直接移行できる
  • Managed Agents は、Anthropic がエージェントとサンドボックスを実行するホスト型 REST API
  • Agent SDK は、ユーザーのプロセス内でエージェントループを実行するライブラリ
    • 実行場所: Agent SDK はユーザーのプロセスとインフラ、Managed Agents は Anthropic 管理インフラ
    • インターフェース: Agent SDK は Python または TypeScript ライブラリ、Managed Agents は REST API
    • 作業対象: Agent SDK はユーザーインフラ上のファイル、Managed Agents はセッションごとのマネージドサンドボックス
    • セッション状態: Agent SDK はファイルシステム上の JSONL、Managed Agents は Anthropic ホスティングのイベントログ
    • カスタムツール: Agent SDK はプロセス内の Python または TypeScript 関数、Managed Agents は Claude がツールをトリガーし、ユーザーが実行結果を返す
    • 適した用途: Agent SDK はローカルプロトタイピングやファイルシステム・サービスへ直接アクセスするエージェント、Managed Agents はサンドボックスやセッション基盤を運用しない本番エージェントと長時間実行・非同期セッション
  • 一般的な流れは、Agent SDK でローカルプロトタイプを作成し、その後本番では Managed Agents に移行するというもの

変更ログ、バグ報告、ブランディング

  • SDK の更新、バグ修正、新機能は各リポジトリの変更ログで確認できる
  • バグや問題は GitHub で報告する
  • パートナーが Claude Agent SDK を統合する際、Claude ブランディング の使用は任意
    • 許可: “Claude Agent”, “Claude”, “Powered by Claude”
    • 禁止: “Claude Code”, “Claude Code Agent”, Claude Code ブランドの ASCII アート、または Claude Code を模倣した視覚要素
    • 製品は独自ブランディングを維持し、Claude Code や Anthropic 製品のように見えてはならない
  • Claude Agent SDK の利用には Anthropic’s Commercial Terms of Service が適用される
    • ただし、特定コンポーネントや依存関係で当該コンポーネントの LICENSE ファイルに別ライセンスが明記されている場合はその限りではない

関連記事

1件のコメント

 
GN⁺ 2025-05-20
Hacker News のコメント

  • Claude Code が目指している方向は、私がエージェント型コーディングツールに求めているものと正確に一致していて、「Unix ツールのような」哲学も良い
    公開プレビューの初期から使ってきたが、方向性は見えていた。コーディングエージェントの理想的な最終形は、Jira チケットのような機能要求を渡すと、レビューしてフィードバックできる PR を作ってくれることだと思う。そういう意味で、Cursor や Windsurf のようなローカルエディタ中心のツールは CI の中で動けないため、行き止まりに近い。コードベースを AI 向けにルールや MCP などで整備するなら、ヘッドレス利用までつながる技術を目指すべきだ。Claude Code はツールを通じて自動化の一部として簡単に使えるので、今ではコーディングエージェントを考えるときのデフォルトになっており、Codex npm パッケージも似ている。ただし、自分は企業がエージェント活用に合わせてコードベースを整備するのを支援する仕事をしているので、設定しやすいツールのほうに偏りがあるかもしれない

    • その「理想的な最終形」には同意しにくい。私が望む姿は、部屋の中で複数の画面に囲まれ、AI エージェントたちがコーディング、設計、テストを行い、私は中央で方向を示して好みを反映するというものだ
      すべて会話で進み、99% はキーボードに触る必要がない形を期待している
    • そうではないと思う。コーディングエージェントの「理想的な」最終形は、自分のコンピュータや自分が望むマシン上で動く自由でオープンソースのコーディングエージェントだ
      ターミナルで ls、ps、kill のようなコマンドを実行するたびにお金を払うと想像してみると、ありえない。LLM も同じだ。プロプライエタリな LLM を禁止しようという意味ではないが、昔ながらのハッカーが主な道具として使うべきなのは、自由でオープンソースなツールであるべきだ
    • Anthropic も今日、似た方向の機能をベータとして発表した: https://docs.anthropic.com/en/docs/claude-code/github-action...
    • Cursor と MCP でもこうした作業をやってみた。1日ほど経つと使用量制限に引っかかり、最も遅くて愚かなモデルに落とされた
      Claude でもやってみたが、すぐに制限を使い切った。PR がそのまま「通してよい」レベルなのは 25% 程度にすぎず、AI がどこでやらかしたのか探すくらいなら、最初から自分でちゃんとやるほうが速いことが多い
    • 機能要求を渡すとレビュー用の PR を作ってくれる状態、という話は理解できるが、それだとソフトウェア作業で最も魂を削る部分であるJira チケットだけが残ることになり、気が滅入る

  • Claude Code は、コーディングに LLM を使う方法の中で一番気に入っている
    しかし本当に必要なのは、任意のモデルを渡せて、複数モデルの回答も比較できるオープンソース版だと思う。Aider や他の代替案は、Claude Code ほど使いやすく感じない。Anthropic の立場では堀がなくなるので望まないだろうが、消費者の立場では特定のエコシステムに縛られず最高のモデルを使いたいだけだ。おそらくこれが、LLM モデル提供企業が最も恐れている点なのだろう

    • OpenAI Codex がたぶん最も近い代替案だ。オープンソースで、どの提供元のモデルでも使用できる
      今は Claude Code ほど良くはないが、すぐ追いつきそうだ。https://github.com/openai/codex/tree/main
    • OpenCode プロジェクトは関心に合うかもしれない: https://github.com/opencode-ai/opencode
      まだ開発中だが、有望に見える
    • Claude Code がAider より優れている点が何なのか気になる
    • 最近は自己宣伝をしすぎている気もするが、以前のコメントを見ると、私が Go で作ったサービスがある。まさにこうした要求を狙ったものだ
    • 同意するが、他のモデルも MCP サーバーと作業する方法を分かるように訓練されている必要があるのではないか？ それとも問題にはならないのか？

  • Aider はかなり前から Python とシェルスクリプティングをサポートしてきた [0]
    最近、130 の新しいプログラミング言語サポートを追加する過程で、その場で Bash スクリプティングを Aider で行うスクリーンキャストも作った [1]。こうしたアプローチがどれほど強力になり得るか、感覚をつかめるはずだ。
    [0] https://aider.chat/docs/scripting.html
    [1] https://aider.chat/docs/recordings/tree-sitter-language-pack...

    • Aider は本当に気に入っている。MCP も近くサポート予定で、開発ブランチをテスト中だ
      そうなれば、信頼するモデルを使って PR やチケットなどを通じて最初から最後まで開発できる
    • Aider を Claude Code にどれくらい近づけられるのか気になる。Claude Code のユーザー体験は良かったが、Gemini 2.5 Proを好んでいるので使っていない
      コミットまでしてくれることはあまり望んでおらず、主に Claude Code の使用感が気に入っている
    • Aider は、よく磨かれた GitHub Actions ワークフローがあれば大きく良くなり得る
      リポジトリにファイルを1つ追加するだけで、Issue を通じてどのモデルとも会話できるような形であればよい

  • Claude Code チームがより詳しく取り上げている内容: http://latent.space/p/claude-code
    文字起こしをざっと読むだけでもよいが、個人的には、Anthropic の社員が無制限の Claude を使っていながら平均で1日あたり約6ドル程度しか使っていない点、ヘッドレスの Claude Code を CI のどこでも使える「Linux」ユーティリティのように見ている点、ユーザーが拡張可能なプラットフォームとして見ている点、サンドボックス化・ブランチング・計画機能が今後のロードマップにある点、Sonnet 3.7 を持続型エージェントモデルとして見ている点が印象的だった

    • リンク先には、Anthropic の社内エンジニアの中に1日で1,000ドル超を使った人もいると書かれている
      社員別支出の P50、P75、P95 がいくらなのか気になる
    • 自分の使い方が間違っているのかもしれないが、Claude Code を2時間使うと簡単に20ドル以上かかる
      個人プロジェクトには高すぎるので使用をやめた
    • 最近 latent space ポッドキャストを本当に楽しく聴いている。高いS/N比を保ちながら、全体的なアウトプット量がここまである人やポッドキャストはほとんどないと思う
      この半年、あるいは数年にわたって複数の事業を育てながら、公開される作業の量と価値が増え続けているのは驚きだ。他の人たちも似たような生産性の傾きを見つけられるとよいと思う。大まかに何がうまく合っているのかは共有しているが、再現するのは簡単ではない。思い浮かぶのは simonw、gwern あたり
    • そのポッドキャストがどれほど中立的だったのか、それとも単にこの製品の営業色の強い宣伝だったのか気になる

  • もし自分が AI コードアシスタントを作るなら、特定の基盤モデル提供企業に縛り付けるのは最後の最後にするだろう
    この製品が成功するには、いままさにモデル性能が高原状態に達しており、すべての基盤モデルがほぼ同じ性能と能力に収束し、インテグレーターが慣れ親しんだ SDK のような些細な利便性で選ぶようになる、という前提が必要になる

    • コマンドと引数を除けば、縛られる部分は多くない。単なる入力と出力にすぎない
      別のものに差し替えるか、ラッパーをかませればよい。ここに複雑なことはあまりない
    • 現時点で Claude Code は、エージェント型コーディング領域におけるソフトウェア面の差別化要素だ
      AI コードアシスタント関連の何かを作っているところで、まず Claude Code を統合する方法をハックしていた。私たちが最初にその上に作りたいと思った対象だ。ロックインを心配するには早すぎるし、最高のものが必要なので最高のものを中心にだけ作るつもりだ

  • Claude Code はすでに非対話モードで使うことができ、そのため他の Unix コマンドラインユーティリティと同じように他のアプリへ統合できた
    この SDK は現時点ではコマンドラインでの利用だけをサポートしているように見えるが、それなら既存のものと同じではないのか？実際に何が新しくなったのか分からない。自分が何か見落としているのだろうか？

    • 私にも分からない。見る限り、この点をほとんど誰も話題にしていないようで奇妙だ

  • Codebuff(https://www.codebuff.com/) もおすすめ。Claude Code に似た優れたCLI コードアシスタントで、トークン費用をかなり節約できる
    このプロジェクトとは関係なく、単なるユーザーだ

  • 規約には「本サービスと競合する製品またはサービスを開発するため、人工知能または機械学習のアルゴリズムもしくはモデルを開発・訓練するため、または本サービスを再販売するために使用してはならない」とある
    汎用知能と競合しないソフトウェア製品やサービスとは一体何なのか気になる。知能を売っておきながら、厳密に解釈すればどこにも使うなという法的条項を付けていることになる。あまりに曖昧で執行不能なのだろうか？汎用知能と競合する用途に使えないなら、出力物はどうやって所有するというのか？「法的規約なんて誰も気にしない」という感じなのか？誰も気にしないなら、なぜサービス利用に包括的な禁止をかけているのか？こうした成果物を得るために、訴訟で敗訴する責任まで受け入れなければならないのか、疑問が多すぎる

    • 弁護士たちに好き勝手書かせるとこうなる
    • 「artificial」を「general」に置き換えたのだから、意味が変わるのは当然だ

  • モデルロックインがあると、利用上大きな不利になる。誰かが最新かつ最高性能のモデルを出したとき、すでにこのインフラに投資していたら閉じ込められてしまう
    後から開放したとしても、そのモデルがその CLI に合わせて特別に訓練されている可能性が高く、うまく動かないかもしれない。Codex CLI を見ても、Gemini 2.5 Pro は使えるものの、OpenAI のモデルに比べてランダムに止まったり失敗したりすることが多い

  • 新しい GitHub Action は、まさに自分が探していた機能だ: https://docs.anthropic.com/en/docs/claude-code/github-action...
    ただ、Claude Code のMax プランで使う方法はなさそうだ。自分の見る限り、API キーだけを受け付けるように見える