TypeScript

Pré-requisitos

Node.js 18+

Instalação

Instale @anthropic-ai/claude-code do NPM:

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

Para visualizar o código fonte do TypeScript SDK, visite a página @anthropic-ai/claude-code no NPM.

Uso básico

A interface principal via TypeScript SDK é a função query, que retorna um iterador assíncrono que transmite mensagens conforme chegam:

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);
  }
}

Opções de configuração

Argumento	Tipo	Descrição	Padrão
`abortController`	`AbortController`	Controlador de aborto para cancelar operações	`new AbortController()`
`additionalDirectories`	`string[]`	Diretórios adicionais para incluir na sessão	`undefined`
`allowedTools`	`string[]`	Lista de ferramentas que Claude tem permissão para usar	Todas as ferramentas habilitadas por padrão
`appendSystemPrompt`	`string`	Texto para anexar ao prompt do sistema padrão	`undefined`
`canUseTool`	`CanUseTool`	Função de permissão personalizada para uso de ferramentas	`undefined`
`continue`	`boolean`	Continuar a sessão mais recente	`false`
`customSystemPrompt`	`string`	Substituir completamente o prompt do sistema padrão	`undefined`
`cwd`	`string`	Diretório de trabalho atual	`process.cwd()`
`disallowedTools`	`string[]`	Lista de ferramentas que Claude não tem permissão para usar	`undefined`
`env`	`Dict<string>`	Variáveis de ambiente para definir	`undefined`
`executable`	`'bun' \| 'deno' \| 'node'`	Qual runtime JavaScript usar	`node` quando executando com Node.js, `bun` quando executando com Bun
`executableArgs`	`string[]`	Argumentos para passar ao executável	`[]`
`fallbackModel`	`string`	Modelo para usar se o modelo principal falhar	`undefined`
`maxThinkingTokens`	`number`	Tokens máximos para o processo de pensamento do Claude	`undefined`
`maxTurns`	`number`	Número máximo de turnos de conversa	`undefined`
`mcpServers`	`Record<string, McpServerConfig>`	Configurações do servidor MCP	`undefined`
`model`	`string`	Modelo Claude para usar	Usa padrão da configuração CLI
`pathToClaudeCodeExecutable`	`string`	Caminho para o executável Claude Code	Executável que vem com `@anthropic-ai/claude-code`
`permissionMode`	`PermissionMode`	Modo de permissão para a sessão	`"default"` (opções: `"default"`, `"acceptEdits"`, `"bypassPermissions"`, `"plan"`)
`permissionPromptToolName`	`string`	Nome da ferramenta MCP para prompts de permissão	`undefined`
`resume`	`string`	ID da sessão para retomar	`undefined`
`stderr`	`(data: string) => void`	Callback para saída stderr	`undefined`
`strictMcpConfig`	`boolean`	Aplicar validação rigorosa de configuração MCP	`undefined`

Conversas multi-turno

Para conversas multi-turno, você tem duas opções.

Você pode gerar respostas e retomá-las, ou pode usar o modo de entrada de streaming que aceita um async/generator para um array de mensagens. Por enquanto, o modo de entrada de streaming é a única maneira de anexar imagens via mensagens.

Retomar com gerenciamento de sessão

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

// Continuar conversa mais recente
for await (const message of query({
  prompt: "Now refactor this for better performance",
  options: { continue: true }
})) {
  if (message.type === "result") console.log(message.result);
}

// Retomar sessão específica
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);
}

Modo de entrada de streaming

O modo de entrada de streaming permite que você forneça mensagens como um iterável assíncrono em vez de uma única string. Isso permite conversas multi-turno, anexos de imagem e geração dinâmica de mensagens:

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

// Criar um gerador assíncrono para streaming de mensagens
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Start analyzing this codebase"
    }
  };
  
  // Aguardar alguma condição ou entrada do usuário
  await new Promise(resolve => setTimeout(resolve, 1000));
  
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "Now focus on the authentication module"
    }
  };
}

// Usar entrada de streaming
for await (const message of query({
  prompt: generateMessages(),
  options: {
    maxTurns: 5,
    allowedTools: ["Read", "Grep", "Bash"]
  }
})) {
  if (message.type === "result") {
    console.log(message.result);
  }
}

Entrada de streaming com imagens

O modo de entrada de streaming é a única maneira de anexar imagens via mensagens:

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

async function* messagesWithImage() {
  // Enviar uma imagem com texto
  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);
}

Prompts de sistema personalizados

Prompts de sistema definem o papel, expertise e comportamento do seu agente:

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

// Agente de resposta a incidentes 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);
}

// Anexar ao prompt de sistema padrão
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);
}

Ferramentas personalizadas via MCP

O Model Context Protocol (MCP) permite que você dê aos seus agentes ferramentas e capacidades personalizadas:

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

// Agente SRE com ferramentas de monitoramento
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);
}

Ferramentas personalizadas usando MCPs

Você pode implementar ferramentas personalizadas usando MCPs, por exemplo, aqui está como você pode criar uma ferramenta de tratamento de permissão personalizada.

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",
                }
          ),
        },
      ],
    };
  }
);

// Usar no 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);
}

Formatos de saída

Saída de texto (padrão)

// Saída de texto padrão
for await (const message of query({
  prompt: "Explain file src/components/Header.tsx"
})) {
  if (message.type === "result") {
    console.log(message.result);
    // Saída: This is a React component showing...
  }
}

Saída JSON

// Coletar todas as mensagens para acesso tipo JSON
const messages = [];
for await (const message of query({
  prompt: "How does the data layer work?"
})) {
  messages.push(message);
}

// Acessar mensagem de resultado com metadados
const result = messages.find(m => m.type === "result");
console.log({
  result: result.result,
  cost: result.total_cost_usd,
  duration: result.duration_ms
});

Formatos de entrada

// Prompt direto
for await (const message of query({
  prompt: "Explain this code"
})) {
  if (message.type === "result") console.log(message.result);
}

// De variável
const userInput = "Explain this code";
for await (const message of query({ prompt: userInput })) {
  if (message.type === "result") console.log(message.result);
}

Exemplos de integração de agentes

Agente de resposta a incidentes SRE

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

// Agente de resposta a incidentes automatizado
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");
}

// Uso
const result = await investigateIncident("Payment API returning 500 errors", "high");
console.log(result.result);

Revisão de segurança automatizada

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

async function auditPR(prNumber: number) {
  // Obter diff do 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");
}

// Uso
const report = await auditPR(123);
console.log(JSON.stringify(report, null, 2));

Assistente jurídico multi-turno

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

async function legalReview() {
  // Iniciar sessão de revisão jurídica
  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;
    }
  }

  // Revisão multi-etapas usando a mesma sessão
  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);
      }
    }
  }
}

Schema de mensagens

Mensagens retornadas da API JSON são estritamente tipadas de acordo com o seguinte schema:

type SDKMessage =
  // Uma mensagem do assistente
  | {
      type: "assistant";
      uuid: string;
      session_id: string;
      message: Message; // do Anthropic SDK
      parent_tool_use_id: string | null;
    }

  // Uma mensagem do usuário (entrada)
  | {
      type: "user";
      uuid?: string;
      session_id: string;
      message: MessageParam; // do Anthropic SDK
      parent_tool_use_id: string | null;
    }

  // Uma mensagem do usuário (saída/replay com UUID obrigatório)
  | {
      type: "user";
      uuid: string;
      session_id: string;
      message: MessageParam; // do Anthropic SDK
      parent_tool_use_id: string | null;
    }

  // Emitida como a última mensagem em caso de sucesso
  | {
      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[];
    }

  // Emitida como a última mensagem em caso de erro ou turnos máximos
  | {
      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[];
    }

  // Emitida como a primeira mensagem no início de uma conversa
  | {
      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>;
  }

Tipos de suporte adicionais:

Os tipos Message, MessageParam e Usage estão disponíveis no TypeScript SDK da Anthropic.

Recursos relacionados

Uso e controles da CLI - Documentação completa da CLI
Integração com GitHub Actions - Automatize seu fluxo de trabalho do GitHub com Claude
Fluxos de trabalho comuns - Guias passo a passo para casos de uso comuns

Começando

Construir com Claude Code

Claude Code SDK

Implantação

Administração

Configuração

Referência

Recursos

Pré-requisitos

Instalação

Uso básico

Opções de configuração

Conversas multi-turno

Retomar com gerenciamento de sessão

Modo de entrada de streaming

Entrada de streaming com imagens

Prompts de sistema personalizados

Ferramentas personalizadas via MCP

Ferramentas personalizadas usando MCPs

Formatos de saída

Saída de texto (padrão)

Saída JSON

Formatos de entrada

Exemplos de integração de agentes

Agente de resposta a incidentes SRE

Revisão de segurança automatizada

Assistente jurídico multi-turno

Schema de mensagens

Recursos relacionados

Começando

Construir com Claude Code

Claude Code SDK

Implantação

Administração

Configuração

Referência

Recursos

​Pré-requisitos

​Instalação

​Uso básico

​Opções de configuração

​Conversas multi-turno

​Retomar com gerenciamento de sessão

​Modo de entrada de streaming

​Entrada de streaming com imagens

​Prompts de sistema personalizados

​Ferramentas personalizadas via MCP

​Ferramentas personalizadas usando MCPs

​Formatos de saída

​Saída de texto (padrão)

​Saída JSON

​Formatos de entrada

​Exemplos de integração de agentes

​Agente de resposta a incidentes SRE

​Revisão de segurança automatizada

​Assistente jurídico multi-turno

​Schema de mensagens

​Recursos relacionados

Pré-requisitos

Instalação

Uso básico

Opções de configuração

Conversas multi-turno

Retomar com gerenciamento de sessão

Modo de entrada de streaming

Entrada de streaming com imagens

Prompts de sistema personalizados

Ferramentas personalizadas via MCP

Ferramentas personalizadas usando MCPs

Formatos de saída

Saída de texto (padrão)

Saída JSON

Formatos de entrada

Exemplos de integração de agentes

Agente de resposta a incidentes SRE

Revisão de segurança automatizada

Assistente jurídico multi-turno

Schema de mensagens

Recursos relacionados