Claude Agent SDK: integre Claude Code em apps com segurança

Se você quer tirar o Claude Code do uso apenas interativo no terminal e colocá-lo em ferramentas internas, CI, revisão prévia de PR, QA de conteúdo ou painéis de suporte, o caminho atual é o Claude Agent SDK.

Muitos exemplos antigos ainda usam @anthropic-ai/claude-code, claude-code-sdk ou o nome “Claude Code SDK”. Em junho de 2026, a documentação oficial aponta para @anthropic-ai/claude-agent-sdk em TypeScript e claude-agent-sdk em Python. Antes de copiar código antigo, confira o Agent SDK overview e o Migration Guide.

Este artigo não é um demo de chatbot. A ideia é criar agentes que leem arquivos, pesquisam no repositório, chamam ferramentas MCP, fazem uma correção pequena com permissões restritas, executam um teste específico e retornam evidência revisável.

Como entender o Agent SDK hoje

Claude Agent SDK permite usar, dentro de um programa TypeScript ou Python, o agent loop que alimenta o Claude Code. Agent loop é o ciclo em que Claude escolhe a próxima ação, chama uma ferramenta, lê o resultado e decide se continua. Isso é diferente de uma chamada API comum de pergunta e resposta.

Tema	Recomendação atual
Pacote TypeScript	@anthropic-ai/claude-agent-sdk
Pacote Python	claude-agent-sdk
CLI vs SDK	CLI para humanos, SDK para apps e automações
Client SDK vs Agent SDK	Client SDK exige loop próprio; Agent SDK usa o loop do Claude Code
Risco principal	Permissões amplas aumentam utilidade e risco

O SDK de TypeScript normalmente inclui um binário nativo do Claude Code como dependência opcional, então nem sempre é preciso instalar a CLI separadamente. Se o gerenciador de pacotes pular optional dependencies, o binário pode não ser encontrado. Corrija a instalação ou passe o caminho com pathToClaudeCodeExecutable.

Setup mínimo copiável

Usaremos TypeScript com tsx para executar sem pipeline de build.

mkdir claude-agent-sdk-demo
cd claude-agent-sdk-demo
npm init -y
npm install @anthropic-ai/claude-agent-sdk zod
npm install -D typescript tsx @types/node

Organize o package.json assim:

{
  "type": "module",
  "scripts": {
    "audit": "tsx src/read-only-audit.ts",
    "runbook": "tsx src/runbook-agent.ts",
    "fix": "tsx src/safe-fix.ts"
  },
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest"
  }
}

A chave da API deve vir do ambiente. Não coloque em repositório, artigo, print ou log de CI.

export ANTHROPIC_API_KEY="sk-ant-..."

No Windows PowerShell:

$env:ANTHROPIC_API_KEY = "sk-ant-..."

Crie primeiro src/read-only-audit.ts. Este agente só lê e pesquisa; não edita arquivos nem executa shell.

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

const prompt = [
  "Inspecione este repositório em modo somente leitura.",
  "Encontre TODOs, dependências antigas e áreas com testes fracos.",
  "Retorne uma lista priorizada com referências de arquivos.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 4,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Execute:

npm run audit

Começar por leitura não é burocracia. Você valida o sinal antes de abrir Edit, Write ou Bash.

Casos de uso com retorno real

Claude Agent SDK funciona melhor quando a tarefa pede observação, uso de ferramenta e decisão. Nos fluxos de conteúdo e desenvolvimento de Masa, eu priorizaria estes casos:

Caso	Ferramentas	Saída	Limite
Pré-revisão de PR	Read, Glob, Grep	Riscos, testes ausentes, foco do review	Comentário final fica com humano
Pequena correção	Read, Edit, Bash(npm test)	Diff mínimo e resultado de testes	Bloquear push, deploy e remoção
Triage de incidente	MCP runbook e busca de logs	Hipóteses e próximos checks	Produção em leitura
QA de artigos multilíngues	Read, Grep	Mojibake, CTA ausente, links antigos	Naturalidade revisada por humano

Para contexto interno, leia também o guia de permissões, o guia de MCP server e as dicas de produtividade Claude Code.

Runbook com MCP

MCP significa Model Context Protocol. É um padrão para expor ferramentas e fontes de dados para um agente. O guia oficial de MCP mostra como conectar servidores MCP ao Agent SDK. Também dá para criar um servidor pequeno no mesmo processo.

import {
  createSdkMcpServer,
  query,
  tool,
} from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const runbooks: Record<string, string> = {
  billing: "Verificar pagamentos falhos, webhooks Stripe e último deploy.",
  search: "Verificar horário de index, task status Algolia e limites API.",
  content: "Verificar sync do CMS, slugs por locale e imagem hero.",
};

const lookupRunbook = tool(
  "lookup_runbook",
  "Retorna um runbook operacional somente leitura para um serviço",
  { service: z.string().min(1) },
  async ({ service }) => {
    const text = runbooks[service] ?? "Nenhum runbook encontrado.";
    return { content: [{ type: "text", text }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: false } },
);

const runbookServer = createSdkMcpServer({
  name: "runbook",
  version: "1.0.0",
  tools: [lookupRunbook],
});

for await (const message of query({
  prompt: "Sugira os primeiros checks para um incidente de publicação.",
  options: {
    mcpServers: { runbook: runbookServer },
    allowedTools: ["mcp__runbook__lookup_runbook"],
    maxTurns: 3,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

O erro comum é liberar o nome errado. Em allowedTools, ferramentas MCP usam mcp__serverName__toolName. Apenas lookup_runbook não aprova a chamada.

Editar com limites claros

Depois que a auditoria em leitura for útil, permita pequenas correções. Leia o guia oficial de permissions antes de qualquer agente que escreva arquivos ou rode comandos.

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

const prompt = [
  "Corrija apenas um pequeno erro TypeScript em src.",
  "Depois rode npm test e reporte o resumo do diff.",
  "Não faça refactor amplo nem adicione dependências.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Bash(npm test)",
    ],
    disallowedTools: [
      "Bash(git push)",
      "Bash(git commit)",
      "Bash(rm -rf *)",
    ],
    permissionMode: "default",
    maxTurns: 6,
  },
})) {
  if (message.type === "result") {
    console.log(message.subtype, message.result ?? "");
  }
}

Isso cria um diff revisável com prova de teste. Não é um padrão para deixar o agente fazer push, deploy, release ou tocar dados sensíveis.

Armadilhas comuns

A primeira é nome antigo. Se o exemplo usa @anthropic-ai/claude-code ou ClaudeCodeOptions, confira se está antes da migração.

A segunda é Bash amplo. Permitir shell livre pode incluir limpeza, git, deploy, instalação de pacotes e scripts com efeitos colaterais. Comece com Bash(npm test).

A terceira é não definir cwd. Local, CI e worker podem iniciar em pastas diferentes. Código de produção deve apontar claramente para o repositório certo.

A quarta é tratar Agent SDK como chat SDK. Um agente pode ler muitos arquivos e usar vários turnos. Consulte o cost tracking guide, registre usage e defina limites.

A quinta é criar ferramentas vagas. Nome, descrição, schema e anotações devem deixar claro quando usar a ferramenta e se ela é somente leitura.

Checklist, CTA e verificação

• API keys e tokens não aparecem em logs.
• A primeira execução usa só Read, Glob, Grep.
• Agentes com escrita têm cwd, permissões e maxTurns.
• MCP separa leitura de ações destrutivas.
• Comandos de teste são específicos, não shell livre.
• Uma pessoa revisa diff e testes antes do merge.

Claude Agent SDK não é sobre automatizar tudo. É sobre tornar a automação revisável. Isso também importa para monetização: CTA, links de produto, analytics events e formulários podem mudar juntos.

Para começar, use o cheatsheet gratuito. Para prompts e materiais reutilizáveis, veja produtos. Para rollout em equipe, permissões, MCP e gates de CI, use treinamento e consultoria Claude Code.

Nesta atualização conferi as páginas oficiais de overview, TypeScript reference, MCP, permissions, migration e cost tracking. A melhoria prática mais importante foi deixar o primeiro exemplo somente leitura: npm run audit permite observar antes de adicionar MCP, edição e testes.