Claude Code SDK - Anthropic

Por que usar o Claude Code SDK?

O Claude Code SDK fornece todos os blocos de construção necessários para criar agentes prontos para produção:

Integração otimizada com Claude: Cache automático de prompts e otimizações de desempenho
Ecossistema rico de ferramentas: Operações de arquivo, execução de código, busca na web e extensibilidade MCP
Permissões avançadas: Controle refinado sobre as capacidades do agente
Essenciais para produção: Tratamento de erros integrado, gerenciamento de sessão e monitoramento

O que você pode construir com o SDK?

Aqui estão alguns tipos de agentes de exemplo que você pode criar: Agentes de codificação:

Agentes SRE que diagnosticam e corrigem problemas de produção
Bots de revisão de segurança que auditam código em busca de vulnerabilidades
Assistentes de engenharia de plantão que fazem triagem de incidentes
Agentes de revisão de código que aplicam estilo e melhores práticas

Agentes de negócios:

Assistentes jurídicos que revisam contratos e conformidade
Consultores financeiros que analisam relatórios e previsões
Agentes de suporte ao cliente que resolvem problemas técnicos
Assistentes de criação de conteúdo para equipes de marketing

O SDK está atualmente disponível em TypeScript e Python, com uma interface de linha de comando (CLI) para prototipagem rápida.

Início rápido

Tenha seu primeiro agente funcionando em menos de 5 minutos:

Instalar o SDK

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

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

Definir sua chave de API

Obtenha sua chave de API do Console Anthropic e defina a variável de ambiente ANTHROPIC_API_KEY:

export ANTHROPIC_API_KEY="sua-chave-de-api-aqui"

Criar seu primeiro agente

Crie um destes agentes de exemplo:

# Criar um assistente jurídico simples
claude -p "Revise esta cláusula de contrato em busca de possíveis problemas: 'A parte concorda com responsabilidade ilimitada...'" \
  --append-system-prompt "Você é um assistente jurídico. Identifique riscos e sugira melhorias."

Executar o agente

Copie e cole o comando acima diretamente no seu terminal.

Cada exemplo acima cria um agente funcional que irá:

Analisar o prompt usando as capacidades de raciocínio do Claude
Planejar uma abordagem de múltiplas etapas para resolver o problema
Executar ações usando ferramentas como operações de arquivo, comandos bash e busca na web
Fornecer recomendações acionáveis baseadas na análise

Uso principal

Visão geral

O Claude Code SDK permite que você faça interface com o Claude Code em modo não interativo a partir de suas aplicações.

Pré-requisitos

Node.js 18+
@anthropic-ai/claude-code do NPM

Uso básicoA interface principal de linha de comando para o Claude Code é o comando claude. Use a flag --print (ou -p) para executar em modo não interativo e imprimir o resultado final:

claude -p "Analisar desempenho do sistema" \
  --append-system-prompt "Você é um engenheiro de desempenho" \
  --allowedTools "Bash,Read,WebSearch" \
  --permission-mode acceptEdits \
  --cwd /caminho/para/projeto

ConfiguraçãoO SDK aproveita todas as opções CLI disponíveis no Claude Code. Aqui estão as principais para uso do SDK:

Flag	Descrição	Exemplo
`--print`, `-p`	Executar em modo não interativo	`claude -p "consulta"`
`--output-format`	Especificar formato de saída (`text`, `json`, `stream-json`)	`claude -p --output-format json`
`--resume`, `-r`	Retomar uma conversa por ID de sessão	`claude --resume abc123`
`--continue`, `-c`	Continuar a conversa mais recente	`claude --continue`
`--verbose`	Habilitar log detalhado	`claude --verbose`
`--append-system-prompt`	Anexar ao prompt do sistema (apenas com `--print`)	`claude --append-system-prompt "Instrução personalizada"`
`--allowedTools`	Lista separada por espaços de ferramentas permitidas, ou string de lista separada por vírgulas de ferramentas permitidas	`claude --allowedTools mcp__slack mcp__filesystem` `claude --allowedTools "Bash(npm install),mcp__filesystem"`
`--disallowedTools`	Lista separada por espaços de ferramentas negadas, ou string de lista separada por vírgulas de ferramentas negadas	`claude --disallowedTools mcp__splunk mcp__github` `claude --disallowedTools "Bash(git commit),mcp__github"`
`--mcp-config`	Carregar servidores MCP de um arquivo JSON	`claude --mcp-config servers.json`
`--permission-prompt-tool`	Ferramenta MCP para lidar com prompts de permissão (apenas com `--print`)	`claude --permission-prompt-tool mcp__auth__prompt`

Para uma lista completa de opções CLI e recursos, consulte a documentação de referência CLI.

Autenticação

Chave de API Anthropic

Para autenticação básica, recupere uma chave de API Anthropic do Console Anthropic e defina a variável de ambiente ANTHROPIC_API_KEY, conforme demonstrado no Início rápido.

Credenciais de API de terceiros

O SDK também suporta autenticação via provedores de API de terceiros:

Amazon Bedrock: Defina a variável de ambiente CLAUDE_CODE_USE_BEDROCK=1 e configure as credenciais AWS
Google Vertex AI: Defina a variável de ambiente CLAUDE_CODE_USE_VERTEX=1 e configure as credenciais Google Cloud

Para instruções detalhadas de configuração para provedores de terceiros, consulte a documentação do Amazon Bedrock e Google Vertex AI.

Conversas de múltiplas rodadas

Para conversas de múltiplas rodadas, você pode retomar conversas ou continuar da sessão mais recente:

# Continuar a conversa mais recente
claude --continue "Agora refatore isso para melhor desempenho"

# Retomar uma conversa específica por ID de sessão
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Atualize os testes"

# Retomar em modo não interativo
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Corrija todos os problemas de linting" --no-interactive

Usando Modo de Planejamento

O Modo de Planejamento permite que o Claude analise código sem fazer modificações, útil para revisões de código e planejamento de mudanças.

claude -p "Revise este código" --permission-mode plan

O Modo de Planejamento restringe edição, criação de arquivos e execução de comandos. Consulte modos de permissão para detalhes.

Prompts de sistema personalizados

Prompts de sistema definem o papel, expertise e comportamento do seu agente. É aqui que você especifica que tipo de agente está construindo:

# Agente de resposta a incidentes SRE
claude -p "API está fora do ar, investigue" \
  --append-system-prompt "Você é um especialista SRE. Diagnostique problemas sistematicamente e forneça soluções acionáveis."

# Agente de revisão de documentos jurídicos  
claude -p "Revise este contrato" \
  --append-system-prompt "Você é um advogado corporativo. Identifique riscos, sugira melhorias e garanta conformidade."

# Anexar ao prompt de sistema padrão
claude -p "Refatore esta função" \
  --append-system-prompt "Sempre inclua tratamento de erro abrangente e testes unitários."

Uso Avançado

Ferramentas personalizadas via MCP

O Model Context Protocol (MCP) permite que você dê aos seus agentes ferramentas e capacidades personalizadas. Isso é crucial para construir agentes especializados que precisam de integrações específicas de domínio. Configurações de ferramentas de agente de exemplo:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {"SLACK_TOKEN": "seu-token-slack"}
    },
    "jira": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-jira"],
      "env": {"JIRA_TOKEN": "seu-token-jira"}
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {"DB_CONNECTION_STRING": "sua-url-db"}
    }
  }
}

Exemplos de uso:

# Agente SRE com ferramentas de monitoramento
claude -p "Investigue a interrupção do serviço de pagamento" \
  --mcp-config sre-tools.json \
  --allowedTools "mcp__datadog,mcp__pagerduty,mcp__kubernetes" \
  --append-system-prompt "Você é um SRE. Use dados de monitoramento para diagnosticar problemas."

# Agente de suporte ao cliente com acesso CRM
claude -p "Ajude a resolver o ticket do cliente #12345" \
  --mcp-config support-tools.json \
  --allowedTools "mcp__zendesk,mcp__stripe,mcp__user_db" \
  --append-system-prompt "Você é um especialista em suporte técnico."

Ao usar ferramentas MCP, você deve explicitamente permiti-las usando a flag --allowedTools. Nomes de ferramentas MCP seguem o padrão mcp__<serverName>__<toolName> onde:

serverName é a chave do seu arquivo de configuração MCP
toolName é a ferramenta específica fornecida por esse servidor

Esta medida de segurança garante que ferramentas MCP sejam usadas apenas quando explicitamente permitidas.Se você especificar apenas o nome do servidor (ou seja, mcp__<serverName>), todas as ferramentas desse servidor serão permitidas.Padrões glob (por exemplo, mcp__go*) não são suportados.

Ferramenta de prompt de permissão personalizada

Opcionalmente, use --permission-prompt-tool para passar uma ferramenta MCP que usaremos para verificar se o usuário concede ou não permissões ao modelo para invocar uma determinada ferramenta. Quando o modelo invoca uma ferramenta, acontece o seguinte:

Primeiro verificamos configurações de permissão: todos os arquivos settings.json, bem como --allowedTools e --disallowedTools passados para o SDK; se uma dessas permite ou nega a chamada da ferramenta, prosseguimos com a chamada da ferramenta
Caso contrário, invocamos a ferramenta MCP que você forneceu em --permission-prompt-tool

A ferramenta MCP --permission-prompt-tool recebe o nome da ferramenta e entrada, e deve retornar um payload JSON-stringified com o resultado. O payload deve ser um dos seguintes:

// chamada de ferramenta é permitida
{
  "behavior": "allow",
  "updatedInput": {...}, // entrada atualizada, ou apenas retorne a entrada original
}

// chamada de ferramenta é negada
{
  "behavior": "deny",
  "message": "..." // string legível explicando por que a permissão foi negada
}

Exemplos de implementação:

# Usar com sua configuração de servidor MCP
claude -p "Analise e corrija os problemas de segurança" \
  --permission-prompt-tool mcp__security__approval_prompt \
  --mcp-config security-tools.json \
  --allowedTools "Read,Grep" \
  --disallowedTools "Bash(rm*),Write"

# Com regras de permissão personalizadas
claude -p "Refatore a base de código" \
  --permission-prompt-tool mcp__custom__permission_check \
  --mcp-config custom-config.json \
  --output-format json

Notas de uso:

Use updatedInput para dizer ao modelo que o prompt de permissão mutou sua entrada; caso contrário, defina updatedInput para a entrada original, como no exemplo acima. Por exemplo, se a ferramenta mostra um diff de edição de arquivo para o usuário e permite que eles editem o diff manualmente, a ferramenta de prompt de permissão deve retornar essa edição atualizada.
O payload deve ser JSON-stringified

Formatos de saída

O SDK suporta múltiplos formatos de saída:

Saída de texto (padrão)

claude -p "Explique o arquivo src/components/Header.tsx"
# Saída: Este é um componente React mostrando...

Saída JSON

Retorna dados estruturados incluindo metadados:

claude -p "Como funciona a camada de dados?" --output-format json

Formato de resposta:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "O texto de resposta aqui...",
  "session_id": "abc123"
}

Saída JSON de transmissão

Transmite cada mensagem conforme é recebida:

$ claude -p "Construa uma aplicação" --output-format stream-json

Cada conversa começa com uma mensagem inicial do sistema init, seguida por uma lista de mensagens do usuário e assistente, seguida por uma mensagem final do sistema result com estatísticas. Cada mensagem é emitida como um objeto JSON separado.

Esquema de mensagem

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

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

  // Uma mensagem do usuário
  | {
      type: "user";
      message: MessageParam; // do SDK Anthropic
      session_id: string;
    }

  // Emitida como a última mensagem
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // Emitida como a última mensagem, quando atingimos o número máximo de rodadas
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // Emitida como a primeira mensagem no início de uma conversa
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

Em breve publicaremos esses tipos em um formato compatível com JSONSchema. Usamos versionamento semântico para o pacote principal Claude Code para comunicar mudanças que quebram compatibilidade neste formato. Os tipos Message e MessageParam estão disponíveis nos SDKs Anthropic. Por exemplo, consulte os SDKs Anthropic TypeScript e Python.

Formatos de entrada

O SDK suporta múltiplos formatos de entrada:

Entrada de texto (padrão)

# Argumento direto
claude -p "Explique este código"

# Do stdin
echo "Explique este código" | claude -p

Entrada JSON de transmissão

Um fluxo de mensagens fornecido via stdin onde cada mensagem representa uma rodada do usuário. Isso permite múltiplas rodadas de uma conversa sem relançar o binário claude e permite fornecer orientação ao modelo enquanto ele está processando uma solicitação. Cada mensagem é um objeto JSON ‘Mensagem do usuário’, seguindo o mesmo formato que o esquema de mensagem de saída. Mensagens são formatadas usando o formato jsonl onde cada linha de entrada é um objeto JSON completo. Entrada JSON de transmissão requer -p e --output-format stream-json. Atualmente isso é limitado a mensagens de usuário apenas de texto.

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explique este código"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

Exemplos de integração de agentes

Bot de resposta a incidentes SRE

#!/bin/bash

# Agente de resposta a incidentes automatizado
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"
    
    claude -p "Incidente: $incident_description (Severidade: $severity)" \
      --append-system-prompt "Você é um especialista SRE. Diagnostique o problema, avalie o impacto e forneça itens de ação imediatos." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# Uso
investigate_incident "API de pagamento retornando erros 500" "high"

Revisão de segurança automatizada

# Agente de auditoria de segurança para pull requests
audit_pr() {
    local pr_number="$1"
    
    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "Você é um engenheiro de segurança. Revise este PR em busca de vulnerabilidades, padrões inseguros e problemas de conformidade." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Uso e salvar em arquivo
audit_pr 123 > security-report.json

Assistente jurídico de múltiplas rodadas

# Revisão de documento jurídico com persistência de sessão
session_id=$(claude -p "Iniciar sessão de revisão jurídica" --output-format json | jq -r '.session_id')

# Revisar contrato em múltiplas etapas
claude -p --resume "$session_id" "Revisar contract.pdf em busca de cláusulas de responsabilidade"
claude -p --resume "$session_id" "Verificar conformidade com requisitos GDPR" 
claude -p --resume "$session_id" "Gerar resumo executivo dos riscos"

Melhores Práticas Específicas do Python

Padrões Principais

import asyncio
from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions

# Sempre use gerenciadores de contexto
async with ClaudeSDKClient() as client:
    await client.query("Analise este código")
    async for msg in client.receive_response():
        # Processar mensagens de transmissão
        pass

# Executar múltiplos agentes simultaneamente
async with ClaudeSDKClient() as reviewer, ClaudeSDKClient() as tester:
    await asyncio.gather(
        reviewer.query("Revisar main.py"),
        tester.query("Escrever testes para main.py")
    )

# Tratamento de erros
from claude_code_sdk import CLINotFoundError, ProcessError

try:
    async with ClaudeSDKClient() as client:
        # Seu código aqui
        pass
except CLINotFoundError:
    print("Instalar CLI: npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"Erro de processo: {e}")

# Coletar resposta completa com metadados
async def get_response(client, prompt):
    await client.query(prompt)
    text = []
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    text.append(block.text)
        if type(msg).__name__ == "ResultMessage":
            return {'text': ''.join(text), 'cost': msg.total_cost_usd}

Dicas IPython/Jupyter

# No Jupyter, use await diretamente em células
client = ClaudeSDKClient()
await client.connect()
await client.query("Analisar data.csv")
async for msg in client.receive_response():
    print(msg)
await client.disconnect()

# Criar funções auxiliares reutilizáveis
async def stream_print(client, prompt):
    await client.query(prompt)
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    print(block.text, end='', flush=True)

Melhores práticas

Use formato de saída JSON para análise programática de respostas:

# Analisar resposta JSON com jq
result=$(claude -p "Gerar código" --output-format json)
code=$(echo "$result" | jq -r '.result')
cost=$(echo "$result" | jq -r '.cost_usd')

Trate erros graciosamente - verifique códigos de saída e stderr:

if ! claude -p "$prompt" 2>error.log; then
    echo "Erro ocorreu:" >&2
    cat error.log >&2
    exit 1
fi

Use gerenciamento de sessão para manter contexto em conversas de múltiplas rodadas

Considere timeouts para operações de longa duração:

timeout 300 claude -p "$complex_prompt" || echo "Timeout após 5 minutos"

Respeite limites de taxa ao fazer múltiplas solicitações adicionando atrasos entre chamadas

Recursos relacionados

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

Release Notes

​Por que usar o Claude Code SDK?

​O que você pode construir com o SDK?

​Início rápido

​Uso principal

​Visão geral

​Autenticação

​Chave de API Anthropic

​Credenciais de API de terceiros

​Conversas de múltiplas rodadas

​Usando Modo de Planejamento

​Prompts de sistema personalizados

​Uso Avançado

​Ferramentas personalizadas via MCP

​Ferramenta de prompt de permissão personalizada

​Formatos de saída

​Saída de texto (padrão)

​Saída JSON

​Saída JSON de transmissão

​Esquema de mensagem

​Formatos de entrada

​Entrada de texto (padrão)

​Entrada JSON de transmissão

​Exemplos de integração de agentes

​Bot de resposta a incidentes SRE

​Revisão de segurança automatizada

​Assistente jurídico de múltiplas rodadas

​Melhores Práticas Específicas do Python

​Padrões Principais

​Dicas IPython/Jupyter

​Melhores práticas

​Recursos relacionados

Por que usar o Claude Code SDK?

O que você pode construir com o SDK?

Início rápido

Uso principal

Visão geral

Autenticação

Chave de API Anthropic

Credenciais de API de terceiros

Conversas de múltiplas rodadas

Usando Modo de Planejamento

Prompts de sistema personalizados

Uso Avançado

Ferramentas personalizadas via MCP

Ferramenta de prompt de permissão personalizada

Formatos de saída

Saída de texto (padrão)

Saída JSON

Saída JSON de transmissão

Esquema de mensagem

Formatos de entrada

Entrada de texto (padrão)

Entrada JSON de transmissão

Exemplos de integração de agentes

Bot de resposta a incidentes SRE

Revisão de segurança automatizada

Assistente jurídico de múltiplas rodadas

Melhores Práticas Específicas do Python

Padrões Principais

Dicas IPython/Jupyter

Melhores práticas

Recursos relacionados