claude-agent-sdk-best-practice

Claude Agent SDK v0.2.101 best practices and complete API reference. Use when: building AI agents with @anthropic-ai/claude-agent-sdk, designing multi-agent systems, configuring MCP servers, implementing hooks/permissions, using structured outputs, managing sessions, or troubleshooting SDK errors. Covers query() API, V2 session API, 22 hook events, sandbox, worktree isolation, and current public configuration options.

설치로 이동

저장소: wquguru/morpho-claude
최근 소스 활동: 2026년 4월 14일 16:05
감지된 SKILL.md 언어: 영어
스타: 4
포크: 0

설치 방법

기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.

Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.

직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.

npx skills add https://github.com/wquguru/morpho-claude --skill claude-agent-sdk-best-practice

명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.

로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.

소스 파일 검토

설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.

파일 탐색기

8 개 파일

SKILL.md

소스 지침 · 읽기 전용 미리보기

검색으로 돌아가기 설치로 돌아가기

import {
  forkSession,                    // Fork existing transcript into a new branch
  getSessionInfo,                 // Read single-session metadata
  getSessionMessages,             // Read session history
  listSessions,                   // List past sessions
  listSubagents,                  // List subagents for a session (v0.2.89+)
  getSubagentMessages,            // Read subagent message history (v0.2.89+)
  query,                          // V1 API
  renameSession,                  // Set custom transcript title
  tagSession,                     // Set/clear transcript tag
  createSdkMcpServer,            // In-process MCP server
  tool,                           // MCP tool helper
  unstable_v2_createSession,      // V2 session API
  unstable_v2_resumeSession,      // V2 resume
  unstable_v2_prompt,             // V2 one-shot
} from "@anthropic-ai/claude-agent-sdk";

// Minimal agent
const q = query({ prompt: "Analyze this code", options: { model: "claude-sonnet-4-6" } });

// Production agent with safety
const q = query({
  prompt: "Deploy to staging",
  options: {
    model: "claude-sonnet-4-6",
    permissionMode: "default",
    allowedTools: ["Read", "Grep", "Glob", "Bash"],
    sandbox: { enabled: true, autoAllowBashIfSandboxed: true },
    maxTurns: 20,
    maxBudgetUsd: 5.0,
    thinking: { type: "adaptive" },
  }
});

// CI/CD headless agent
const q = query({
  prompt: taskFromCI,
  options: {
    model: "claude-sonnet-4-6",
    permissionMode: "bypassPermissions",
    settingSources: ["project"],
    sandbox: { enabled: true },
    maxBudgetUsd: 10.0,
    taskBudget: 50,                        // Max tool calls (v0.2.91+)
    includeHookEvents: true,               // Emit hook lifecycle messages (v0.2.91+)
    outputFormat: { type: "json_schema", schema: resultSchema },
  }
});

const q = query({ prompt: "...", options: { ... } });

for await (const message of q) {
  switch (message.type) {
    case "system":
      if (message.subtype === "init") sessionId = message.session_id;
      break;
    case "assistant":
      // Full assistant response with BetaMessage
      break;
    case "result":
      if (message.subtype === "success") {
        console.log(message.result);
        console.log(message.structured_output); // if outputFormat set
        console.log(`Cost: $${message.total_cost_usd}`);
      }
      break;
  }
}

const q = query({ prompt: "..." });
await q.interrupt();                          // Interrupt current turn
await q.setModel("claude-opus-4-6");          // Switch model mid-session
await q.setPermissionMode("acceptEdits");     // Change permissions
q.close();                                    // Force terminate

// Introspection
const agents = await q.supportedAgents();
const models = await q.supportedModels();
const status = await q.mcpServerStatus();
const account = await q.accountInfo();
const usage = await q.getContextUsage();      // Token budget breakdown by category (v0.2.86+)
const settings = await q.getSettings();       // Applied settings: model, effort, etc. (v0.2.72+)

// Subagent inspection (v0.2.89+)
const subagents = await q.listSubagents(sessionId);
const subMsgs = await q.getSubagentMessages(sessionId, subagentId);

// MCP management
await q.reconnectMcpServer("my-server");
await q.toggleMcpServer("my-server", false);
await q.setMcpServers({ "new-server": config });
await q.enableChannel("my-server", "channel-name"); // Activate MCP channel (v0.2.84+)

// Plugin management (v0.2.85+)
await q.reloadPlugins();

// File checkpointing (requires enableFileCheckpointing: true)
await q.rewindFiles(userMessageId);

const q = query({
  prompt: "Analyze this PR",
  options: {
    outputFormat: {
      type: "json_schema",
      schema: {
        type: "object",
        properties: {
          summary: { type: "string" },
          risk_level: { type: "string", enum: ["low", "medium", "high"] },
          issues: { type: "array", items: { type: "string" } }
        },
        required: ["summary", "risk_level", "issues"]
      }
    }
  }
});

for await (const msg of q) {
  if (msg.type === "result" && msg.subtype === "success") {
    const output = msg.structured_output; // Guaranteed to match schema
  }
}

options: {
  agents: {
    "code-reviewer": {
      description: "Review code for bugs and style issues",
      prompt: "You are a code reviewer. Check for bugs, security issues, and style.",
      tools: ["Read", "Grep", "Glob"],
      model: "sonnet",
      maxTurns: 15,
    },
    "test-runner": {
      description: "Run test suites and report results",
      prompt: "Run all tests. Report failures clearly with file:line references.",
      tools: ["Bash", "Read"],
      model: "haiku",
      maxTurns: 10,
    },
    "architect": {
      description: "Design system architecture for complex features",
      prompt: "You design software architecture. Consider scalability and maintainability.",
      model: "opus",
      skills: ["system-design-patterns"],
    }
  }
}

import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const server = createSdkMcpServer({
  name: "my-tools",
  version: "1.0.0",
  tools: [
    tool(
      "search_tickets",
      "Search support tickets by keyword",
      {
        query: z.string().describe("Search keyword"),
        status: z.enum(["open", "closed", "all"]).describe("Filter by status"),
      },
      async (args) => {
        const results = await db.searchTickets(args.query, args.status);
        return { content: [{ type: "text", text: JSON.stringify(results) }] };
      },
      { annotations: { readOnly: true } }  // MCP tool annotations
    )
  ]
});

// Use in query
query({ prompt: "...", options: { mcpServers: { "my-tools": server } } });

mcpServers: {
  // Stdio
  "fs": { command: "npx", args: ["@modelcontextprotocol/server-filesystem"] },
  // HTTP (MUST specify type)
  "api": { type: "http", url: "https://api.example.com/mcp", headers: { Authorization: "Bearer ..." } },
  // SSE
  "stream": { type: "sse", url: "https://stream.example.com/mcp" },
}

hooks: {
  PreToolUse: [{ matcher: "Bash", hooks: [async (input) => {
    const command = (input.tool_input as { command?: string }).command ?? "";
    if (command.includes("rm -rf")) {
      return { decision: "block", reason: "Destructive command blocked" };
    }
    return { decision: "approve" };
  }] }],

  PostToolUse: [{ hooks: [async (input) => {
    await auditLog(input.tool_name, input.tool_input, input.tool_response);
    return {};
  }] }],

  SessionStart: [{ hooks: [async (input) => {
    return { systemMessage: "Additional context for this session" };
  }] }],

  Stop: [{ hooks: [async (input) => {
    await cleanup();
    return {};
  }] }],
}

// Permission modes: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'dontAsk' | 'auto'

// Custom permission callback
canUseTool: async (toolName, input, options) => {
  // options: { signal, suggestions?, blockedPath?, decisionReason?, toolUseID, agentID? }

  if (["Read", "Grep", "Glob"].includes(toolName))
    return { behavior: "allow" };

  if (toolName === "Bash" && /rm\s+-rf|dd\s+if=/.test(input.command))
    return { behavior: "deny", message: "Destructive command blocked" };

  return { behavior: "allow", updatedInput: input };
  // Can also return updatedPermissions for persistent rule changes
}

// Create session
const session = unstable_v2_createSession({
  model: "claude-sonnet-4-6",
  permissionMode: "acceptEdits",
  allowedTools: ["Read", "Write", "Edit", "Bash"],
});

// Send message and stream response
await session.send("Build a REST API for user management");
for await (const msg of session.stream()) {
  console.log(msg);
}

// Continue conversation
await session.send("Now add authentication");
for await (const msg of session.stream()) { ... }

// Cleanup (supports Symbol.asyncDispose)
session.close();

// Resume later
const resumed = unstable_v2_resumeSession(session.sessionId, { ... });

// WRONG - cryptic "process exited with code 1"
mcpServers: { "api": { url: "https://..." } }
// CORRECT
mcpServers: { "api": { type: "http", url: "https://..." } }

// Sanitize external data in MCP handlers
const sanitized = content.replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");

// WRONG - security risk
permissionMode: "bypassPermissions"
// CORRECT - use sandbox + specific permissions
permissionMode: "default",
sandbox: { enabled: true, autoAllowBashIfSandboxed: true },
canUseTool: async (tool, input) => { /* fine-grained logic */ }

// ALWAYS capture for resume/fork
for await (const msg of q) {
  if (msg.type === "system" && msg.subtype === "init") {
    sessionId = msg.session_id;  // Save this!
  }
}

// ALWAYS set limits in production
options: { maxTurns: 30, maxBudgetUsd: 10.0 }

// sandbox.failIfUnavailable defaults to true when enabled: true (v0.2.91+)
// If the sandbox binary is missing, the query will THROW instead of running unsandboxed
// WRONG for environments where sandbox may not be installed
sandbox: { enabled: true }
// CORRECT for graceful degradation
sandbox: { enabled: true, failIfUnavailable: false }
// CORRECT for explicit hard requirement
sandbox: { enabled: true, failIfUnavailable: true }

// Subagents don't auto-stop when parent stops
// Use Stop hook for cleanup
hooks: { Stop: [{ hooks: [async () => { await cleanupSubagents(); }] }] }

Concept	Description	Key API
`query()`	Primary V1 API - returns async generator	`query({ prompt, options })`
V2 Session	Multi-turn persistent session (unstable)	`unstable_v2_createSession()`
Agents	Subagent definitions for task delegation	`options.agents`

Concept	Description	Key API
`query()`	Primary V1 API - returns async generator	`query({ prompt, options })`
V2 Session	Multi-turn persistent session (unstable)	`unstable_v2_createSession()`
Agents	Subagent definitions for task delegation	`options.agents`

claude-agent-sdk-best-practice

설치 방법

소스 파일 검토