Pergunte a um chatbot sobre um pedido atrasado e ele lhe dará alguns conselhos. Pergunte a um agente de IA, e ele poderá consultar o pedido, verificar o atraso, aplicar um voucher e reportar. A diferença é que um agente pode agir e reagir ao que acontece, em vez de produzir apenas uma resposta.

O termo é ampliado em marketing, então este guia se concentra em como esses sistemas realmente funcionam. Para torná-lo concreto, construímos um pequeno loop de agente no Python 3.13 e o executamos, e a saída abaixo vem dessas execuções. Nosso “modelo” é uma função com script, não um modelo real de IA, para que o loop possa ser executado e testado por qualquer pessoa. Mostra a estrutura de controle, não a inteligência. Novo no básico? Leia o que é um modelo de linguagem grande primeiro.

O que é um agente de IA?

Não existe uma definição única acordada. Na prática atual, um agente de IA é um software que persegue um objetivo decidindo repetidamente o que fazer a seguir, utilizando ferramentas para agir no mundo e ajustando-o com base nos resultados. Normalmente, a tomada de decisão vem de um grande modelo de linguagem.

Pense na diferença entre uma pessoa que dá instruções e uma pessoa que faz a tarefa. O primeiro responde uma vez. O segundo sai, encontra a loja fechada, tenta outra e só volta quando o trabalho termina.

Chatbot, fluxo de trabalho ou agente?

Eles existem em um espectro e muitos sistemas úteis são uma mistura. A questão principal é quanto do caminho é decidido em tempo de execução.

O que há dentro de um agente

O ciclo do agente

1. Decidir. O modelo analisa o objetivo e o histórico e escolhe uma ação ou decide que ela está concluída.
2. Agir. Seu código executa a ferramenta solicitada.
3. Observe. O resultado é adicionado ao histórico.
4. Repita até que a meta seja atingida ou um limite seja atingido.

Essa é a essência da maioria dos agentes. A sofisticação reside principalmente no modelo, nas ferramentas e nas salvaguardas em torno deste ciclo.

Um loop que você pode executar

Nosso pequeno agente lida com pedidos atrasados. Possui duas ferramentas, e uma delas precisa da aprovação humana porque custa dinheiro:

ORDERS = {
    "A100": {"status": "delayed", "days_late": 6},
    "B200": {"status": "shipped", "days_late": 0},
}

def get_order(order_id):
    return ORDERS.get(order_id, {"error": "order not found"})

def issue_voucher(order_id, amount):
    return {"voucher": f"V-{order_id}", "amount": amount}

TOOLS = {"get_order": get_order, "issue_voucher": issue_voucher}
NEEDS_APPROVAL = {"issue_voucher"}

E aqui está o próprio loop. É um código comum, e todas as regras de segurança residem aqui, e não no modelo:

def run_agent(goal, model, approve, max_steps=5):
    history = []
    for step in range(1, max_steps + 1):
        decision = model(goal, history)
        if "finish" in decision:
            return decision["finish"]

        name, args = decision["tool"], decision["args"]
        if name in NEEDS_APPROVAL and not approve(name, args):
            result = {"denied": True}
        else:
            result = TOOLS[name](**args)

        history.append({"tool": name, "result": result})
    return None   # stopped: step limit reached

Para usar um modelo real, você substituiria a função model por uma chamada a uma API LLM, passando para ela o objetivo, o histórico e as descrições de suas ferramentas. O loop permanece quase o mesmo.

O que aconteceu em nossas corridas

Tentamos cinco situações com a função de decisão com script e registramos cada etapa.

Um pedido atrasado, com voucher aprovado

step 1: get_order({'order_id': 'A100'}) -> {'status': 'delayed', 'days_late': 6}
step 2: issue_voucher({'order_id': 'A100', 'amount': 200}) -> {'voucher': 'V-A100', 'amount': 200}
step 3: finish -> Sorry for the delay. Voucher V-A100 issued.

Cada etapa usou o resultado da anterior. O voucher só foi considerado depois de confirmado o atraso.

A mesma ordem, com aprovação negada

step 2: issue_voucher({'order_id': 'A100', 'amount': 200}) -> {'denied': True}
step 3: finish -> Your order is late. A person will review compensation.

O humano disse não, a ferramenta nunca funcionou e o agente adaptou sua resposta.

Uma ordem desconhecida

step 1: get_order({'order_id': 'Z999'}) -> {'error': 'order not found'}
step 2: finish -> I could not find that order.

Fornecer mensagens de erro claras às ferramentas ajuda. Um modelo real pode lê-los e responder com sensatez, em vez de adivinhar.

Um modelo que fica preso

Também trocamos uma função de decisão defeituosa que repetia a mesma ação para sempre:

step 1: get_order({'order_id': 'B200'}) -> {'status': 'shipped', 'days_late': 0}
step 2: get_order({'order_id': 'B200'}) -> {'status': 'shipped', 'days_late': 0}
step 3: get_order({'order_id': 'B200'}) -> {'status': 'shipped', 'days_late': 0}
stopped: step limit reached

Os agentes realmente podem cair em ciclos como esse, e cada etapa com um modelo real custa dinheiro. Sem max_steps, este nunca teria terminado.

Como funcionam as ferramentas

Esta é a parte mais incompreendida. Um modelo de linguagem não pode executar nada sozinho. Produz texto estruturado dizendo qual ferramenta deseja, com quais argumentos. Seu código decide se deseja executá-lo. É por isso que o loop é o lugar certo para permissões, validação e registro.

Os provedores de modelos oferecem ferramentas ou funções para isso. O Model Context Protocol (MCP) é um padrão aberto para conectar modelos a ferramentas e dados, e nosso artigo sobre Playwright MCP mostra um uso. Escreva nomes e descrições de ferramentas claras, porque o modelo depende delas para escolher corretamente.

Memória

Tarefas longas podem ultrapassar a janela de contexto de um modelo, por isso os sistemas geralmente resumem etapas mais antigas. Os resumos podem perder detalhes, o que é um dos motivos pelos quais os agentes que trabalham há muito tempo podem se desviar do curso.

Sistemas multiagentes

Alguns sistemas dividem o trabalho entre vários agentes especializados, como um planejador, um pesquisador e um revisor. Isso pode ajudar com tarefas grandes que são divididas de maneira organizada. Também adiciona custos, mais maneiras de falhar e depuração mais difícil. Experimente primeiro um único agente com boas ferramentas e divida-o somente quando houver um motivo claro.

Riscos e limites

• Ações erradas. O erro de um chatbot é uma frase ruim. O erro de um agente pode ser um e-mail enviado ou um registro excluído.
• Injeção imediata. Uma página da web ou e-mail que o agente lê pode conter instruções ocultas. Trate todas as saídas da ferramenta como dados não confiáveis, não como comandos.
• Erros compostos. Um pequeno erro no início pode enviar todas as etapas posteriores na direção errada.
• Custo e latência. Cada etapa pode ser outra chamada de modelo, portanto, uma tarefa pode ser muito mais lenta e mais cara do que um único prompt.
• Inconsistência. O mesmo objetivo pode seguir um caminho diferente em cada execução, o que torna os testes mais difíceis.
• Responsabilidade. As pessoas continuam responsáveis ​​pelo que o sistema faz, portanto, mantenha registros.

Guarda-corpos que importam

1. Privilégio mínimo. Dê a cada agente apenas as ferramentas e o acesso necessário.
2. Aprovação humana para qualquer coisa cara, irreversível ou externa, como faz nossa demonstração.
3. Limites rígidos de etapas, tempo e gastos.
4. Valide as entradas da ferramenta no código e não confie nas instruções do modelo.
5. Registre cada etapa para ver por que algo aconteceu. Consulte monitoramento versus observabilidade.
6. Teste com cenários reais, incluindo falhas. Verifique os resultados finais, bem como as respostas individuais. Nosso guia de práticas recomendadas para agentes de IA vai além na implantação.

Quando usar um agente

Os assistentes de codificação são um dos exemplos mais maduros da atualidade, pois podem ler arquivos, executar testes, ver falhas e tentar novamente, com um humano revisando o resultado. Um conjunto de testes dá a eles um sinal claro de sucesso. Nosso guia para engenharia imediata também se aplica à redação de boas instruções para agentes. Comece com a coisa mais simples que poderia funcionar, porque uma única chamada bem solicitada geralmente supera um agente complicado.

Considerações finais

Um agente de IA é menos misterioso do que parece: um modelo, algumas ferramentas e um loop com limites. A parte difícil é a confiança, não o código. Para saber como eles se comportam, pegue nosso pequeno loop, conecte-o a um modelo real com ferramentas somente leitura e observe os logs enquanto ele funciona. Em breve você verá onde ele brilha e onde precisa de um humano.

Perguntas frequentes

Continue aprendendo