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:

1

Instalar o SDK

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

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

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"
3

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."
4

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ásico

A 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ção

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

FlagDescriçãoExemplo
--print, -pExecutar em modo não interativoclaude -p "consulta"
--output-formatEspecificar formato de saída (text, json, stream-json)claude -p --output-format json
--resume, -rRetomar uma conversa por ID de sessãoclaude --resume abc123
--continue, -cContinuar a conversa mais recenteclaude --continue
--verboseHabilitar log detalhadoclaude --verbose
--append-system-promptAnexar ao prompt do sistema (apenas com --print)claude --append-system-prompt "Instrução personalizada"
--allowedToolsLista 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"
--disallowedToolsLista 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-configCarregar servidores MCP de um arquivo JSONclaude --mcp-config servers.json
--permission-prompt-toolFerramenta 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:

  1. 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
  2. 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