​
Предварительные требования

  • Node.js 18+

​
Установка

Установите @anthropic-ai/claude-code из NPM:

npm install -g @anthropic-ai/claude-code

Чтобы просмотреть исходный код TypeScript SDK, посетите страницу @anthropic-ai/claude-code на NPM.

​
Базовое использование

Основной интерфейс через TypeScript SDK - это функция query, которая возвращает асинхронный итератор, передающий сообщения по мере их поступления:

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

for await (const message of query({
  prompt: "Analyze system performance",
  abortController: new AbortController(),
  options: {
    maxTurns: 5,
    systemPrompt: "You are a performance engineer",
    allowedTools: ["Bash", "Read", "WebSearch"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

​
Параметры конфигурации

АргументТипОписаниеПо умолчанию
abortControllerAbortControllerКонтроллер прерывания для отмены операцийnew AbortController()
additionalDirectoriesstring[]Дополнительные директории для включения в сессиюundefined
allowedToolsstring[]Список инструментов, которые Claude может использоватьВсе инструменты включены по умолчанию
appendSystemPromptstringТекст для добавления к системному промпту по умолчаниюundefined
canUseToolCanUseToolПользовательская функция разрешений для использования инструментовundefined
continuebooleanПродолжить самую последнюю сессиюfalse
customSystemPromptstringПолностью заменить системный промпт по умолчаниюundefined
cwdstringТекущий рабочий каталогprocess.cwd()
disallowedToolsstring[]Список инструментов, которые Claude не может использоватьundefined
envDict<string>Переменные окружения для установкиundefined
executable'bun' | 'deno' | 'node'Какую среду выполнения JavaScript использоватьnode при работе с Node.js, bun при работе с Bun
executableArgsstring[]Аргументы для передачи исполняемому файлу[]
fallbackModelstringМодель для использования, если основная модель не работаетundefined
maxThinkingTokensnumberМаксимальное количество токенов для процесса размышления Claudeundefined
maxTurnsnumberМаксимальное количество ходов разговораundefined
mcpServersRecord<string, McpServerConfig>Конфигурации MCP-серверовundefined
modelstringМодель Claude для использованияИспользует значение по умолчанию из конфигурации CLI
pathToClaudeCodeExecutablestringПуть к исполняемому файлу Claude CodeИсполняемый файл, поставляемый с @anthropic-ai/claude-code
permissionModePermissionModeРежим разрешений для сессии"default" (варианты: "default", "acceptEdits", "bypassPermissions", "plan")
permissionPromptToolNamestringИмя MCP-инструмента для запросов разрешенийundefined
resumestringID сессии для возобновленияundefined
stderr(data: string) => voidОбратный вызов для вывода stderrundefined
strictMcpConfigbooleanПринудительная строгая валидация конфигурации MCPundefined

​
Многоходовые разговоры

Для многоходовых разговоров у вас есть два варианта.

Вы можете генерировать ответы и возобновлять их, или можете использовать режим потокового ввода, который принимает async/generator для массива сообщений. На данный момент режим потокового ввода - единственный способ прикреплять изображения через сообщения.

​
Возобновление с управлением сессиями

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

// Продолжить самый последний разговор
for await (const message of query({
  prompt: "Now refactor this for better performance",
  options: { continue: true }
})) {
  if (message.type === "result") console.log(message.result);
}

// Возобновить конкретную сессию
for await (const message of query({
  prompt: "Update the tests",
  options: {
    resume: "550e8400-e29b-41d4-a716-446655440000",
    maxTurns: 3
  }
})) {
  if (message.type === "result") console.log(message.result);
}

​
Режим потокового ввода

Режим потокового ввода позволяет предоставлять сообщения как асинхронный итерируемый объект вместо одной строки. Это обеспечивает многоходовые разговоры, прикрепление изображений и динамическую генерацию сообщений:

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

// Создать асинхронный генератор для потоковых сообщений
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Start analyzing this codebase"
    }
  };
  
  // Ждать некоторого условия или пользовательского ввода
  await new Promise(resolve => setTimeout(resolve, 1000));
  
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Now focus on the authentication module"
    }
  };
}

// Использовать потоковый ввод
for await (const message of query({
  prompt: generateMessages(),
  options: {
    maxTurns: 5,
    allowedTools: ["Read", "Grep", "Bash"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

​
Потоковый ввод с изображениями

Режим потокового ввода - единственный способ прикреплять изображения через сообщения:

import { query } from "@anthropic-ai/claude-code";
import { readFileSync } from "fs";

async function* messagesWithImage() {
  // Отправить изображение с текстом
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: [
        {
          type: "text",
          text: "Analyze this screenshot and suggest improvements"
        },
        {
          type: "image",
          source: {
            type: "base64",
            media_type: "image/png",
            data: readFileSync("screenshot.png", "base64")
          }
        }
      ]
    }
  };
}

for await (const message of query({
  prompt: messagesWithImage()
})) {
  if (message.type === "result") console.log(message.result);
}

​
Пользовательские системные промпты

Системные промпты определяют роль, экспертизу и поведение вашего агента:

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

// Агент реагирования на инциденты SRE
for await (const message of query({
  prompt: "API is down, investigate",
  options: {
    systemPrompt: "You are an SRE expert. Diagnose issues systematically and provide actionable solutions.",
    maxTurns: 3
  }
})) {
  if (message.type === "result") console.log(message.result);
}

// Добавить к системному промпту по умолчанию
for await (const message of query({
  prompt: "Refactor this function",
  options: {
    appendSystemPrompt: "Always include comprehensive error handling and unit tests.",
    maxTurns: 2
  }
})) {
  if (message.type === "result") console.log(message.result);
}

​
Пользовательские инструменты через MCP

Протокол контекста модели (MCP) позволяет предоставить вашим агентам пользовательские инструменты и возможности:

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

// SRE-агент с инструментами мониторинга
for await (const message of query({
  prompt: "Investigate the payment service outage",
  options: {
    mcpConfig: "sre-tools.json",
    allowedTools: ["mcp__datadog", "mcp__pagerduty", "mcp__kubernetes"],
    systemPrompt: "You are an SRE. Use monitoring data to diagnose issues.",
    maxTurns: 4
  }
})) {
  if (message.type === "result") console.log(message.result);
}

​
Пользовательские инструменты с использованием MCP

Вы можете реализовать пользовательские инструменты с помощью MCP, например, вот как можно создать пользовательский инструмент обработки разрешений.

const server = new McpServer({
  name: "Test permission prompt MCP Server",
  version: "0.0.1",
});

server.tool(
  "approval_prompt",
  'Simulate a permission check - approve if the input contains "allow", otherwise deny',
  {
    tool_name: z.string().describe("The name of the tool requesting permission"),
    input: z.object({}).passthrough().describe("The input for the tool"),
    tool_use_id: z.string().optional().describe("The unique tool use request ID"),
  },
  async ({ tool_name, input }) => {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            JSON.stringify(input).includes("allow")
              ? {
                  behavior: "allow",
                  updatedInput: input,
                }
              : {
                  behavior: "deny",
                  message: "Permission denied by test approval_prompt tool",
                }
          ),
        },
      ],
    };
  }
);

// Использовать в SDK
import { query } from "@anthropic-ai/claude-code";

for await (const message of query({
  prompt: "Analyze the codebase",
  options: {
    permissionPromptTool: "mcp__test-server__approval_prompt",
    mcpConfig: "my-config.json",
    allowedTools: ["Read", "Grep"]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

​
Форматы вывода

​
Текстовый вывод (по умолчанию)

// Текстовый вывод по умолчанию
for await (const message of query({
  prompt: "Explain file src/components/Header.tsx"
})) {
  if (message.type === "result") {
    console.log(message.result);
    // Вывод: This is a React component showing...
  }
}

​
JSON вывод

// Собрать все сообщения для доступа в стиле JSON
const messages = [];
for await (const message of query({
  prompt: "How does the data layer work?"
})) {
  messages.push(message);
}

// Получить доступ к результирующему сообщению с метаданными
const result = messages.find(m => m.type === "result");
console.log({
  result: result.result,
  cost: result.total_cost_usd,
  duration: result.duration_ms
});

​
Форматы ввода

// Прямой промпт
for await (const message of query({
  prompt: "Explain this code"
})) {
  if (message.type === "result") console.log(message.result);
}

// Из переменной
const userInput = "Explain this code";
for await (const message of query({ prompt: userInput })) {
  if (message.type === "result") console.log(message.result);
}

​
Примеры интеграции агентов

​
Агент реагирования на инциденты SRE

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

// Автоматизированный агент реагирования на инциденты
async function investigateIncident(
  incidentDescription: string,
  severity = "medium"
) {
  const messages = [];

  for await (const message of query({
    prompt: `Incident: ${incidentDescription} (Severity: ${severity})`,
    options: {
      systemPrompt: "You are an SRE expert. Diagnose the issue, assess impact, and provide immediate action items.",
      maxTurns: 6,
      allowedTools: ["Bash", "Read", "WebSearch", "mcp__datadog"],
      mcpConfig: "monitoring-tools.json"
    }
  })) {
    messages.push(message);
  }

  return messages.find(m => m.type === "result");
}

// Использование
const result = await investigateIncident("Payment API returning 500 errors", "high");
console.log(result.result);

​
Автоматизированная проверка безопасности

import { query } from "@anthropic-ai/claude-code";
import { execSync } from "child_process";

async function auditPR(prNumber: number) {
  // Получить diff PR
  const prDiff = execSync(`gh pr diff ${prNumber}`, { encoding: 'utf8' });

  const messages = [];
  for await (const message of query({
    prompt: prDiff,
    options: {
      systemPrompt: "You are a security engineer. Review this PR for vulnerabilities, insecure patterns, and compliance issues.",
      maxTurns: 3,
      allowedTools: ["Read", "Grep", "WebSearch"]
    }
  })) {
    messages.push(message);
  }

  return messages.find(m => m.type === "result");
}

// Использование
const report = await auditPR(123);
console.log(JSON.stringify(report, null, 2));

​
Многоходовой юридический помощник

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

async function legalReview() {
  // Начать сессию юридической проверки
  let sessionId: string;

  for await (const message of query({
    prompt: "Start legal review session",
    options: { maxTurns: 1 }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }
  }

  // Многоэтапная проверка с использованием той же сессии
  const steps = [
    "Review contract.pdf for liability clauses",
    "Check compliance with GDPR requirements",
    "Generate executive summary of risks"
  ];

  for (const step of steps) {
    for await (const message of query({
      prompt: step,
      options: { resume: sessionId, maxTurns: 2 }
    })) {
      if (message.type === "result") {
        console.log(`Step: ${step}`);
        console.log(message.result);
      }
    }
  }
}

​
Схема сообщений

Сообщения, возвращаемые из JSON API, строго типизированы согласно следующей схеме:

type SDKMessage =
  // Сообщение помощника
  | {
      type: "assistant";
      uuid: string;
      session_id: string;
      message: Message; // из Anthropic SDK
      parent_tool_use_id: string | null;
    }

  // Пользовательское сообщение (ввод)
  | {
      type: "user";
      uuid?: string;
      session_id: string;
      message: MessageParam; // из Anthropic SDK
      parent_tool_use_id: string | null;
    }

  // Пользовательское сообщение (вывод/воспроизведение с обязательным UUID)
  | {
      type: "user";
      uuid: string;
      session_id: string;
      message: MessageParam; // из Anthropic SDK
      parent_tool_use_id: string | null;
    }

  // Выдается как последнее сообщение при успехе
  | {
      type: "result";
      subtype: "success";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      result: string;
      total_cost_usd: number;
      usage: Usage;
      permission_denials: SDKPermissionDenial[];
    }

  // Выдается как последнее сообщение при ошибке или максимальном количестве ходов
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      total_cost_usd: number;
      usage: Usage;
      permission_denials: SDKPermissionDenial[];
    }

  // Выдается как первое сообщение в начале разговора
  | {
      type: "system";
      subtype: "init";
      uuid: UUID;
      session_id: string;
      apiKeySource: "user" | "project" | "org" | "temporary";
      cwd: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
      slash_commands: string[];
      output_style: string;
    };

  type SDKPermissionDenial = {
    tool_name: string;
    tool_use_id: string;
    tool_input: Record<string, unknown>;
  }

Дополнительные поддерживающие типы:

Типы Message, MessageParam и Usage доступны в Anthropic TypeScript SDK.

​
Связанные ресурсы