# Claude Agent SDKの便利だけど知られていない機能 🌍 エージェントの実行コスト、ちゃんと把握できていますか？詳細なトラッキングで可視化しましょう！ Claude Agent SDKは、クエリごとにトークン使用量とコストの詳細な内訳を提供します。 📌 タイトル：詳細なコスト・使用量トラッキング 🔗 URL： 🧩 概要 `ResultMessage` には `total_cost_usd`（推定コスト）、`usage`（トークン内訳）、`num_turns`（ターン数）が含まれており、成功・エラーを問わずすべての結果で取得可能です。さらに `model_usage`（Python）/ `modelUsage`（TypeScript）を使えば、モデルごとのコスト・トークン内訳も確認できます。並列ツール実行時は同一メッセージIDで重複するため、IDベースの重複排除が正確なカウントに必要です。 🛠 使い方 ```python # Python - クエリの総コストを取得 from claude_agent_sdk import query, ResultMessage async for message in query(prompt="プロジェクトを要約してください"): if isinstance(message, ResultMessage): print(f"総コスト: ${ or 0}") # モデルごとの内訳 if message.model_usage: for model, usage in message.model_usage.items(): print(f" {model}: ${usage['costUSD']:.4f}") print(f" 入力トークン: {usage['inputTokens']}") print(f" キャッシュ読取: {usage['cacheReadInputTokens']}") ``` ```typescript // TypeScript - 複数クエリのコストを累積 import { query } from "@anthropic-ai/claude-agent-sdk"; let totalSpend = 0; for (const prompt of prompts) { for await (const message of query({ prompt })) { if (message.type === "result") { totalSpend += // モデルごとの内訳 for (const [model, usage] of Object.entries(message.modelUsage)) { console.log(`${model}: $${usage.costUSD.toFixed(4)}`); } } } } console.log(`合計: $${totalSpend.toFixed(4)}`); ``` 🏗 本番システムへの組み込み方 ・`total_cost_usd` を監視システムに送信して、コスト傾向をリアルタイムで可視化します ・`model_usage` でモデル別コストを分析し、サブエージェントのコスト配分を最適化します ・`resume` で同一セッションを再開した呼び出しの結果には、そのセッションの過去の利用分も含まれます（Claude Code v2.1.277 以降）。この場合は最新の結果を読み、合算すると二重計上になります。セッションを共有しない独立した呼び出しはアプリケーション側で合算ロジックを実装します ・エラー時もコストは発生するため、失敗した `ResultMessage` からも必ずコストを記録します 💡 ユースケース 💰 マルチテナント環境でユーザーごとの利用コストをレポートする 📊 モデル別のコスト内訳を分析して、最適なモデル構成を見つける 🔍 キャッシュトークン（`cache_read_input_tokens`）の割合を監視して、プロンプトキャッシュの効果を測定する ⚠️ 注意点 ・`total_cost_usd` はクライアント側の概算値であり、実際の請求額とは異なる場合があります。正確な請求情報は Usage and Cost API を利用してください ・並列ツール呼び出し時は同一IDのメッセージが重複するため、IDで重複排除しないとトークン数が膨らみます ・`ENABLE_PROMPT_CACHING_1H` を設定すると1時間TTLのキャッシュが有効になりますが、書き込みコストが高くなります ✨ コストの可視化なくしてコスト最適化なし。まずはトラッキングを組み込んで、エージェントの「お財布事情」を把握しましょう！ #ClaudeAgentSDK# #AIAgent#

# Claude Agent SDKの便利だけど知られていない機能 🌍 複雑なタスクの進捗、見失っていませんか？構造化タスクトラッキングで可視化できます！ Claude Agent SDKには、エージェント実行中のタスク管理と進捗表示を行う組み込み機能があります。 📌 タイトル：構造化タスク(Todo)トラッキング 🔗 URL： 🧩 概要 `TaskCreate`、`TaskUpdate`、`TaskGet`、`TaskList` の4つのツールを使って、エージェント実行中の構造化タスク管理が可能です。これらのタスクトラッキングツールは Claude 3.x 系、Opus 4〜4.7、Sonnet 4〜4.6、Haiku 4.5 でのみデフォルトで提供され（Claude Code v2.1.268 以降、TypeScript SDK は v0.3.268 以降がこの既定を同梱）、それ以外のモデルではオプトインが必要です。エージェントは複数ステップの作業を自動的にタスクとして登録し、`pending` → `in_progress` → `completed` のライフサイクルで進捗を管理します。従来の `TodoWrite` は全リストを毎回上書きしていましたが、新しい Task ツールでは個別のタスク単位で作成・更新できるため、より細かい進捗追跡が実現できます。 🛠 使い方 ```python # Python - TaskCreate/TaskUpdate のストリームを監視 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock async for message in query( prompt="React アプリのパフォーマンスを最適化してください", # 既定で Task ツールが提供されないモデルでも有効化する options=ClaudeAgentOptions(env={"CLAUDE_CODE_ENABLE_TODO_TOOLS": "1"}), ): if not isinstance(message, AssistantMessage): continue for block in message.content: if not isinstance(block, ToolUseBlock): continue if == "TaskCreate": print(f"+ {block.input['subject']}") elif == "TaskUpdate" and block.input.get("status"): # ストリーム上のキー名は修復前の生の形（id / task_id の場合がある） task_id = ( block.input.get("taskId") or block.input.get("id") or block.input.get("task_id") ) print(f" {task_id} -> {block.input['status']}") ``` ```typescript // TypeScript - タスクの作成と更新をリアルタイム表示 import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Optimize my React app performance", // 既定で Task ツールが提供されないモデルでも有効化する options: { env: { ...process.env, CLAUDE_CODE_ENABLE_TODO_TOOLS: "1" } }, })) { if (message.type !== "assistant") continue; for (const block of message.message.content) { if (block.type !== "tool_use") continue; if ( === "TaskCreate") { console.log(`+ ${block.input.subject}`); } else if ( === "TaskUpdate") { // ストリーム上のキー名は修復前の生の形（id / task_id の場合がある） const taskId = block.input.taskId ?? ?? block.input.task_id; if (taskId && block.input.status) console.log(` ${taskId} -> ${block.input.status}`); } } } ``` 🏗 本番システムへの組み込み方 ・タスクの進捗をUIのプログレスバーやチェックリストに反映して、ユーザーに作業状況を可視化します ・`TaskCreate` の結果から `taskId` を取得し、マップで管理することで完全なタスク一覧を構築できます ・`TaskList` のツール結果を監視してスナップショットを取得し、ダッシュボードに表示します ・3ステップ以上の複雑なタスクで自動的にタスクが作成されるため、長時間実行の監視に活用できます 💡 ユースケース 📋 大規模リファクタリングの進捗をリアルタイムでチームに共有する 🔄 CI/CDパイプラインでエージェントの各ステップの完了状況を追跡する 📊 マルチステップのコード分析で、どの分析が完了したかをダッシュボードに表示する ⚠️ 注意点 ・`TaskCreate` の入力には `taskId` は含まれません。対応する `tool_result` ブロックから `{ task: { id, subject } }` として取得する必要があります ・既定でツールが提供されないモデルでは、`allowed_tools` にツール名を挙げる、`tools` オプションに列挙する、`env` で `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` を設定する、のいずれかでオプトインが必要です（オプトインしないと該当の `tool_use` ブロックはストリームに現れません）。逆に `CLAUDE_CODE_ENABLE_TASKS=0` を設定すると、4つの Task ツールの代わりに旧 `TodoWrite` が提供されます ・`status` を `"deleted"` に設定するとタスクを削除できます ✨ 複数ステップの作業を「何をやっているか分からない」状態で待つのはストレスフルです。タスクトラッキングを活用して、エージェントの作業をガラス張りにしましょう！ #ClaudeAgentSDK# #AIAgent#

Claude DashboardsとClaude Motionがリリース！ Dashboards → 自然言語で質問するだけで、データを自動更新するダッシュボードを生成。 Motion → レポートやグラフなどからアニメーションを生成。文字や数値を編集でき、MP4形式で出力可能。 本日よりベータ版を提供。

# Claude Agent SDKの便利だけど知られていない機能 🌍 エージェントの作業ディレクトリ外のファイルにもアクセスを許可できる additionalDirectories オプションをご紹介します。 モノレポや共有ライブラリなど、複数ディレクトリにまたがるプロジェクトで威力を発揮します。 📌 タイトル：作業ディレクトリ外への追加アクセス許可 🔗 URL： 🧩 概要 `additionalDirectories` は `query()` のオプションで、エージェントが作業ディレクトリ（cwd）以外のパスにアクセスすることを許可する機能です。通常、エージェントは cwd 内のファイルのみを操作できますが、このオプションで追加のディレクトリを指定すると、そのパス内のファイルも読み書きできるようになります。`acceptEdits` パーミッションモードでは、追加ディレクトリ内の編集も自動承認されます。モノレポの別パッケージや共有ライブラリのディレクトリにアクセスする場合に特に有用です。 🛠 使い方 `query()` のオプションに `add_dirs`（TypeScript では `additionalDirectories`）を渡します。 ```python from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage # モノレポ内の複数パッケージにアクセスを許可 async for message in query( prompt="Update the shared utility functions and fix the imports in the web app", options=ClaudeAgentOptions( # cwd はデフォルトでプロセスの現在ディレクトリ add_dirs=[ "/path/to/monorepo/packages/shared-utils", "/path/to/monorepo/packages/web-app", ], permission_mode="acceptEdits", # 追加ディレクトリ内の編集も自動承認 allowed_tools=["Read", "Edit", "Write", "Grep", "Glob"], ), ): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) # 共有ライブラリとメインプロジェクトを同時に操作 async for message in query( prompt="Check the shared library API and update our integration code", options=ClaudeAgentOptions( add_dirs=[ "/path/to/shared-library", ], allowed_tools=["Read", "Edit", "Grep", "Glob"], ), ): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) ``` 🏗 本番システムへの組み込み方 ・モノレポ構成では、関連するパッケージのパスを `add_dirs` に列挙することで、パッケージ間の依存関係を考慮した変更が可能になります ・`acceptEdits` モードと組み合わせると、追加ディレクトリ内のファイル編集（Edit、Write）やファイルシステム操作（mkdir、rm、mv、cp）も自動承認されます ・保護対象のパスへの書き込みは追加ディレクトリに含めても依然としてプロンプトが表示されます 💡 ユースケース 📦 モノレポ開発：共有パッケージと個別アプリの両方を同時に変更する 📚 共有ライブラリ参照：外部ライブラリのソースを読み取り、正しいAPI使用法を確認しながらコーディングする 🔧 設定ファイルの集中管理：プロジェクト外の設定ディレクトリにアクセスして設定を更新する ⚠️ 注意点 ・追加ディレクトリ外のパスへのアクセスは引き続きブロックまたはプロンプトが表示されます ・`bypassPermissions` モードでは全パスが許可されるため、`add_dirs` の設定とは無関係に動作します ・エージェントのセキュリティ境界を広げることになるため、必要最小限のパスのみを指定してください ・`acceptEdits` での自動承認は cwd と追加ディレクトリの範囲内に限定されます ✨ additionalDirectories を活用することで、複数ディレクトリにまたがるプロジェクトでもエージェントがシームレスに作業できるようになります。 #ClaudeAgentSDK# #AIAgent#

Claude Codeで中〜大規模の開発を一気に進めるときは、複数のセッションに役割を分けて、1つ「司令塔」を作るとうまくいきます。 例えば、 ・実装担当 ・テスト担当 ・レビュー担当 ・司令塔 のように分ける。 司令塔には、各セッションの進捗やエラーを定期的に確認させて、問題があれば修正指示を出してもらう。 Claude CodeのAgent Teamsでは、複数のエージェント同士でコミュニケーションしながら並列で作業できるのがめっちゃ良い。 全部のセッションを自分で追い続けると普通に脳が疲弊するので、プロジェクトごとに「司令塔」を置くのがおすすめです。

# Claude Agent SDKの便利だけど知られていない機能 🌍 @tool デコレータと create_sdk_mcp_server で、独自の関数をエージェントのツールとしてインプロセスで実行できます。 データベースアクセス、外部API呼び出し、ドメイン固有のロジックをエージェントに提供する方法を解説します。 📌 タイトル：インプロセス・カスタムツール (create_sdk_mcp_server / @tool) 🔗 URL： 🧩 概要 カスタムツールは、SDK のインプロセス MCP サーバーを使って独自の関数を Claude から呼び出せるようにする機能です。Python では `@tool` デコレータ、TypeScript では `tool()` ヘルパーでツールを定義し、`create_sdk_mcp_server` でラップして `query()` に渡します。ツールはアプリケーションプロセス内で実行され、別プロセスは不要です。ツール名は `mcp__{server_name}__{tool_name}` の形式になります。`readOnlyHint` アノテーションで並列実行を有効にし、`isError` で復旧可能なエラーをエージェントに伝え、画像（base64）やリソースの返却も可能です。 🛠 使い方 `@tool` デコレータでツールを定義し、`create_sdk_mcp_server` でサーバーにまとめます。 ```python from typing import Any import httpx from claude_agent_sdk import tool, create_sdk_mcp_server, query, ClaudeAgentOptions, ResultMessage @tool( "get_temperature", "Get the current temperature at a location", {"latitude": float, "longitude": float}, ) async def get_temperature(args: dict[str, Any]) -> dict[str, Any]: async with httpx.AsyncClient() as client: response = await client.get( "", params={ "latitude": args["latitude"], "longitude": args["longitude"], "current": "temperature_2m", }, ) data = response.json() return { "content": [ {"type": "text", "text": f"Temperature: {data['current']['temperature_2m']}"} ] } # インプロセスMCPサーバーにラップ weather_server = create_sdk_mcp_server( name="weather", version="1.0.0", tools=[get_temperature], ) # query() に渡して使用 async for message in query( prompt="What's the temperature in Tokyo?", options=ClaudeAgentOptions( mcp_servers={"weather": weather_server}, allowed_tools=["mcp__weather__get_temperature"], ), ): if isinstance(message, ResultMessage) and message.subtype == "success": print(message.result) ``` 🏗 本番システムへの組み込み方 ・エラーハンドリングでは例外をスローせず `{"is_error": True}` を返すことで、エージェントループを継続させつつ Claude にリカバリーさせることができます ・`readOnlyHint=True` アノテーションを設定すると、副作用のないツールを他のリードオンリーツールと並列実行できます ・画像を返す場合は `{"type": "image", "data": base64_str, "mimeType": "image/png"}` 形式のコンテンツブロックを使用します ・`structuredContent` フィールドでツール結果を機械可読な JSON として返却できます（ただし Python の `@tool` では未サポート、スタンドアロン MCP サーバーが必要） 💡 ユースケース 🗄 データベースアクセス：エージェントに直接 DB クエリを実行させる 🌐 外部API連携：社内 API やサードパーティサービスをツールとして公開する 📊 データ可視化：グラフを生成し画像（base64）として返却する 🔧 ドメインロジック：計算、変換、バリデーションなど特定の業務ロジックをツール化する ⚠️ 注意点 ・Python の dict スキーマではすべてのキーが必須になります。オプションパラメータは schema に含めず、description で説明して `args.get()` で読み取ってください ・`structuredContent` は Python の `@tool` デコレータでは転送されません（スタンドアロン MCP サーバーを使用） ・ツール検索（tool search）はデフォルトで有効で、SDK MCP ツールのスキーマは必要になるまで遅延ロードされます。無効にすると `tools` 配列のすべてのツールが毎ターンのコンテキストを消費します ・アノテーションはメタデータであり強制力はありません。`readOnlyHint=True` でも handler が書き込みを行う場合があります ✨ インプロセスのカスタムツールにより、エージェントの能力を自由に拡張でき、外部プロセスの管理も不要です。 #ClaudeAgentSDK# #AIAgent#