English 中文 العربية 日本語 Português

Claude Code: Agent SDK

Última atualização: 2026-08-31

O Agent SDK transforma as capacidades do Claude Code em uma API programável — incorpore habilidades de programação com IA em suas aplicações, construa fluxos de trabalho com IA customizados.

💡 Dica: O Agent SDK não torna o Claude Code um servidor de API; fornece um SDK para chamar as capacidades de Agent do Claude Code no seu código — leitura/escrita de arquivos, geração de código, execução de testes, etc.

📋 Pré-requisitos: Capítulo 23 - Fluxo de Trabalho Git e GitHub Actions

1. O Que Você Vai Aprender

2. Arquitetura do Agent SDK

(1) SDK vs CLI

Dimensão CLI SDK
Uso Comando no terminal Invocação por código
Interação Conversa humana Interface de programação
Customizabilidade Limitada Totalmente customizável
Integração Pipeline/scripts Incorporação profunda
Caso de uso Desenvolvimento diário Construir aplicações com IA

▶ Exemplo 1: Uso Básico do SDK

TYPESCRIPT 
import { Agent } from "@anthropic-ai/claude-code-sdk";

const agent = new Agent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: "claude-sonnet-4-20250514",
  workingDir: "./my-project",
});

const result = await agent.run("Add user login with JWT authentication");

console.log(result.summary);
console.log(`Files modified: ${result.files.length}`);
console.log(`Tests passed: ${result.testsPassed}`);

3. API Central

(1) Criação e Configuração de Agent

TYPESCRIPT 
const agent = new Agent({
  apiKey: "sk-ant-api03-xxxxx",
  model: "claude-sonnet-4-20250514",
  workingDir: "/path/to/project",
  tools: ["Read", "Write", "Bash"],
  maxTurns: 30,
  style: "concise",
});

(2) Executar Tarefas

TYPESCRIPT 
// Execução básica
const result = await agent.run("Fix all TypeScript errors");

// Execução com streaming
const stream = agent.runStream("Refactor auth module");
for await (const event of stream) {
  console.log(event.type, event.data);
}

// Com contexto
const result = await agent.run("Modify this function", {
  files: ["src/auth/jwt.ts"],
  context: "Use RS256 instead of HS256",
});

(3) Tratamento de Resultados

TYPESCRIPT 
interface AgentResult {
  summary: string;
  files: FileChange[];
  commands: CommandResult[];
  testsPassed: number;
  testsFailed: number;
  tokensUsed: number;
  cost: number;
}

▶ Exemplo 2: Fluxo de Trabalho Customizado

TYPESCRIPT 
async function reviewAndFix(projectDir: string) {
  const agent = new Agent({
    apiKey: process.env.ANTHROPIC_API_KEY!,
    workingDir: projectDir,
    tools: ["Read", "Write", "Bash"],
  });

  // Passo 1: Code review
  const review = await agent.run(
    "Review project code quality, list all issues to fix"
  );

  // Passo 2: Auto-correção
  if (review.summary.includes("issue")) {
    const fix = await agent.run("Fix all listed quality issues, run tests");
    console.log(`Tests: ${fix.testsPassed} passed, ${fix.testsFailed} failed`);
  }
}

4. Agent Customizado

(1) Ferramentas Customizadas

TYPESCRIPT 
const databaseQueryTool: Tool = {
  name: "database_query",
  description: "Execute a read-only SQL query",
  parameters: {
    sql: { type: "string", description: "SQL query (SELECT only)" },
  },
  execute: async ({ sql }) => {
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      throw new Error("Only SELECT queries allowed");
    }
    const result = await db.query(sql);
    return { rows: result.rows, count: result.rowCount };
  },
};

const agent = new Agent({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  tools: ["Read", "Write", databaseQueryTool],
});

(2) Escuta de Eventos

TYPESCRIPT 
agent.on("file:write", (data) => {
  console.log(`Modified: ${data.filePath}`);
  auditLog.record(data);
});

agent.on("bash:execute", (data) => {
  if (data.command.includes("DROP")) {
    throw new Error("Dangerous command blocked");
  }
});

▶ Exemplo 3: Bot de Code Review

TYPESCRIPT 
class CodeReviewBot {
  private agent: Agent;

  constructor(apiKey: string) {
    this.agent = new Agent({
      apiKey,
      model: "claude-sonnet-4-20250514",
      tools: ["Read", "Bash"],
    });
  }

  async reviewPR(repoDir: string, prDiff: string) {
    this.agent.setWorkingDir(repoDir);
    const result = await this.agent.run(
      `Review PR changes:\n${prDiff}\n\nCheck security, performance, style, test coverage`
    );
    return { review: result.summary, score: this.calculateScore(result.summary) };
  }

  private calculateScore(text: string): number {
    let score = 100;
    if (text.includes("critical")) score -= 30;
    if (text.includes("warning")) score -= 10;
    return Math.max(0, score);
  }
}

5. Colaboração SDK vs CLI

Cenário CLI SDK
Desenvolvimento diário ✅ ❌
CI/CD ✅ (headless) ✅
Ferramentas customizadas ❌ ✅
Integração com web app ❌ ✅
Automação em lote ⚠️ (scripts) ✅

❓ Perguntas Frequentes

P: O SDK requer instalação separada do CLI? R: Não. O SDK é um pacote npm independente. Ambos compartilham a mesma API Key.

P: A API do SDK é estável? R: A API central é estável, mas detalhes podem mudar com versões. Bloqueie números de versão, observe o changelog.

P: O SDK pode rodar no browser? R: Não. Precisa de ambiente Node.js; envolve operações de sistema de arquivos e Shell.

P: Mesmo preço que o CLI? R: Sim. Ambos chamam a API da Anthropic com a mesma cobrança.

📖 Resumo

📝 Exercícios

  1. Básico (⭐): Crie um Agent com SDK, execute uma tarefa simples, imprima resultados.
  2. Intermediário (⭐⭐): Construa um script de auto code review com saída estruturada.
  3. Avançado (⭐⭐⭐): Construa um bot de code review integrado com GitHub Webhook para auto review de PR.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%