Claude Code Agent SDK入門 ― 自律エージェントを最速で構築する方法

Agent SDKとは何か

Claude Code Agent SDKは、Claudeモデルをコアに据えた自律型エージェントをプログラムから構築するためのフレームワークです。単なるAPIコールと異なり、エージェントは目標を受け取ると自分でツールを選択し、結果を評価し、次のアクションを決定するマルチステップ推論ループを実行します。

従来のチャットボットでは「質問→回答」の1往復で完結していましたが、Agent SDKを使えば「ファイルを読む→問題を特定→修正を適用→テストを実行→結果を報告」といった複雑なワークフローを1回の指示で完了させることができます。

セットアップ

まずはプロジェクトを初期化してSDKをインストールします。

mkdir my-agent && cd my-agent
npm init -y
npm install @anthropic-ai/claude-code --save

TypeScriptで開発する場合は型定義も追加します。

npm install typescript @types/node --save-dev
npx tsc --init

環境変数にANTHROPIC_API_KEYをセットすれば準備完了です。

export ANTHROPIC_API_KEY="sk-ant-..."

最小構成のエージェント

以下は、ファイルシステムを操作できるシンプルなエージェントの例です。

import { Claude } from "@anthropic-ai/claude-code";

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
});

async function main() {
  const result = await agent.run(
    "srcディレクトリ内のTODOコメントを一覧化して、優先度順に並べてください"
  );
  console.log(result.text);
}

main();

maxTurnsはエージェントが実行できる最大ステップ数です。無限ループを防ぐ安全弁として必ず設定しましょう。

カスタムツールの定義

Agent SDKの真価はカスタムツールを定義できる点にあります。エージェントに外部APIやデータベースへのアクセスを与えることで、より実用的な自動化が可能になります。

import { Claude, Tool } from "@anthropic-ai/claude-code";

const fetchIssueTool: Tool = {
  name: "fetch_github_issue",
  description: "GitHubのIssueを取得する",
  parameters: {
    type: "object",
    properties: {
      owner: { type: "string", description: "リポジトリのオーナー" },
      repo: { type: "string", description: "リポジトリ名" },
      number: { type: "number", description: "Issue番号" },
    },
    required: ["owner", "repo", "number"],
  },
  async execute({ owner, repo, number }) {
    const res = await fetch(
      `https://api.github.com/repos/${owner}/${repo}/issues/${number}`,
      { headers: { Authorization: `token ${process.env.GITHUB_TOKEN}` } }
    );
    return await res.json();
  },
};

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool],
  maxTurns: 15,
});

このように定義すると、エージェントは必要に応じてfetch_github_issueを呼び出し、取得した情報をもとに次の行動を決定します。

マルチステップ実行の流れ

Agent SDKのエージェントは内部で以下のループを回します。

1. 計画（Planning） ― ユーザーの指示を分解し、必要なステップを洗い出す
2. ツール選択（Tool Selection） ― 利用可能なツールから最適なものを選択
3. 実行（Execution） ― ツールを実行し結果を取得
4. 評価（Evaluation） ― 結果を確認し、目標が達成されたか判定
5. 繰り返しまたは完了 ― 未達なら1に戻り、達成なら最終回答を生成

このループにより、事前にすべての手順をハードコードする必要がなく、状況に応じた柔軟な処理が実現します。

実践：PRレビュー自動化エージェント

実際のユースケースとして、Pull Requestの自動レビューエージェントを構築してみましょう。

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  tools: [fetchIssueTool, readFileTool, postCommentTool],
  maxTurns: 20,
  systemPrompt: `あなたはコードレビューの専門家です。
PRの差分を読み、以下の観点でレビューしてください：
- バグの可能性
- セキュリティリスク
- パフォーマンス上の問題
- 改善提案`,
});

const result = await agent.run(
  "PR #42 をレビューして、問題があればコメントしてください"
);

systemPromptでエージェントの役割と判断基準を明示することで、一貫性のあるレビューが実現できます。

エラーハンドリングとリトライ

本番環境では堅牢なエラーハンドリングが不可欠です。

const agent = new Claude({
  model: "claude-sonnet-4-20250514",
  maxTurns: 10,
  onError: (error, context) => {
    console.error(`ステップ${context.turn}でエラー:`, error.message);
    if (context.turn >= 3) {
      return "abort"; // 3回失敗で中断
    }
    return "retry"; // それ以外はリトライ
  },
});

まとめと次のステップ

Agent SDKを使うことで、単発のAI応答ではなく、複数ステップにまたがる複雑なタスクを自動化できます。まずは小さなタスク（ファイル整理やログ分析など）から始め、徐々にツールを追加してエージェントの能力を拡張していくのがおすすめです。

Claude Codeの基本的な使い方については入門ガイドを、APIを活用した開発手法についてはAPI開発ガイドも合わせてご覧ください。CLIツールとの連携についてはCLIツール開発が参考になります。

さらに詳しい情報はAnthropic公式ドキュメントやClaude Code GitHub リポジトリをご確認ください。