O que é agente de IA? Diferença pro chatbot + código

Qual a diferença entre chatbot e agente de IA?

O chatbot só gera texto. O agente gera texto e age: chama APIs, lê arquivos, roda comandos.

	Chatbot	Agente de IA
O que faz	Responde e para	Trabalha até cumprir o objetivo
Ferramentas	Nenhuma	APIs, arquivos, comandos
Quem decide o próximo passo	Você	O próprio modelo
Exemplo	“Explique o que é HTTP”	“Veja se meu site está no ar e me avise”

Como funciona o loop de um agente?

Todo agente segue o mesmo ciclo:

1. Pensa: o modelo lê o objetivo e decide o que fazer.
2. Usa uma ferramenta: pede pra chamar, por exemplo, checar_site.
3. Observa: o seu código executa a ferramenta e devolve o resultado.
4. Repete: até o modelo responder sem pedir ferramenta.

Detalhe importante: o modelo não executa nada sozinho. Ele só pede. Quem roda a ferramenta é o seu código. Isso se chama tool calling (ou tool use).

Como criar um agente de IA simples em TypeScript?

Agente mínimo com o SDK oficial da Anthropic (@anthropic-ai/sdk). A ferramenta checa se um site está no ar.

npm install @anthropic-ai/sdk
export ANTHROPIC_API_KEY="sua-chave"

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic(); // lê ANTHROPIC_API_KEY do ambiente

const tools: Anthropic.Tool[] = [{
  name: "checar_site",
  description: "Checa se um site está no ar. Use a URL completa, com https://",
  input_schema: {
    type: "object",
    properties: { url: { type: "string" } },
    required: ["url"],
  },
}];

async function checarSite(url: string): Promise<string> {
  try {
    const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
    return `Status ${res.status}`;
  } catch {
    return "Fora do ar ou sem resposta";
  }
}

const messages: Anthropic.MessageParam[] = [
  { role: "user", content: "Verifique se sujeitoprogramador.com e google.com estão no ar." },
];

for (let passo = 0; passo < 5; passo++) { // limite de passos
  const res = await client.messages.create({
    model: "claude-haiku-5-5", max_tokens: 1024, tools, messages,
  });
  messages.push({ role: "assistant", content: res.content });

  if (res.stop_reason !== "tool_use") { // terminou: mostra a resposta final
    for (const b of res.content) if (b.type === "text") console.log(b.text);
    break;
  }

  const resultados: Anthropic.ToolResultBlockParam[] = [];
  for (const b of res.content) {
    if (b.type !== "tool_use") continue;
    const { url } = b.input as { url: string };
    resultados.push({ type: "tool_result", tool_use_id: b.id, content: await checarSite(url) });
  }
  messages.push({ role: "user", content: resultados });
}

O que está acontecendo:

• tools descreve a ferramenta: nome, descrição e parâmetros. É assim que o modelo sabe que ela existe.
• stop_reason === "tool_use" significa “quero usar uma ferramenta”. Seu código executa e devolve um tool_result com o mesmo id.
• O for com limite é o loop do agente. Sem limite, ele pode rodar (e gastar) pra sempre.

Rode com npx tsx agente.ts (Node 20+). Troque o modelo pelo que estiver disponível na sua conta.

Quando NÃO usar um agente?

Se a tarefa tem passos fixos e conhecidos, escreva código normal. Checar um site a cada 5 minutos é um setInterval com fetch, sem IA nenhuma. Se só precisa de uma resposta em texto, uma chamada simples ao modelo basta. Agente faz sentido quando o caminho muda conforme o resultado, e o modelo precisa decidir o próximo passo. Fora isso, é mais lento, mais caro e mais imprevisível.

Que cuidados tomar ao criar um agente?

• Limite de passos: sempre. No exemplo, 5.
• Aprovação humana: ações perigosas (apagar, pagar, enviar e-mail) passam por você antes.
• Ferramentas mínimas: dê só o que o agente precisa. Ferramenta de leitura é mais segura que de escrita.
• Valide a entrada: o input vem do modelo. Trate como dado de usuário.
• Chave no .env: nunca no código nem no Git.

Perguntas frequentes

ChatGPT é um agente? Depende do modo. Conversando, funciona como chatbot. Quando usa ferramentas (busca, código) em várias etapas, age como agente.

Preciso de framework pra criar um agente? Não. O exemplo acima usa só o SDK oficial. Frameworks ajudam em projetos maiores.

Funciona com OpenAI? Sim. A OpenAI também tem tool calling. Muda a sintaxe, o loop é o mesmo.

Quer criar agentes de verdade?

Esse exemplo é o esqueleto. Agente de produção precisa de memória, várias ferramentas, tratamento de erro e segurança.

É isso que eu ensino na Formação Hermes Agent: do primeiro loop até um agente que trabalha por você.