こんにちは、株式会社TIMEWELLの濱本です。
前回の「Superpowers：Claude Codeプラグインで開発生産性を底上げする」で、開発ワークフロー側の強化について書きました。今回はその続編として、自社業務に特化した独自エージェントを作るための基盤である「Claude Agent SDK」を取り上げます。2026年4月時点、このSDKは旧Claude Code SDKから改名され、Python版とTypeScript版の両方が本番運用の実績を積みつつあります。さらに4月8日にはManaged Agentsがpublic betaで公開され、「エージェントを動かすインフラ」自体をAnthropicに任せられるようになりました。正直なところ、半年前と比べてエージェント開発の前提条件が一段変わったと感じています。
本稿では、SDKの概念整理から、PythonとTypeScriptの実装コード、MCP統合、Managed Agents、コスト最適化までを、社内で自動化エージェントを組みたい現場向けに書いていきます。「Claude Codeが便利なのはわかった、じゃあこれを自社業務に転用するには何をどう書くのか」という問いに答える一本です。
Claude Agent SDKとは何か、なぜ今これなのか
Claude Agent SDKは、Claude Codeを動かしているエージェントループ、組み込みツール、コンテキスト管理の仕組みを、そのままライブラリとして切り出したものです。パッケージ名はTypeScript側が@anthropic-ai/claude-agent-sdk、Python側がclaude-agent-sdk。Opus 4.7（claude-opus-4-7）を動かすにはv0.2.111以降が必要で、thinking.type.enabled系のエラーが出たらまずバージョンを疑うのが定跡です。
ここで誤解されやすいのが、Anthropic公式にはもうひとつ「Client SDK」（anthropicパッケージ）が存在する点です。両者の一番大きな違いは、ツール実行ループを誰が書くかにあります。Client SDKを使う場合、stop_reason === "tool_use"を見てツールを実行し、結果を次のリクエストに渡す、という手続きをアプリ側で組む必要があります。Agent SDKは、このループをClaude側が握ってくれる。開発者が書くのは「プロンプト」と「許可するツール」だけで、実行はSDKが勝手に回します。プロトタイプで小さい会話ボットを作るだけならClient SDKで十分ですが、ファイル操作や複数ステップの作業を任せたい時点でAgent SDKに切り替わる、というのが私の基準です。
組み込みツールは現在9種類あります。Read、Write、Edit、Bash、Monitor、Glob、Grep、WebSearch、WebFetch、それに確認質問用のAskUserQuestion。これだけあれば、ファイルを読んで直して、Bashを叩いてテストを回して、外部情報を拾ってくる、という基本動作は追加実装ゼロで動きます。OpenAI Agents SDKが「空のツールレジストリ＋hosted tools」で始まるのと比較すると、初期速度はClaude Agent SDKに軍配が上がります1。
そして2026年4月にManaged Agentsが登場したことで、「エージェントを本番で走らせる」こと自体の難易度が一段下がりました。SiliconANGLEの4月8日付の記事によれば、これまで「導入まで数ヶ月」だった独自エージェントの立ち上げを、Managed Agentsは「数日」に圧縮するのが狙いです2。後述しますが、サンドボックス、認証、セッション永続化、ツール実行、トレーシングがマネージドで、料金はモデル利用料＋$0.08/agent runtime hourという構造になっています。
最小構成で動かす：PythonとTypeScriptの実装
最初のエージェントを動かすまでの手順は、想像よりずっと単純です。APIキーを環境変数に置いて、パッケージを入れて、query関数を1回呼ぶだけ。まずPython版から見ます。
# pip install claude-agent-sdk
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"],
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
queryは非同期ジェネレータで、Claudeが生成する各メッセージを逐次返してきます。allowed_toolsに読み取り系だけを並べているので、このエージェントはファイルを書き換えたりBashを叩いたりしません。読んで、検索して、要約を返すだけ。「まず安全な範囲で動かして感触を掴む」段階ではこの形が基本です。
TypeScript版はほぼ同じです。依存関係に@anthropic-ai/claude-agent-sdkを入れるだけで動きます。
// npm install @anthropic-ai/claude-agent-sdk
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "src配下のTODOコメントを洗い出して優先度つきで要約して",
options: {
allowedTools: ["Read", "Glob", "Grep"],
},
})) {
if ("result" in message) {
console.log(message.result);
}
}
TypeScript版の地味にありがたい仕様として、Claude Codeネイティブバイナリがoptional dependencyとしてプラットフォーム別に同梱されます。つまりNode.jsさえ入っていれば、Claude Codeを別途インストールしなくてもそのまま走る。CIやサーバーレス環境に載せるときにハマりにくい構造になっています。
ここで一歩進めて、ファイル編集まで許可する例も置いておきます。
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "utils.tsのany型を具体的な型定義に置き換えて、ユニットテストも更新して",
options: {
allowedTools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"],
permissionMode: "acceptEdits",
},
})) {
console.log(message);
}
permissionMode: "acceptEdits"にすると、編集系のツール呼び出しをいちいち確認せず自動適用します。CI上で回す夜間バッチ的な用途ではこれでいいのですが、対話的に動かすツールではデフォルトのままで、人間が確認ステップを挟む運用にするのが安全です。私の基準では、本番でacceptEditsを使うのは「対象ファイルが明確に限定されていて、失敗しても戻せる」ケースだけに絞っています。
Hooks、Subagents、MCPで業務特化させる
組み込みツールと最小queryだけでは、当然ながら自社の業務にはフィットしません。Agent SDKが面白いのは、ここから先の拡張ポイントが3本きれいに分かれている点です。Hooks、Subagents、MCP。この3つを理解すれば、既製のClaude Codeを「自社のワークフロー実行役」に仕立て直せます。
Hooksは、エージェントのライフサイクルに割り込むコールバックです。PreToolUse、PostToolUse、Stop、SessionStart、SessionEnd、UserPromptSubmitなどのタイミングで任意の処理を差し込めます。たとえば「ファイル編集が走ったら監査ログに必ず残す」という要件は、次のように書けます。
import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
async def log_file_change(input_data, tool_use_id, context):
file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
with open("./audit.log", "a") as f:
f.write(f"{datetime.now().isoformat()}\t{file_path}\n")
return {}
async def main():
async for message in query(
prompt="configディレクトリの古い設定値を最新仕様に合わせて修正して",
options=ClaudeAgentOptions(
permission_mode="acceptEdits",
hooks={
"PostToolUse": [
HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
]
},
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
監査ログだけでなく、「PreToolUseで特定のパスへの書き込みをブロックする」「UserPromptSubmitで入力をバリデーションする」など、ガードレールとしても使えます。企業導入で必ず出てくる「勝手なことをさせないでほしい」という要求に、この仕組みが効きます。
Subagentsは、専門タスクを切り出した子エージェントを定義して、本体から呼び出す仕組みです。コードレビュー担当、セキュリティ監査担当、翻訳担当のように役割を分けて、親エージェントが必要に応じて振り分ける。Python側のサンプルだとこんなかたちになります。
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition
async for message in query(
prompt="このPRの変更をcode-reviewerで精査して、重大度順にまとめて",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Agent"],
agents={
"code-reviewer": AgentDefinition(
description="品質とセキュリティの観点でコードを精査する専門エージェント。",
prompt="変更差分を読み、バグ、型の不整合、セキュリティリスクを優先度つきで返す。",
tools=["Read", "Glob", "Grep"],
)
},
),
):
...
ここで大事なのは、allowed_toolsにAgentを明示的に含める点です。SubagentはAgentツール経由で呼ばれるので、ここを書き忘れると親エージェントから呼び出せません。また、各SubagentにはそのSubagent専用のツールセットを渡せるので、「レビュー担当には書き込み権限を一切持たせない」といった原則も、この層で強制できます。
MCP（Model Context Protocol）統合は、Agent SDKを「Claudeだけでは触れない外部システム」に接続するための標準インターフェイスです。PlaywrightでブラウザをつかませたりSlackやGitHubに直接つないだり、自社DBにぶら下げたり。オープンソースだけで何百ものMCPサーバーが公開されています3。ブラウザ自動化の例はこうです。
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "example.comを開いて見出しを全部抽出して、スクリーンショットを残して",
options: {
mcpServers: {
playwright: { command: "npx", args: ["@playwright/mcp@latest"] },
},
allowedTools: ["WebFetch"],
},
})) {
console.log(message);
}
MCPのいいところは「Claude専用APIを個別に叩く」のではなく、オープンプロトコルで書いたツールがそのままOpenAI側でもGoogle側でも使える、と期待できる点です。自社でMCPサーバーを1本立てておけば、モデル選定で将来もめても、接続層を作り直さずに済みます。これは、複数ベンダーを併用する大企業ほどメリットが大きい設計です。
Managed Agentsで運用をAnthropicに任せる
ここまでは全部、自前のマシンやCI、Cloud Runなどで走らせる前提の話でした。2026年4月8日に公開されたManaged Agentsは、そのレイヤーを丸ごとマネージドにするプロダクトです。InfoQの解説によれば、Managed Agentsが受け持つのはオーケストレーション、サンドボックス、セッション状態の管理、認証情報、永続化の5点4。開発者はエージェントの振る舞いとツールとガードレールを書くだけでよく、ランタイムはAnthropic側が面倒を見ます。
料金構造はシンプルです。モデル利用料に加えて、agent runtime 1時間あたり$0.08が乗る。長時間走りっぱなしのバックグラウンドエージェント（たとえばSlack常駐ボット）を自前で組むと、EC2なりCloud Runなりのインスタンス費用、監視、ログ収集、セッションストアのRedisやDynamoDBまで込みで、月で見ると数百ドルに跳ねるのが普通でした。$0.08/時なら、フル稼働でも月60ドル前後。運用工数を考えると、まずManaged Agentsで立ち上げる選択は十分に合理的です。
機能面では、スコープ付き権限、ID管理、実行トレースがConsoleに統合されていて、誰がどのツールを呼んで何を得たかが全部追える。マルチエージェント協調と自己評価は2026年4月時点でまだリサーチプレビューですが、いずれも別途申請すれば触れるようになるとアナウンスされています5。
私自身の温度感としては、「社内向けAIエージェントを本番で立ち上げたい」というフェーズの企業にとって、Managed Agentsはかなり強い選択肢だと思っています。理由は2つ。1つ目は、独自SREチームを持たない会社でもセッション永続化と監査ログを標準で手に入れられること。2つ目は、エージェントのツール呼び出しを全部Consoleで追えるため、「AIが何をしたか説明してほしい」という経営層の典型的な要求に、そのままエビデンスで応えられること。ガバナンスの観点でここが弱いと、そもそも本番に出せないケースが多い。
ただし、2026年4月時点でベンダーロックインの度合いは明確に強まります。Managed Agentsに載せたエージェントを他ベンダーに引っ越すのは、自前SDK実装をDockerで動かしている場合より格段に大変です。私の推奨は、ロジック本体はPythonかTypeScriptのSDK層に寄せておき、ランタイムだけManaged Agentsに載せる。こうしておけば、必要になったときに自前クラスタへの降格移行がきれいに効きます。
コスト最適化と本番運用で効くパターン
エージェントを作ると、最初のひと月で必ず経理から呼ばれます。「Claudeのトークン代、これで合ってますか」と。Agent SDKはデフォルトで結構賢くコストを抑える作りになっていますが、知っておくべき論点が3つあります。
1つ目はプロンプトキャッシュです。Agent SDKは再利用可能なシステムプロンプトやツール定義を自動でキャッシュします。Anthropic公式ドキュメントによれば、cache_read_input_tokensの単価は通常の入力トークンの約10%6。長文のシステムプロンプトや大量のツール定義を毎回そのまま送るのと比べて、ここだけで60%超のトークン削減が現実的に見えるケースが報告されています。開発者がやるべきことは「変わらない部分を先頭に置く」だけで、あとはSDKが勝手に判定してくれます。
2つ目はオートコンパクションです。長時間セッションでは文脈が肥大してトークンが爆発しがちですが、SDKは文脈上限に近づくと会話履歴を自動で要約圧縮します。Claude Code本体と同じ仕組みで、開発者側のコードは一切いじらなくていい。これがあるので、1日中立ち上がりっぱなしのエージェントでも、文脈を気にせず動かせます。
3つ目はTool searchです。MCPサーバーを多く繋ぐと、ツール定義だけで数万トークンに達することが珍しくありません。Tool searchは、ツール定義をコンテキストから一旦外して、Claudeが「このタスクにはこのツールが要る」と判断した時のみロードする仕組みです。MCPを10個以上繋ぐような構成では、ここを有効化するだけでスタート時の固定コストが大きく下がります。
運用面の実感としては、エージェントのコストは「モデルの賢さ」ではなく「文脈の設計」で9割決まります。システムプロンプトをキャッシュに乗るように構造化し、ツールは必要最小限に絞り、Hooksで不要な処理をブロックする。このあたりを設計の最初に組み込むのと、後から削るのでは、運用コストが2倍3倍で違ってきます。
TIMEWELLでは、こうした独自エージェントの企画から本番運用までを支援するコンサルティングとして「WARP」を提供しています。エージェントで何を自動化すべきか、社内ナレッジのどこをエンタープライズAI基盤である「ZEROCK」に載せると効くか、といった一段上のレイヤーから入る伴走型の支援です。Agent SDKの実装だけ切り出してお願いしたい場合もご相談いただけますし、そもそも自社のどの業務をエージェント化すべきか、という議論から始めることもできます。この手のプロジェクトは、最初の1ヶ月でアーキテクチャを誤るとその後ずっと引きずるので、設計段階で第三者の視点を入れておくと、後の数十時間を節約できます。
実装を始めるための最初の10日間
ここまでの話を踏まえて、これから始める人向けに具体的な10日間の進め方を置いておきます。まず1〜2日目で、組み込みツールだけの最小queryを動かす。allowedToolsをRead、Glob、Grepに絞って、社内リポジトリを読ませてTODO抽出や仕様書生成を試す。この段階で「うちの社内テキストをClaudeに食わせた時、何が出てくるか」の解像度が上がります。
3〜5日目はHooksとPermissionsの設計です。自社で絶対に触られたくないパスをPreToolUseでブロックするルール、監査ログをPostToolUseで必ず吐くルール、の2本を入れる。ここを入れずに編集系ツールを許可すると、私の経験上、数日のうちに「そんなファイルまで触ると思わなかった」事件が起きます。ここを3日かけてでも固めるのが、結果的に一番の近道です。
6〜8日目はMCP統合。自社でどうしても繋ぎたいデータソース（SlackやGitHub、社内DB、あるいはClaude Code Skillsで整理された自社ナレッジ）を1つ選び、MCPサーバー経由でエージェントから触らせる。OSS化されているMCPサーバーが多いので、自作より先にまずは既存を探すのが鉄則です。
9〜10日目で本番運用形態を決める。自前インフラに載せるか、Managed Agentsに載せるか。判断基準は、「SREチームがいるか」「監査ログをどれだけ厳密に持つ必要があるか」「コスト上限の見通し」の3つです。SREチームがなくて監査要件が厳しい企業は、迷わずManaged Agents。逆に、既存のKubernetes基盤があってエージェントを他のワークロードと混ぜたい場合は、自前運用のほうが素直です。
余談ですが、この10日間の前に、エンタープライズAIを本当に社内に入れるなら、ガバナンスの方針合意を先に済ませておく必要があります。「Google Cloud Next 2025：エンタープライズAIエージェント時代」の記事でも触れたとおり、AIエージェントはデータの持ち方と権限設計がすべての土台です。Agent SDKの実装力があっても、この土台が揺らいでいると、本番投入の直前に必ず止まります。技術の前に、まず社内合意。これが2026年のAIエージェント導入の、もっとも地味で、もっとも効くアドバイスです。
Agent SDKを触り始めると、「今まで人手でやっていた確認作業の8割が、エージェント側に寄せられる」ことに気づきます。そこからが本題です。何を寄せて、何を人間に残すのか。この線引きこそがこれからの企画者の仕事で、SDKの使い方はその手段にすぎません。手段の学習コストが下がった今、本当に問われるのは自社の業務設計そのもの。そう考えると、Claude Agent SDKは単なる便利ライブラリではなく、企業のオペレーション設計を見直す触媒として見たほうが、受け取り方を間違えずに済むと思います。