Claude Agent SDKで自作エージェント

10秒でいうと

Claude Codeの中身を、ライブラリとして自分のプログラムから使えます。
ツールの往復を自分で書かずに済み、権限もサブエージェントもフックもそのまま使えます。

No.52でツール使用の往復を見ました。あの往復を自分で書くのが面倒だと感じたなら、それがAgent SDKの出番です。

何が違うのか
そのまま使えるもの
使える言語
いつAgent SDKを選ぶか
認証について
名前の使い方にも決まりがある
つまずきポイント
関連ページ
まとめ
次に読む

何が違うのか

公式ドキュメントの整理が的確なので、そのまま使います。

やりたいこと	使うもの
ツールの往復を自分で書かずにエージェントを作る	Agent SDK
ターミナルで対話しながら作業する	Claude Code CLI（第5章）
APIを直接呼び、往復も自分で書く	Client SDK（No.51、No.52）
長時間動くエージェントを、環境の管理なしで動かす	Managed Agents

Agent SDKは、Claude Codeと同じ仕組みを自分のプロセスの中で動かすものです。ターミナルのUIが無いClaude Code、と考えると近い。

そのまま使えるもの

第5章で扱ったものが、ほぼそのまま使えます。

組み込みの道具（読む、書く、コマンド実行、Web検索）
フック（No.41）
サブエージェント（No.23）
MCP（第6章）
権限（No.39）
セッション（続きから再開、分岐）
スキル・コマンド・メモリ（.claude/ と ~/.claude/ から自動で読まれる）
プラグイン（No.41）

.claude/ の設定がそのまま効くのが大きい。Claude Codeで作ったスキルやサブエージェントを、自作のエージェントでも使えます。

使える言語

PythonとTypeScriptのみです。

他の言語から使いたい場合は、CLIを子プロセスとして起動する方法があります（-p と --output-format json）。同じエージェントの動きを、どの言語からでも呼べます。

いつAgent SDKを選ぶか

判断の軸はエージェント的かどうかです。

Client SDKで足りるもの。

1回の呼び出しで答えが出る（分類、要約、抽出）
道具を使わない、または1〜2個で往復が単純
構造化出力で形を保証すれば済む（No.52）

Agent SDKが向くもの。

手順が事前に決まっていない
道具を何度も往復する
ファイルを読んで、書いて、実行して、確かめる
権限の制御が要る

見積書の仕事でいうと、PDFから項目を抜き出すだけならClient SDKで足ります。フォルダを見て、様式の違いを判断して、必要なら別の処理に切り替えるならAgent SDKです。

認証について

APIキーでの認証を使ってください。

公式が明記しています。Anthropicは、事前の承認がない限り、第三者の開発者が自社製品でclaude.aiのログインや利用枠を使うことを認めていません。Agent SDKで作ったエージェントも同じです。

自分のサービスに載せるなら、利用料は自分が持つという前提になります。No.53のコスト設計が、そのまま事業の設計になります。

名前の使い方にも決まりがある

意外に見落とされる点なので書いておきます。公式にブランドの指針があります。

使ってよいのは「Claude Agent」「Claude」「（自分の製品名）Powered by Claude」。

使えないのは「Claude Code」「Claude Code Agent」、およびClaude Codeを模した見た目。

自分の製品は自分のブランドを保つというのが原則です。社内ツールなら気にする場面は少ないですが、外に出すなら確認してください。

やってみよう：Client SDKとAgent SDKのどちらか判定する（3分）

プロンプト
“`
私が作りたいものを書きます。Client SDK（APIを直接呼ぶ）と
Agent SDK（Claude Codeの仕組みを使う）のどちらが向くか判定してください。

判定の理由には、次を含めてください。
・手順が事前に決まっているか
・道具の往復が何回必要か
・ファイルやコマンドを扱うか

作りたいもの：（ここに書く）
“`

期待される結果：判定と理由が返る。往復の回数が判断の中心になっている。

うまくいかないとき：どちらとも言えると返ってきたら、まずClient SDKで作ってみてください。足りないと感じてから移るほうが、無駄が少なくて済みます。

つまずきポイント

最初からAgent SDKを選ぶ。1回の呼び出しで済むものに使うと、重いだけです。Client SDKから。

claude.aiのログインを使わせようとする。認められていません。APIキーで。

権限の設定を飛ばす。自作エージェントでも、ファイルを書き、コマンドを実行します。第3章と第5章の話がそのまま当てはまります。

まとめ

Claude Codeの中身をライブラリとして使える。PythonとTypeScript
.claude/ の設定がそのまま効く。スキルもサブエージェントも共有できる
分かれ目は道具の往復が何回あるか
APIキーで認証する。claude.aiのログインは使わせられない

次に読む

自分のアプリに組み込む

→ ガイドの目次に戻る

※本記事の情報は 2026年8月時点のものです。