API de sessão TypeScript SDK V2 (removida)

A API de sessão V2 não é mais suportada. TypeScript Agent SDK 0.3.142 remove unstable_v2_createSession, unstable_v2_resumeSession, unstable_v2_prompt e os tipos SDKSession e SDKSessionOptions.Para migrar, use a API query() e as opções de sessão que ela aceita. Passe um AsyncIterable<SDKUserMessage> para conversas multi-turno, ou options.resume para continuar uma sessão salva. Esta página é mantida como referência se você mantém código no Agent SDK 0.2.x ou anterior.

V2 era uma API de sessão experimental que removeu a necessidade de geradores assíncronos e coordenação de yield. Em vez de gerenciar o estado do gerador entre turnos, cada turno era um ciclo send()/stream() separado. A superfície da API se reduzia a criar uma sessão, enviar uma mensagem e transmitir a resposta:

createSession() / resumeSession(): Iniciar ou continuar uma conversa
session.send(): Enviar uma mensagem
session.stream(): Obter a resposta

Instalação

Agent SDK 0.2.x é a última versão que inclui a interface V2. A versão do pacote saltou de 0.2.x diretamente para 0.3.142, portanto a versão de remoção acima e o pin de instalação abaixo descrevem o mesmo limite. Para instalar a última versão compatível com V2, fixe a versão principal e secundária:

npm install @anthropic-ai/claude-agent-sdk@0.2

O SDK agrupa um binário nativo do Claude Code para sua plataforma como uma dependência opcional, portanto a maioria das instalações não precisa de uma instalação separada do Claude Code. Consulte a nota de instalação do quickstart para as instalações que precisam de uma.

Início rápido

Prompt único

Para consultas simples de turno único onde você não precisa manter uma sessão, use unstable_v2_prompt(). Este exemplo envia uma pergunta de matemática e registra a resposta:

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

const result = await unstable_v2_prompt("What is 2 + 2?", {
  model: "claude-opus-4-7"
});
if (result.subtype === "success") {
  console.log(result.result);
}

Sessão básica

Para interações além de um único prompt, crie uma sessão. V2 separa envio e streaming em etapas distintas:

send() envia sua mensagem
stream() transmite a resposta

Esta separação explícita torna mais fácil adicionar lógica entre turnos (como processar respostas antes de enviar acompanhamentos). O exemplo abaixo cria uma sessão, envia “Hello!” para Claude e imprime a resposta de texto. Ele usa await using (TypeScript 5.2+) para fechar automaticamente a sessão quando o bloco sai. Você também pode chamar session.close() manualmente.

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

await using session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});

await session.send("Hello!");
for await (const msg of session.stream()) {
  // Filter for assistant messages to get human-readable output
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((block) => block.type === "text")
      .map((block) => block.text)
      .join("");
    console.log(text);
  }
}

Conversa multi-turno

As sessões persistem contexto em múltiplas trocas. Para continuar uma conversa, chame send() novamente na mesma sessão. Claude se lembra dos turnos anteriores. Este exemplo faz uma pergunta de matemática e depois faz um acompanhamento que referencia a resposta anterior:

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

await using session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});

// Turn 1
await session.send("What is 5 + 3?");
for await (const msg of session.stream()) {
  // Filter for assistant messages to get human-readable output
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((block) => block.type === "text")
      .map((block) => block.text)
      .join("");
    console.log(text);
  }
}

// Turn 2
await session.send("Multiply that by 2");
for await (const msg of session.stream()) {
  if (msg.type === "assistant") {
    const text = msg.message.content
      .filter((block) => block.type === "text")
      .map((block) => block.text)
      .join("");
    console.log(text);
  }
}

Retomada de sessão

Se você tiver um ID de sessão de uma interação anterior, poderá retomá-lo mais tarde. Isso é útil para fluxos de trabalho de longa duração ou quando você precisa persistir conversas entre reinicializações de aplicativo. Este exemplo cria uma sessão, armazena seu ID, a fecha e depois retoma a conversa:

import {
  unstable_v2_createSession,
  unstable_v2_resumeSession,
  type SDKMessage
} from "@anthropic-ai/claude-agent-sdk";

// Helper to extract text from assistant messages
function getAssistantText(msg: SDKMessage): string | null {
  if (msg.type !== "assistant") return null;
  return msg.message.content
    .filter((block) => block.type === "text")
    .map((block) => block.text)
    .join("");
}

// Create initial session and have a conversation
const session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});

await session.send("Remember this number: 42");

// Get the session ID from any received message
let sessionId: string | undefined;
for await (const msg of session.stream()) {
  sessionId = msg.session_id;
  const text = getAssistantText(msg);
  if (text) console.log("Initial response:", text);
}

console.log("Session ID:", sessionId);
session.close();

// Later: resume the session using the stored ID
await using resumedSession = unstable_v2_resumeSession(sessionId!, {
  model: "claude-opus-4-7"
});

await resumedSession.send("What number did I ask you to remember?");
for await (const msg of resumedSession.stream()) {
  const text = getAssistantText(msg);
  if (text) console.log("Resumed response:", text);
}

Limpeza

As sessões podem ser fechadas manualmente ou automaticamente usando await using, um recurso do TypeScript 5.2+ para limpeza automática de recursos. Se você estiver usando uma versão mais antiga do TypeScript ou encontrar problemas de compatibilidade, use limpeza manual em seu lugar. Os exemplos abaixo mostram apenas o padrão de limpeza e não enviam nenhuma mensagem, portanto, executá-los não produz nenhuma saída. Limpeza automática (TypeScript 5.2+):

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

await using session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});
// Session closes automatically when the block exits

Limpeza manual:

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

const session = unstable_v2_createSession({
  model: "claude-opus-4-7"
});
// ... use the session ...
session.close();

Referência da API

`unstable_v2_createSession()`

Cria uma nova sessão para conversas multi-turno.

function unstable_v2_createSession(options: {
  model: string;
  // Additional options supported
}): SDKSession;

`unstable_v2_resumeSession()`

Retoma uma sessão existente por ID.

function unstable_v2_resumeSession(
  sessionId: string,
  options: {
    model: string;
    // Additional options supported
  }
): SDKSession;

`unstable_v2_prompt()`

Função de conveniência única para consultas de turno único.

function unstable_v2_prompt(
  prompt: string,
  options: {
    model: string;
    // Additional options supported
  }
): Promise<SDKResultMessage>;

Interface SDKSession

interface SDKSession {
  readonly sessionId: string;
  send(message: string | SDKUserMessage): Promise<void>;
  stream(): AsyncGenerator<SDKMessage, void>;
  close(): void;
}

Disponibilidade de recursos

A API de sessão V2 não suporta todos os recursos V1. Os seguintes requerem o SDK V1:

Bifurcação de sessão (opção forkSession)
Alguns padrões avançados de entrada de streaming

Veja também

Referência do SDK TypeScript (V1) - Documentação completa do SDK V1
Visão geral do SDK - Conceitos gerais do SDK
Exemplos V2 no GitHub - Exemplos de código funcionando

Agent SDK

Criar agentes

Conceitos fundamentais

Entrada e saída

Estender com ferramentas

Personalizar comportamento

Controle e observabilidade

Implantação

Referências do SDK

API de sessão TypeScript SDK V2 (removida)

Instalação

Início rápido

Prompt único

Sessão básica

Conversa multi-turno

Retomada de sessão

Limpeza

Referência da API

`unstable_v2_createSession()`

`unstable_v2_resumeSession()`

`unstable_v2_prompt()`

Interface SDKSession

Disponibilidade de recursos

Veja também

​Instalação

​Início rápido

​Prompt único

​Sessão básica

​Conversa multi-turno

​Retomada de sessão

​Limpeza

​Referência da API

​unstable_v2_createSession()

​unstable_v2_resumeSession()

​unstable_v2_prompt()

​Interface SDKSession

​Disponibilidade de recursos

​Veja também

Instalação

Início rápido

Prompt único

Sessão básica

Conversa multi-turno

Retomada de sessão

Limpeza

Referência da API

`unstable_v2_createSession()`

`unstable_v2_resumeSession()`

`unstable_v2_prompt()`

Interface SDKSession

Disponibilidade de recursos

Veja também