Claude Code SDK: Guia do Programador para Construir Agentes

O Claude Code SDK transforma o Claude Code de um assistente de codificação interativo num runtime de agente totalmente programável. Se tem utilizado o Claude Code de forma interativa, o SDK abre um conjunto fundamentalmente diferente de possibilidades — pipelines automatizados, UIs personalizadas, orquestração multi-agente e integração com CI/CD.

O que é o Claude Code SDK?

O Claude Code SDK é uma interface programática que permite:

• Executar o Claude Code de forma não interativa a partir de scripts e pipelines
• Controlar quais ficheiros, diretórios e ferramentas estão no contexto
• Analisar saídas estruturadas para processamento subsequente
• Encadear o Claude Code com outras ferramentas em fluxos de trabalho automatizados
• Construir UIs personalizadas sobre o raciocínio do Claude Code

Disponível como pacote Node.js:

npm install @anthropic-ai/claude-code

Ou invocar via CLI em modo não interativo:

claude -p "O seu prompt aqui" --output-format json

Conceitos Fundamentais do SDK

Modo Não Interativo

O caso de utilização mais básico do SDK: execute o Claude Code com um prompt, obtenha a saída, terminado.

# CLI não interativo
claude -p "Rever src/auth.ts à procura de vulnerabilidades de segurança" \
  --output-format json \
  --max-turns 5

// SDK
const { query } = require('@anthropic-ai/claude-code');

const result = await query({
  prompt: "Rever src/auth.ts à procura de vulnerabilidades de segurança",
  options: {
    maxTurns: 5,
    outputFormat: 'json'
  }
});

Configuração de Ferramentas

Controle as ferramentas a que o Claude Code tem acesso na sua chamada SDK:

const result = await query({
  prompt: "Gerar um conjunto de testes para src/utils.ts",
  options: {
    allowedTools: ['Read', 'Write', 'Bash'],
    // Desativar ferramentas desnecessárias:
    // disallowedTools: ['WebSearch', 'mcp__custom_tool']
  }
});

System Prompts Personalizados

Substitua o system prompt predefinido do Claude Code para comportamentos especializados:

const result = await query({
  prompt: "Refatorizar este módulo",
  options: {
    systemPrompt: `É um especialista em TypeScript especializado em padrões de programação funcional.
    Prefira sempre estruturas de dados imutáveis. Utilize tipos Result para o tratamento de erros.
    Nunca utilize os tipos any ou unknown.`,
  }
});

Padrões Práticos com o SDK

1. Revisão de Código Automatizada no CI

// .github/workflows/code-review.js
const { query } = require('@anthropic-ai/claude-code');
const { execSync } = require('child_process');

const diff = execSync('git diff main...HEAD').toString();

const review = await query({
  prompt: `Rever este diff de PR à procura de: problemas de segurança, problemas de desempenho e testes em falta.
  Saída como JSON com as chaves: security[], performance[], testing[].
  
  Diff:
  ${diff}`,
  options: {
    outputFormat: 'json',
    allowedTools: ['Read'],  // Apenas leitura no CI
    maxTurns: 3
  }
});

console.log(JSON.parse(review.result));

2. Geração Automatizada de Documentação

const fs = require('fs');
const { query } = require('@anthropic-ai/claude-code');

async function generateDocs(srcPath) {
  const result = await query({
    prompt: `Gerar documentação JSDoc abrangente para todas as funções exportadas em ${srcPath}.
    Adicionar descrições de parâmetros, tipos de retorno e exemplos de utilização.
    Escrever o ficheiro atualizado com a documentação adicionada.`,
    options: {
      allowedTools: ['Read', 'Write'],
      cwd: process.cwd()
    }
  });
  return result;
}

3. Pipeline Multi-Agente com Capacidades Externas

É aqui que a integração com o AnyCap se torna poderosa. Um pipeline em que o Claude Code trata do raciocínio sobre o código e o AnyCap gere os media e a publicação:

const { query } = require('@anthropic-ai/claude-code');
const { execSync } = require('child_process');

async function buildAndPublishDocs(repoPath) {
  // Passo 1: Claude Code gera a documentação
  const docsResult = await query({
    prompt: "Gerar um README abrangente para este projeto com instruções de configuração, referência de API e exemplos",
    options: {
      cwd: repoPath,
      allowedTools: ['Read', 'Write', 'Bash']
    }
  });

  // Passo 2: AnyCap gera o diagrama hero
  execSync(`anycap image generate \
    --prompt "Diagrama de arquitetura técnica para uma ferramenta de programador, estilo limpo e minimalista" \
    --model nano-banana-2 \
    -o ${repoPath}/docs/architecture.png`);

  // Passo 3: AnyCap publica como página web
  const pageResult = execSync(`anycap page deploy ${repoPath}/docs/`).toString();
  
  return { docs: docsResult, page: JSON.parse(pageResult) };
}

Autenticação do SDK

O SDK utiliza a mesma autenticação do Claude Code. Configure a sua chave de API:

export ANTHROPIC_API_KEY=a_sua_chave_aqui

Ou para ambientes de equipa, utilize configuração específica do ambiente:

const { query } = require('@anthropic-ai/claude-code');

// O SDK lê ANTHROPIC_API_KEY automaticamente
// Ou passe explicitamente:
process.env.ANTHROPIC_API_KEY = await getSecretFromVault('anthropic-api-key');

Formatos de Saída

O SDK suporta três formatos de saída:

// A saída JSON inclui metadados
{
  "result": "A função tem uma potencial vulnerabilidade de SQL injection...",
  "is_error": false,
  "session_id": "sess_xxxx",
  "cost_usd": 0.0043,
  "num_turns": 2
}

Limites de Taxa e Gestão de Custos em Fluxos de Trabalho com SDK

A automação baseada em SDK pode consumir tokens mais rapidamente do que a utilização interativa. Salvaguardas integradas:

const result = await query({
  prompt: "...",
  options: {
    maxTurns: 5,        // Limitar iterações de raciocínio
    timeoutMs: 30000,   // Timeout para tarefas de longa duração
  }
});

// Verifique sempre o custo em produção
if (result.cost_usd > 0.10) {
  logger.warn(`Sessão de custo elevado: $${result.cost_usd}`);
}

Para tarefas com utilização intensiva de capacidades (geração de imagens, criação de vídeos, pesquisa na web), delegue ao AnyCap em vez de deixar o Claude Code lidar com elas no contexto. Isto mantém os custos do SDK previsíveis e evita atingir os limites de taxa do Claude em tarefas que não são de raciocínio.

Primeiros Passos

# Instalar o SDK
npm install @anthropic-ai/claude-code

# Instalar o AnyCap para extensão de capacidades
curl -fsSL https://anycap.ai/install.sh | sh

# Adicionar skill do AnyCap ao Claude Code
npx -y skills add anycap-ai/anycap -y

→ AnyCap para Claude Code → Guia para Adicionar Ferramentas ao Claude Code