Claude Agent SDK

概要

Claude Agent SDK（@anthropic-ai/claude-agent-sdk）を使用したエージェント統合の実装を専門とするスキル。query() API、Hooksシステム、Permission Control、Electron統合、ストリーミング処理を支援します。

対象言語: TypeScript のみ

最新情報取得

SDK情報は頻繁に更新されるため、実装前に最新情報を確認してください。

# 最新情報を取得
node .claude/skills/claude-agent-sdk/scripts/fetch-latest-info.mjs

# npmパッケージ情報のみ
node .claude/skills/claude-agent-sdk/scripts/fetch-latest-info.mjs --category npm

詳細なURL一覧は references/official-urls.md を参照してください。

ワークフロー

Phase 1: 要件の明確化と設計方針の決定

目的: エージェント統合の要件を理解し、適切なパターンを選定する

アクション:

1. 使用するツール（Read, Edit, Bash等）を特定
2. Permission Control戦略を決定
3. references/query-api.md で基礎パターンを確認
4. references/permission-control.md で権限設計を確認

Task: agents/analyze-agent-requirements.md を参照

Phase 2: SDK統合の実装

目的: query() APIとHooksを実装し、エージェント機能を構築する

アクション:

1. assets/agent-handler-template.ts を参照してIPCハンドラを実装
2. references/hooks-system.md でHooksパターンを確認
3. references/electron-ipc.md でElectron統合パターンを確認
4. ストリーミング処理とエラーハンドリングを実装

Task: agents/implement-agent-integration.md を参照

Phase 3: 検証と記録

目的: 成果物の品質を確認し、ナレッジを記録する

アクション:

1. scripts/validate-agent-setup.mjs で設定の検証
2. Permission Controlのテスト
3. 実装パターンのドキュメント化

Task: agents/validate-agent-setup.md を参照

Task仕様ナビ

ベストプラクティス

すべきこと

• Permission Rulesで適切な権限制御を設計する
• PreToolUseフックで危険なコマンドをブロックする
• AbortSignalを使用してタイムアウト処理を実装する
• IPCチャネル名を一貫した命名規則で設計する
• ストリーミングメッセージを適切にUI更新に反映する
• エラー発生時のフォールバック処理を実装する

避けるべきこと

• permissionMode: 'auto' を本番環境で使用する
• Hookなしで危険なツール（Bash等）を許可する
• Main ProcessでUIロジックを処理する
• ストリーミング中のエラーを無視する
• APIキーをRenderer Processで扱う
• signal.abortedのチェックを省略する

クイックリファレンス

パッケージインストール

pnpm add @anthropic-ai/claude-agent-sdk

基本使用例

import { query } from "@anthropic-ai/claude-agent-sdk";

const conversation = query({
  prompt: "Hello, Claude!",
  options: {
    tools: ["Read", "Edit"],
    permissionMode: "ask",
  },
});

for await (const message of conversation.stream()) {
  console.log(message);
}

Hook実装例

const options = {
  hooks: {
    PreToolUse: async (input, toolUseID, { signal }) => {
      if (input.toolName === "Bash" && input.args.command?.includes("rm -rf")) {
        return { proceed: false, message: "危険なコマンドは許可されていません" };
      }
      return { proceed: true };
    },
  },
};

リソース参照

責務別ドキュメント

# query() API、SDKMessage型、ストリーミング
cat .claude/skills/claude-agent-sdk/references/query-api.md

# Hooksシステム（全イベント、実装パターン）
cat .claude/skills/claude-agent-sdk/references/hooks-system.md

# Permission Control（4層システム、ルール）
cat .claude/skills/claude-agent-sdk/references/permission-control.md

# Electron IPC統合
cat .claude/skills/claude-agent-sdk/references/electron-ipc.md

# エラーハンドリング
cat .claude/skills/claude-agent-sdk/references/error-handling.md

# MCP統合
cat .claude/skills/claude-agent-sdk/references/mcp-integration.md

# セキュリティとサンドボックス
cat .claude/skills/claude-agent-sdk/references/security-sandboxing.md

# 公式URL一覧
cat .claude/skills/claude-agent-sdk/references/official-urls.md

テンプレート参照

cat .claude/skills/claude-agent-sdk/assets/agent-handler-template.ts
cat .claude/skills/claude-agent-sdk/assets/use-agent-hook-template.ts

スクリプト実行

# 最新情報取得
node .claude/skills/claude-agent-sdk/scripts/fetch-latest-info.mjs --help

# 設定検証
node .claude/skills/claude-agent-sdk/scripts/validate-agent-setup.mjs --help

関連ドキュメント

変更履歴