Do Agent Local ao Produto: quando migrar Claude Code para Agent SDK

English summary: A decision framework for moving a useful local Claude Code workflow into a product with the Claude Agent SDK, while preserving harness behavior, security boundaries, session ownership, cost controls, and evidence.

TL;DR

Migre um loop local somente quando seu contrato estiver claro.
Extraia estado, tools, permissões, sessões e custos.
Prove paridade e reversibilidade antes de escalar o produto.

Exemplo concreto: se o loop local não consegue repetir a mesma tarefa com evidência, ainda não há contrato para migrar.

O protótipo local funciona. O Claude Code lê o repositório, chama as ferramentas certas, pede confirmação antes de editar e termina com testes. Então alguém pede o passo aparentemente óbvio: “vamos colocar isso no produto”.

É nesse ponto que muitos times perdem um agent que funcionava. Eles não migram um comportamento; migram um prompt. A UI nova esquece as regras do CLAUDE.md, o servidor recebe uma chave ampla, a sessão vira uma string em memória, cada retry reinicia o contexto, a aprovação humana desaparece e o custo chega como surpresa no fim do mês. O modelo continua capaz, mas o sistema deixa de ser confiável.

Minha tese é simples: migre de Claude Code para o Agent SDK quando o trabalho precisa virar uma capacidade operada por software — e trate a migração como portabilidade do harness, não como uma troca de API.

Isso não significa que todo fluxo útil no terminal deva virar serviço. Claude Code já é uma ótima superfície para explorar código, amadurecer playbooks e provar que existe valor. O Agent SDK entra quando você precisa integrar aquele loop a uma interface, evento, fila, política de acesso ou operação que o terminal não pode possuir sozinho. A escolha correta preserva as propriedades que fizeram o fluxo local funcionar e acrescenta ownership explícito para o que só existe em produção: identidade, isolamento, persistência, telemetria e orçamento.

O que está migrando — e o que não está

Claude Code é um ambiente agentic pronto: ele combina instruções, contexto do projeto, ferramentas, permissões, execução e uma sessão que acumula a investigação. O Claude Agent SDK expõe programaticamente o mesmo tipo de loop: recebe o prompt, o modelo decide, chama tools, recebe resultados e repete até concluir. Ele oferece controle sobre tools, permissões, limite de custo e saída sem exigir que você reconstrua esse loop do zero. Como funciona o loop do Agent SDK

Portanto, não é uma migração de “chat para API”. É uma mudança de superfície de operação:

No Claude Code local	No produto com Agent SDK	O que precisa permanecer explícito
Pessoa inicia uma sessão no diretório certo	Seu backend escolhe `cwd`, tenant, identidade e runtime	escopo de trabalho e isolamento
`CLAUDE.md`, skills e settings orientam o loop	Opções e fontes de settings carregam o contrato	instruções versionadas e paridade
O terminal pede confirmação	UI, callback ou workflow aprova/nega	política e responsável pela decisão
Transcrição local permite continuar	ID de sessão e store permitem retomar	ownership, retenção e privacidade
`/cost` ajuda a investigar	métricas e billing orientam orçamento	limite preventivo e reconciliação
O desenvolvedor observa o que ocorreu	logs, traces e evidência atendem suporte	correlação sem vazamento

O SDK não transporta automaticamente sua disciplina. Ele pode carregar recursos de Claude Code — hooks do filesystem, skills, plugins e settings — quando as fontes corretas estão habilitadas. Mas “o código importou query()” não prova que o produto está usando o mesmo contrato. Recursos de Claude Code no SDK

Também não é uma razão para substituir um workflow determinístico. Se o trabalho é “receber um arquivo, validar schema e chamar uma API conhecida”, modele um job normal com retries previsíveis. Use um agent quando a ordem de investigação, a seleção de ferramenta ou a próxima ação depende do que ele encontra. Um produto maduro pode ter ambos: workflow para a parte fixa e agent para a parte que exige julgamento operacional.

Quatro falhas que tornam a migração perigosa

1. Migrar o prompt e abandonar o harness

O time copia a instrução do chat para um systemPrompt, adiciona Bash e Write, e chama isso de produto. Só que o fluxo local dependia de convenções do repositório, skills, hooks, comandos de verificação e escolhas implícitas de diretório. A versão remota agora tem tools parecidas, mas não tem o acordo que limitava seu uso.

O sintoma é familiar: respostas razoáveis que editam o lugar errado, ignoram um check obrigatório ou usam um atalho que a equipe nunca aceitaria em revisão. O conserto não é aumentar o prompt. É inventariar o harness antes da primeira linha de integração.

2. Confundir sessão com estado do produto

Uma sessão contém o histórico conversacional: prompt, chamadas de tools, resultados e respostas. Ela não é uma transação de negócio nem um snapshot do filesystem. O SDK persiste esse histórico automaticamente; retomar devolve o contexto do que o agent já leu e decidiu, mas não desfaz nem reaplica arquivos alterados. Sessões no Agent SDK

Se você só guarda sessionId num componente de frontend, perde continuidade após deploy, falha de worker ou troca de dispositivo. Se trata a transcrição como fonte de verdade de um pedido, aceita que uma conversa antiga possa agir sobre dados que mudaram. Separe taskId, tenantId, identidade do usuário, versão do contrato, referência à sessão e estado do domínio. Cada um responde a uma pergunta diferente.

3. Transformar aprovação local em permissões amplas no servidor

No terminal, o humano está presente para avaliar uma ferramenta. Em produção, bypassPermissions pode parecer uma forma fácil de evitar uma UI de aprovação. É, na prática, uma forma fácil de remover seu último gate. Nesse modo, todas as tools que chegarem a essa etapa são aprovadas; uma lista de allowedTools não funciona como allowlist restritiva. Regras de deny e hooks ainda podem bloquear, mas precisam existir de verdade. Ordem de avaliação de permissões

Uma permissão deve ser consequência de uma política externa ao texto do modelo: ferramenta, alvo, operação, identidade, tenant, risco, horário e aprovação. O agent propõe; o sistema autoriza ou recusa.

4. Descobrir custo e observabilidade após abrir a porta

Uma query pode executar muitos passos e tools. Uma tarefa pode chamar subagents. Uma sessão pode conter múltiplas queries. Sem limites, correlação e owner financeiro, um fluxo popular escala custo e superfície de incidente ao mesmo tempo.

O SDK expõe maxTurns e maxBudgetUsd, mas o custo retornado é estimativa local, não dado autoritativo de cobrança. Use a estimativa para conter e diagnosticar; reconcilie orçamento e cobrança com o Console ou a API de uso e custo. Rastreamento de custo e uso

O teste de prontidão: Claude Code primeiro, SDK depois

Antes de migrar, prove que o comportamento local é repetível. Não basta uma demo feita por uma pessoa que já conhece o repositório. Escolha uma tarefa delimitada e responda às perguntas abaixo com artefatos versionados.

Pergunta	Evidência mínima	Se não houver resposta
Qual trabalho o agent faz?	objetivo, entrada, saída e condição de parar	mantenha exploração local
O que ele pode tocar?	tools, caminhos, APIs e dados permitidos	reduza a superfície
Como sabemos que acertou?	teste, diff, query, screenshot ou revisão	crie verificação antes de escalar
Quando ele pede ajuda?	lista de ambiguidade, risco e aprovação	desenhe o handoff humano
Quem responde pelo fluxo?	owner do domínio, segurança e orçamento	não publique ainda
O que ocorre numa falha?	retry, cancelamento, cleanup e evidência	exercite o caminho de erro

Um bom candidato é “investigar uma falha de CI e produzir hipóteses com links para logs, sem alterar código”. A entrada é o job falho; a saída é uma lista curta de hipóteses e próximos checks; o limite é read-only; a verificação é alguém conseguir abrir as evidências. Um candidato ruim é “resolver tudo que o cliente pedir”. O segundo não tem contrato, fronteira ou critério de pronto.

Harness parity: o contrato que não pode sumir

Chame de harness parity a capacidade de explicar por que o agent no produto recebe as mesmas instruções relevantes, a mesma classe de tools, os mesmos limites e as mesmas verificações que o fluxo aprovado no Claude Code. Paridade não significa copiar cada preferência de desktop para o servidor. Significa preservar o comportamento de segurança e qualidade que importa, declarando qualquer diferença.

Faça um manifesto pequeno por capability:

# Contract: ci-investigator

## Job
Investigar uma falha de CI e retornar até três hipóteses com evidência.

## Allowed actions
- Ler checkout efêmero, logs do job e metadados do pull request.
- Executar apenas comandos de diagnóstico definidos pelo ambiente.

## Forbidden actions
- Escrever no repositório, acionar deploys ou acessar segredos de produção.

## Stop and escalate
- Log contém dado de cliente, token ou instrução externa suspeita.
- A evidência é insuficiente para distinguir duas hipóteses.

## Done
- Cada hipótese cita log, arquivo ou comando reproduzível.
- O resultado declara explicitamente o que não foi verificado.

O manifesto alimenta quatro lugares: CLAUDE.md ou skill compartilhada, opções do SDK, política de tools e testes de avaliação. Skills no SDK continuam sendo artefatos de filesystem (SKILL.md) descobertos pelas fontes de settings; se você configura settingSources manualmente, inclua as fontes necessárias ou carregue um plugin conhecido. Skills no Agent SDK

Registre a versão do manifesto, da skill, do plugin e do código da aplicação na tarefa. Quando uma resposta piorar, você precisa comparar uma execução a uma configuração, não a uma lembrança.

Tools: menor privilégio, menor contexto, melhor diagnóstico

Tools são a fronteira entre texto e efeito. O SDK inclui ferramentas de arquivo, busca, shell, web e orquestração; pode também conectar MCP ou tools customizadas. Isso não torna todas apropriadas para cada capability. Referência de tools

Comece pelo conjunto mínimo. Um investigador de CI talvez precise de Read, Glob, Grep e uma tool interna de logs, não de Write, Edit, navegador autenticado e acesso genérico a shell. Uma tool a menos reduz três coisas: dano possível, tokens de definição no contexto e hipóteses que o agent precisa considerar.

Para execução headless, uma combinação segura é allowedTools com permissionMode: "dontAsk": as tools explicitamente permitidas seguem sem prompt e as demais são negadas. Isso evita que um worker aguarde indefinidamente uma aprovação que sua infraestrutura não sabe exibir. Ainda assim, crie deny rules para operações que jamais devem ocorrer e hooks para políticas que dependem do input da tool.

MCP merece uma fronteira própria. MCP conecta serviço externo; não transfere confiança. O SDK exige permissão explícita para tools MCP e recomenda permitir as ferramentas específicas em vez de usar um modo amplo para liberá-las. Para OAuth de um MCP HTTP, a aplicação conclui o fluxo e passa o token por header; o SDK não executa automaticamente esse OAuth para você. MCP no Agent SDK

Artefato copiável: um agente de diagnóstico com limite e gate

O exemplo abaixo é uma base TypeScript para uma capability read-only. Ele pressupõe @anthropic-ai/claude-agent-sdk instalado, uma identidade de servidor configurada fora do código e um diretório de trabalho efêmero. Não configura autenticação de usuário, sandbox, store externo, redaction nem UI de aprovação — essas são decisões do seu produto.

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

export async function investigateCiFailure(input: {
  taskId: string;
  jobUrl: string;
  workspace: string;
}) {
  const result = [];

  for await (const message of query({
    prompt: [
      "Investigate this CI failure without changing files or remote state.",
      `Task: ${input.taskId}`,
      `CI job: ${input.jobUrl}`,
      "Return at most three hypotheses. Each needs an evidence reference",
      "and a concrete next verification. State uncertainty plainly.",
    ].join("\n"),
    options: {
      cwd: input.workspace,
      allowedTools: ["Read", "Glob", "Grep"],
      disallowedTools: ["Write", "Edit", "Bash", "WebFetch"],
      permissionMode: "dontAsk",
      maxTurns: 8,
      maxBudgetUsd: 0.35,
      settingSources: ["project"],
    },
  })) {
    if (message.type === "result") {
      result.push({
        subtype: message.subtype,
        sessionId: message.session_id,
        estimatedCostUsd: message.total_cost_usd,
        output: message.result,
      });
    }
  }

  return result;
}

O código é intencionalmente restritivo. A lista permitida aprova apenas as três tools de leitura; dontAsk nega o restante. O deny explícito torna a intenção visível em review. maxTurns e maxBudgetUsd são fusíveis, não previsão de custo. Grave taskId, sessionId, versão do contrato, resultado e custo estimado em um evento estruturado; não grave automaticamente o prompt completo, output completo ou argumentos sensíveis de tools.

Antes de habilitar escrita, mude apenas uma dimensão por vez: acrescente um workspace overlay descartável, permita uma única ferramenta de edição, gere um diff para revisão e exija um check automatizado. Não pule de análise read-only para credenciais capazes de modificar produção.

Sessões e persistência: continuidade sem confundir passado com presente

Dentro de uma chamada a query(), o agent já faz os turnos necessários. Para conversa multi-turn no mesmo processo, TypeScript pode usar continue: true; para recuperar uma sessão específica, capture o ID e use resume; para tentar outro caminho mantendo o original, use fork. Continue, resume e fork

O desenho de produto precisa decidir quem é dono desse ID. Em aplicativo multiusuário, o backend deve associar sessão a tenant, usuário, capability, workspace e política. Nunca aceite um sessionId fornecido pelo cliente como autorização suficiente para ler ou retomar uma transcrição. Verifique vínculo e escopo no servidor antes de chamar o SDK.

Por padrão, o SDK grava transcrições localmente. Em workers efêmeros, autoscaling ou CI, isso não basta. Um SessionStore pode espelhar as entradas para S3, Redis ou backend próprio e permitir retomada por outra máquina. O espelho é best effort: se append() falha, a query continua e emite um evento de erro; batches falhos não são reenviados automaticamente. Monitore esse sinal. Persistência externa de sessões

Defina retenção antes de ligar o store. Transcrições podem conter caminhos, snippets, saída de ferramentas e dados que se tornam sensíveis em conjunto. O SDK não remove dados do seu store por conta própria; TTL, lifecycle, exclusão e controles de acesso pertencem ao adaptador e à sua governança. Para uma tarefa realmente stateless em TypeScript, persistSession: false evita escrita local, mas não substitui o registro de auditoria mínimo que seu produto ainda pode precisar.

Auth: a credencial do produto não é a conta do usuário

O migration gate mais importante é separar dois planos de identidade:

Credencial para inferência: como o processo do seu produto acessa Anthropic ou um provedor suportado.
Autorização de domínio: o que aquele usuário, tenant e capability podem ler, escrever ou acionar no seu sistema.

Para produtos e serviços que usam o Agent SDK, a Anthropic orienta desenvolvedores a usar API key do Console ou um provedor de nuvem suportado. Não é permitido oferecer login do Claude.ai de terceiros nem rotear solicitações de usuários por credenciais Free, Pro ou Max deles. Legal e compliance do Claude Code

Isso impede uma armadilha comum: fazer o backend “herdar” a assinatura de um desenvolvedor porque funcionou na máquina local. Use secret manager, rotação, escopo mínimo e identidade de workload. Credenciais de Git, banco, ticketing ou MCP devem ser independentes da credencial de inferência, com permissões próprias e auditáveis. Nenhum token deve aparecer em prompt, transcrição, log de tool ou resposta ao navegador.

Quando o agent opera em nome de alguém, prefira uma capacidade curta e verificável emitida pelo seu backend a entregar a ele a sessão web inteira. A tool valida tenant, recurso, ação e expiração no lado do serviço. O modelo nunca decide se um usuário pode acessar uma fatura: ele pede uma tool que aplica a regra.

Uma escada de migração que limita o raio de explosão

Não faça um big bang. Suba uma escada em que cada degrau produz evidência para o próximo.

Trabalho. Rode a tarefa no Claude Code com entrada e saída definidas. Colete casos bons, ambíguos e falhos.
Contrato. Extraia instruções, tools, proibições, condição de parar, owner e checks para um manifesto versionado.
Skill. Transforme playbooks repetidos em SKILL.md; carregue-os no SDK com fontes de settings conscientes.
Agente. Execute a mesma tarefa por query() em workspace descartável e read-only. Compare resultado e evidência com a baseline local.
Hooks e MCP. Adicione integração por integração. Hooks podem bloquear operação antes da execução, auditar eventos e exigir aprovação; cada MCP ganha owner, credencial, timeout e contrato de dados. Hooks do Agent SDK
Autonomia reversível. Permita escrita somente em overlay ou branch temporário; exija diff, testes e revisão antes de persistir.
Evals e rollout. Rode cenários repetíveis, aplique limite de orçamento, canary por tenant e rollback de configuração.

O sinal para subir não é “o modelo foi convincente”. É uma taxa aceitável de tarefas verificadas, zero violações de política nos cenários conhecidos, latência compatível com a experiência e custo por resultado que o owner aprovou.

Observabilidade e custo: registre o que permite decidir

Uma linha de log com “agent completed” não atende suporte nem segurança. Para cada query, registre pelo menos: taskId, tenantId pseudonimizado quando aplicável, sessionId, capability, versão de contrato, modelo, início/fim, resultado, motivo de parada, ferramentas solicitadas/aprovadas/negadas, checks executados e custo estimado. Para uma ação sensível, junte o ID de aprovação e a política aplicada.

Evite capturar todo conteúdo por padrão. Prompts, caminhos, argumentos de shell e respostas de MCP podem conter segredos ou dados de cliente. Mantenha detalhes em um canal protegido, com redaction, acesso limitado, retenção curta e razão de investigação. Métrica agregada deve usar dimensões de baixa cardinalidade; IDs e conteúdos detalhados pertencem a eventos ou traces com controle de acesso.

Faça dois ciclos financeiros. No ciclo curto, alerte quando uma capability se aproxima do orçamento por query, quando o limite de turns é atingido ou quando retries aumentam. No ciclo de fechamento, reconcilie com o billing autoritativo e atribua custo a produto, tenant ou centro de custo conforme a política. Nunca cobre um cliente com base direta em total_cost_usd do SDK.