AI Hub

Claude Agent SDK入門｜自作AIエージェントの作り方

公開:

#Agent SDK #開発

Claude Agent SDKは、Claude Codeの中身、つまりツール実行・ファイル操作・計画立案をこなす「エージェントループ」を自分のアプリに組み込めるライブラリです。本記事では、Claude Code本体との違い、インストールとAPIキー設定、最小コード例、カスタムツールやMCP連携でできることを解説します。Claude Codeの使い方は「Claude Codeの使い方完全ガイド」も参考にしてください。

前提・動作環境

Claude Agent SDKはPythonとTypeScript(Node.js)向けのライブラリです。対応言語はこの2つのみで、他言語から使う場合はClaude Code CLIを-pオプション(ヘッドレスモード)でサブプロセス実行する方法が案内されています。利用にはAnthropicのAPIキーが必要です。仕様は変わりうるため、実装前に公式サイトで最新情報を確認してください。

Claude Agent SDKとは何か

Claude CodeはCLIやIDE上で対話的に使うコーディングエージェントですが、Claude Agent SDKはその裏側の仕組み、ファイルの読み書き・コマンド実行・Web検索といった組み込みツールとエージェントループそのものをライブラリとして呼び出せる点が特徴です。公式ドキュメントでは、Claude関連ツールを次のように整理しています。

自社サービスに「コードを読んで直す」「リポジトリを調査する」といった機能を組み込みたいなら、Agent SDKが第一候補です。単発のテキスト生成や分類程度なら通常のAPI呼び出しで十分です。

セットアップ

次のコマンドでインストールします。

npm install @anthropic-ai/claude-agent-sdk
pip install claude-agent-sdk

APIキーは環境変数ANTHROPIC_API_KEYに設定します。

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"

claude.aiのログインや契約枠を自作アプリのユーザーに提供することは、事前承認がない限り許可されていません。Agent SDKを組み込む製品では、必ずAPIキー認証を使ってください。APIキーの取得・管理方法は「ClaudeをAPIキーで使う方法」で解説しています。

最小コード例

TypeScriptではquery()関数に非同期ジェネレータでプロンプトを渡すだけで、エージェントループが自動的に動き出します。

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

for await (const message of query({
  prompt: "src/utils.tsのバグを見つけて修正してください",
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Pythonでは同名のquery()をasync関数内で呼び出します。

import asyncio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="src/utils.pyのバグを見つけて修正してください"):
        print(message)

asyncio.run(main())

どちらも、ファイルの読み書きやコマンド実行を含む一連の作業をClaudeが自律的に計画・実行し、進行状況や最終結果がメッセージとしてストリーミングで返ってきます。

できること

Agent SDKでは、Claude Codeの機能のほぼすべてをオプションとして利用できます。

サブエージェントの考え方はClaude Code本体と共通する部分が多く、「Claude Codeサブエージェント活用術」で詳しく解説しています。Skills・CLAUDE.mdの設定も同じ.claude/から読み込まれます。

実用アイデア

注意点

つまずきポイント/よくあるエラー

よくある質問

Claude Agent SDKとClaude Code CLIはどちらを使うべきですか?

対話的にターミナルやIDEで使うだけならCLIで十分です。自社アプリやバッチ処理に組み込みたい場合はAgent SDKを選びます。

無料で使えますか?

SDK自体は無料ですが、内部で呼び出すAnthropic APIは従量課金です。料金は変動するため公式サイトで最新情報を確認してください。

Managed Agentsとの違いは何ですか?

Agent SDKは自分のサーバー上でループを動かすライブラリです。Managed Agentsは実行環境ごとAnthropic側がホストする別サービスで、長時間・非同期の実行に向いています。

まとめ

Claude Agent SDKを使うと、Claude Codeと同じエージェントループやツール群を自作アプリに組み込めます。npm installまたはpip installしAPIキーを設定すれば、数行のquery()呼び出しから始められます。カスタムツールやMCP連携、サブエージェント、権限制御まで揃っており、社内ボットやドキュメント自動整備など既存システムへの追加に有力な選択肢です。導入前にはAPIコストの試算と実行権限の設計を忘れずに行いましょう。Claude Codeの使い方は「Claude Codeの使い方完全ガイド」、サブエージェントの活用法は「Claude Codeサブエージェント活用術」も参考にしてください。