Claude Agent SDKでエージェントを構築する

Claude Agent SDK（旧称 Claude Code SDK）は、Claude Codeを支えているエージェントの仕組みを、自分のアプリケーションから直接利用できるようにする開発キットです。ツール実行・ファイル操作・コンテキスト管理といったエージェントのループを自前で組まずに、Claudeを核とした自律的なエージェントを構築できます。

概要

大規模言語モデルを「エージェント」として動かすには、モデルにツールを渡し、モデルの出力に応じてツールを実行し、その結果を再びモデルに戻す、というループ（エージェントループ）が必要です。Claude Agent SDK は、このループやコンテキスト管理、ファイル・ターミナル操作といった土台をあらかじめ用意しており、開発者は「何をさせたいか」に集中できます。

SDK は TypeScript 版と Python 版が提供されています。Claude Code と同じエンジンを使うため、コード編集・コマンド実行・検索などのツールをそのまま活用できます。

Claude Agent SDKとは

もともと「Claude Code SDK」という名前でしたが、Claude Code のコマンドライン用途にとどまらず、汎用的なエージェント構築に使えることを反映して「Claude Agent SDK」に改称されました。カスタマーサポート、コードレビュー、リサーチ、社内業務の自動化など、ファイルやツールを操作しながら多段のタスクをこなすエージェントを作れます。

SDK が提供する主な要素は、(1) Claudeとのメッセージのやり取り、(2) 組み込みツール（ファイル読み書き・シェル実行・検索など）、(3) 権限やツール許可の制御、(4) サブエージェントやフックといった拡張ポイントです。

セットアップ

TypeScript の場合は npm パッケージを、Python の場合は pip パッケージをインストールします。APIキー（ANTHROPIC_API_KEY）を環境変数に設定しておきます。

# TypeScript / Node.js
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

APIキーは Anthropic Console で発行します。キーはコードに直書きせず、環境変数やシークレット管理から読み込んでください。

基本的な使い方

SDK ではプロンプト（やらせたいこと）を渡すと、Claudeが必要に応じてツールを呼び出しながらタスクを進めます。TypeScript の最小例は次のようになります（実際のAPI名は最新のドキュメントで確認してください）。

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "このリポジトリのREADMEを読んで、要点を3行にまとめて",
  options: { model: "claude-opus-4-8" }
})) {
  console.log(message);
}

エージェントの応答はストリームとして順次届き、ツール実行の要求や結果もメッセージとして流れてきます。使えるツールや作業ディレクトリ、権限モード（自動許可の範囲）はオプションで制御できます。

ベストプラクティス

• 権限を絞る: エージェントに与えるツールと書き込み範囲を最小限にし、破壊的な操作は確認を挟む設計にする。
• タスクを明確に指示する: 目的・制約・完了条件をプロンプトで具体的に書くほど、安定して動く。
• サブエージェントで分割する: 大きな作業は役割ごとにサブエージェントへ分けると、コンテキストが整理され精度が上がる。
• コストとループを監視する: 長時間走るエージェントはトークン消費が大きくなりやすいので、上限や停止条件を設ける。

最新のAPI・パッケージ名・対応機能は公式ドキュメントを参照してください。本ページは非公式の日本語まとめです。