「AIエージェント」という言葉はよく聞くけれど、実際に自分のコードから動かすにはどうすればいいのかわからない……そう感じていませんか？Claude Codeの裏側で動いている仕組みは、実は自分のPythonやTypeScriptのコードからそのまま呼び出すことができます。この記事では、Claude Codeを使ってAIエージェントを作る第一歩を、インストールから実装例まで順番に解説します。
結論：Claude Agent SDKを使えば、数行のコードで自律的なAIエージェントが作れます
結論から言うと、Claude CodeのCLIを支えている仕組みは「Claude Agent SDK」というライブラリとしてPython・TypeScript向けに公開されています。pip install claude-agent-sdkまたはnpm install @anthropic-ai/claude-agent-sdkを実行し、query()という関数にプロンプトを渡すだけで、ファイルを読む・編集する・コマンドを実行するといった一連の作業を自律的にこなすAIエージェントが動き始めます。AIエージェントを自作するのは大変そうだと感じていませんか？実際にはAPIの呼び出しループを自分で書く必要がなく、思っているよりずっと少ないコードで始められます。
なぜAgent SDKがAIエージェント開発に向いているのか
理由は、Anthropicの通常のMessages APIでは「モデルがツールを使いたいと言ってきたら、自分でそのツールを実行して結果を返す」というループを自分で書く必要がありますが、Agent SDKではそのループ自体をSDKが代わりに実行してくれる点にあります。つまり、ファイル読み書きやコマンド実行といった処理を自分で実装しなくても、Claudeが直接ツールを実行し、結果だけが返ってくる仕組みになっています。私はこの違いを知ったとき、思っていたよりエージェント開発のハードルが低いと感じました。
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立ったもあります👇
→記事を読む
Claude CodeでAIエージェントを作る基本の流れ
ここからは、実際にAIエージェントを動かすまでの流れを順番に見ていきます。
1. インストールと認証
PythonとTypeScript、どちらも1行でインストールできます。
| 言語 | インストールコマンド | 必要条件 |
|---|---|---|
| Python | pip install claude-agent-sdk |
Python 3.10以上 |
| TypeScript | npm install @anthropic-ai/claude-agent-sdk |
特になし（CLIバイナリも同梱） |
インストール後、ANTHROPIC_API_KEYを環境変数に設定すれば認証は完了です。TypeScript版はClaude CodeのCLIバイナリを内部に同梱しているため、別途Claude Codeをインストールする必要がありません。
2. 最初のAIエージェントを動かす
最小構成のAIエージェントは、次のようなコードで動きます。
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="このディレクトリにあるTODOコメントを探して要約してください",
options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
):
print(message)
asyncio.run(main())
query()は非同期ジェネレータで、Claudeが考えた内容・ツールの呼び出し・ツールの実行結果・最終的な結果まで、一連のメッセージを順番に流してくれます。TypeScriptでも同じ感覚で書けます。
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "auth.tsのバグを見つけて修正してください",
options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
console.log(message);
}
3. AIエージェントが使えるツールを制限する
allowed_tools（Python）／allowedTools（TypeScript）に指定したツールだけが、そのAIエージェントから使えるようになります。指定していないツールはモデルにそもそも見えないため、これが最も基本的な権限管理の方法になります。
❌ すべてのツールを許可したまま本番運用する
✅ 「調査専用ならRead・Glob・Grepのみ」「修正も許すならEditを追加」のように用途別に絞る
◎ 編集系のAIエージェントにはpermission_mode="acceptEdits"のようなオプションも組み合わせる
4. 独自のツールをAIエージェントに追加する
組み込みツールだけでなく、自分で定義した関数をAIエージェントに使わせることもできます。Pythonでは@toolデコレータでツールを定義し、create_sdk_mcp_serverでまとめてエージェントに渡します。
from claude_agent_sdk import tool, create_sdk_mcp_server
@tool("get_weather", "指定した都市の天気を取得する", {"city": str})
async def get_weather(args):
# ここで実際の天気APIを呼び出す処理を書く
return {"content": [{"type": "text", "text": f"{args['city']}は晴れです"}]}
weather_server = create_sdk_mcp_server(
name="weather",
version="1.0.0",
tools=[get_weather],
)
社内システムや独自APIと連携したいAIエージェントを作るときは、この仕組みが土台になります。
さらに深掘り：業務で使えるAIエージェントに育てるための設計ポイント
最小構成のAIエージェントは数分で動かせますが、業務で使えるレベルに育てるにはもう一段の設計が必要です。私が実際にいくつか試してみて感じたポイントをまとめます。
| 設計ポイント | 内容 | 理由 |
|---|---|---|
| ツール権限を最小限にする | 必要なツールだけallowed_toolsに列挙する |
想定外のファイル変更やコマンド実行を防ぐため |
| 認証はAPIキーで行う | claude.aiのログインや契約プランのレート上限はSDK経由の外部提供では使えない | 商用利用のポリシー上、APIキー認証が前提になる |
| CLIとSDKを使い分ける | 対話的な開発はCLI、自動化・本番運用はSDK | 用途によって最適なインターフェースが異なる |
| MCPサーバーで外部連携する | 社内システムやSaaSとの連携はMCP経由で渡す | 独自ツールを毎回書かずに再利用できる |
CLIと何が違うのか、混乱しやすいポイント
Claude Codeを普段ターミナルで使っている人ほど、「CLIで使えていることはSDKでもそのままできるはず」と思いがちです。実際は、対話的な開発にはCLIが向いていて、CI/CDパイプラインや自社サービスへの組み込みのような自動化にはSDKが向いている、という役割分担になっています。私は最初この違いを意識せずに進めてしまい、本番運用を想定した設計をあとから手直しする羽目になりました。最初の段階で「これは人が対話する用途か、自動化して動かす用途か」を分けて考えるのが、結果的に手戻りを減らすコツだと思います。
スモールスタートで権限を絞ってから広げる
最初から大きな権限を与えるのではなく、Read系のツールだけで動かしてみて、挙動に納得できたら少しずつ書き込み系のツールを追加していく進め方をおすすめします。Qiitaでも見返したくなるような「育てていくAIエージェント」のイメージで、段階的に拡張していくのが安全だと感じています。
まとめ
- ✅ Claude Agent SDKを使えば、ツール実行ループを自分で書かずにAIエージェントを作れる
- ✅
allowed_toolsでツールを絞ることが、最も基本的な権限管理になる - ◎ 独自ツールは
@toolデコレータとcreate_sdk_mcp_serverで追加できる - ✅ 対話開発はCLI、自動化・本番運用はSDKという役割分担を意識する
- ◎ 最初は読み取り専用ツールだけで動かし、段階的に権限を広げる
エンジニアなら読むべき本を30冊以上紹介しています。
正直、私の仕事のやり方をガラッと変えた神本やSQLのチューニングに悩んだ時にめちゃくちゃ役に立ったもあります👇
→記事を読む