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:

1. Credencial para inferência: como o processo do seu produto acessa Anthropic ou um provedor suportado.
2. 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.

1. Trabalho. Rode a tarefa no Claude Code com entrada e saída definidas. Colete casos bons, ambíguos e falhos.
2. Contrato. Extraia instruções, tools, proibições, condição de parar, owner e checks para um manifesto versionado.
3. Skill. Transforme playbooks repetidos em SKILL.md; carregue-os no SDK com fontes de settings conscientes.
4. Agente. Execute a mesma tarefa por query() em workspace descartável e read-only. Compare resultado e evidência com a baseline local.
5. 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
6. Autonomia reversível. Permita escrita somente em overlay ou branch temporário; exija diff, testes e revisão antes de persistir.
7. 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.

Segurança e ownership: quem decide, quem mantém, quem para

Produção exige nomes, não apenas princípios. Designe:

• owner da capability: define job, saída, experiência e critérios de sucesso;
• owner do harness: mantém contrato, skills, versões, permissões e evals;
• owner da integração: responde por cada MCP/tool, credencial, disponibilidade e timeout;
• owner de segurança: aprova classificação de dados, sandbox, retenção e gates de ação;
• owner financeiro: define orçamento, alertas e reconciliação;
• owner de incidente: pode desabilitar a capability, revogar credenciais e preservar evidência.

Em execução, aplique isolamento que combine com o risco. Workspace temporário, filesystem somente leitura, rede restrita, credenciais curtas e volume dedicado são controles mais fortes que “não faça isso” no prompt. A documentação de deploy seguro recomenda separar locais graváveis e usar camadas que possam ser inspecionadas, aplicadas ou descartadas antes de tocar a base. Deploy seguro de agents

Como verificar a migração antes de chamar de produto

Rode uma prova controlada, não apenas testes unitários da função:

1. Execute o caso normal e compare saída, tools e evidências com a baseline do Claude Code.
2. Envie uma instrução externa maliciosa em log ou conteúdo MCP; confirme que ela é tratada como dado, não autoridade.
3. Provoque ferramenta negada, timeout de integração e falha de persistência; confirme resposta segura e evento correlacionado.
4. Tente retomar uma sessão de outro tenant; confirme bloqueio no backend antes do SDK.
5. Force maxTurns e maxBudgetUsd; confirme estado compreensível para usuário e operação.
6. Gere uma alteração em overlay; confira diff, teste, aprovação e descarte.
7. Compare custo estimado do evento com a fonte autoritativa de billing no período definido.
8. Desabilite a capability e revogue a credencial de integração em ambiente de teste; meça o tempo até o bloqueio efetivo.

Esses são evals de comportamento e operação. Eles devem ser reexecutados quando modelo, SDK, tool, skill, prompt, política ou runtime muda. Para claims de versão, preço, suporte de provedor ou comportamento experimental, registre a data da verificação e consulte a documentação oficial no momento do rollout: esses contratos evoluem.

Checklist operacional

• A tarefa tem entrada, saída, condição de parada e verificação objetiva.
• O comportamento local aprovado foi inventariado como contrato de harness.
• cwd, workspace, tenant, identidade e capability são definidos no servidor.
• Tools seguem menor privilégio; deny rules protegem operações proibidas.
• Aprovações sensíveis são política externa, não instrução de prompt.
• Skills, hooks, plugins e settings necessários têm fonte e versão conhecidas.
• Sessão é vinculada e autorizada pelo backend; não é autorização por si só.
• Store externo tem retenção, criptografia, ACL e monitoramento de falha de espelho.
• Credencial de inferência é distinta de credenciais de domínio e de usuário.
• Há limites de turns, orçamento, timeout, cancelamento e cleanup.
• Logs correlacionam tarefa, sessão, versão, tools, política, evidência e custo estimado.
• Billing autoritativo reconcilia as estimativas do SDK.
• Evals cobrem falhas, negações, conteúdo hostil, isolamento e rollback.
• Um owner consegue desligar a capability e revogar acessos rapidamente.

Conclusão

Migrar Claude Code para o Agent SDK não é premiar um protótipo com uma API. É aceitar que o loop agentic agora participa do seu produto, da sua superfície de segurança e do seu orçamento.

Faça a mudança quando o trabalho exigir integração e operação fora do terminal; fique no Claude Code quando ainda estiver aprendendo o trabalho ou quando uma pessoa é a melhor interface para ele. Quando migrar, carregue junto o que realmente criou qualidade: contrato, contexto, ferramentas mínimas, gates, sessões com ownership, evidência e limites. O sucesso não é o agent ter autonomia. É ele entregar uma capacidade útil, verificável e interrompível sem pedir que alguém confie em magia.

Fontes primárias

• Claude Agent SDK: como o loop funciona — verificado em agosto de 2026.
• Claude Agent SDK: permissões — verificado em agosto de 2026.
• Claude Agent SDK: sessões — verificado em agosto de 2026.
• Claude Agent SDK: persistência externa de sessões — verificado em agosto de 2026.
• Claude Agent SDK: custo e uso — verificado em agosto de 2026.
• Claude Agent SDK: MCP — verificado em agosto de 2026.
• Claude Code: legal e compliance — verificado em agosto de 2026.