…
Módulo 1 · Parte A de 3

O Agente

Um agente é uma entidade que interage com um ambiente em qualquer nível significativo. Uma pessoa em seu dia a dia é um agente nesse sentido, assim como um termostato que mantém a temperatura de uma sala ou um carro autônomo que se desloca pelo trânsito.

Todos eles percebem o ambiente por meio de sensores e agem sobre ele por meio de atuadores. Como cada ação alimenta a observação seguinte, percepção e ação formam um ciclo contínuo, o ciclo perceber, raciocinar e agir, que dura enquanto o agente interage. Todos os agentes construídos no curso seguem esse ciclo. O que muda é quanto conseguem perceber e até onde suas ações alcançam.

As três partes do ciclo

Cada iteração passa por três etapas, com nomes simples e funções distintas.

O agente percebe o ambiente por meio de observações e atua sobre ele por meio de ações. A etapa de decisão entre as duas pode mudar.

A percepção reúne o que o agente pode saber, o raciocínio escolhe o que fazer e a ação altera o ambiente. A percepção e a ação costumam vir de um modelo de interação existente, seja ele usado para controlar um aspirador, automação web, uma entidade de jogo ou um humanoide. O raciocínio pode mudar sem alterar essa fronteira, o que separa capacidade de alcance.

Profundo · ConceitosExplorar o ciclo e as arquiteturas clássicas?

Abra esta seção para ver exemplos concretos e uma taxonomia mais completa de arquiteturas.

  • A percepção fornece tudo o que o agente sabe sobre o ambiente. Um termostato lê um único número: a temperatura atual. Um carro autônomo combina câmeras, radar e um mapa em um modelo da via. O agente trabalha somente com o que a percepção captura, pois as etapas seguintes não acessam o mundo diretamente. Uma lacuna na percepção permanece invisível para o restante do agente.
  • O raciocínio transforma uma percepção em uma decisão, e isso varia muito entre agentes. Um termostato compara a temperatura com um alvo e para por aí, enquanto um motor de xadrez busca milhões de jogadas e um carro autônomo executa uma política aprendida. Os agentes que você constrói aqui raciocinam chamando um modelo de linguagem, e quase tudo o que o curso acrescenta depois (ferramentas/memória/planejamento) se apoia nesse único passo.
  • A ação altera o ambiente para o próprio agente e para outros participantes. Pode ser tão pequena quanto acionar um relé ou tão complexa quanto conduzir um carro. Nas páginas seguintes, o código exposto ao modelo recebe o nome de ferramenta, pois, para o modelo, ele representa outra ação disponível. Chamar uma ferramenta significa solicitar que esse código seja executado como ação. O conjunto de ações também define o alcance máximo do agente: por melhor que seja o raciocínio, ele só afeta o mundo por meio das ações permitidas.
A etapa de raciocínio pode ser substituída. Percepção e ação não dependem da função de decisão usada entre elas. Uma regra simples, uma árvore de decisão, uma rotina de busca ou uma rede neural podem conduzir o mesmo ciclo. Manter o ciclo como uma estrutura fixa separa duas perguntas: qual é a capacidade do raciocínio e até onde as ações alcançam?

Os projetos clássicos de agentes diferem na etapa de decisão. O livro Artificial Intelligence: A Modern Approach, de Russell e Norvig, organiza esses projetos em um espectro que vai do agente reflexo a um agente de aprendizagem capaz de melhorar as próprias regras. O curso começa com lógica rígida e depois acrescenta um modelo de linguagem e contexto projetado, aproximando o ciclo de um agente orientado a objetivos e baseado em modelo. Nos módulos seguintes, o ciclo continua sobre um estado que muda, padrão que serve de base para agentes de aprendizagem.

Quatro arquiteturas de agente em ordem crescente de estrutura, de um agente reflexo que mapeia entradas diretamente em ações até um agente de aprendizado que reescreve as próprias regras. Adaptado de Artificial Intelligence: A Modern Approach, de Russell e Norvig ( Artificial Intelligence: A Modern Approach ).
Aplicado · ReflexoExecutar o menor ciclo de agente baseado em regras?

Um agente sem modelo de linguagem

A menor função de decisão é uma única instrução if. Aqui ela conduz uma pista unidimensional limitada por paredes nas posições 0 e 9. Pressione Run e observe a posição alternar entre as paredes enquanto o ciclo é executado.

Duas coisas que vale a pena examinar no código acima:

  • O ambiente (posições das paredes, posição atual) vive em state.env, enquanto as características intrínsecas do agente (sua direção) vivem em state.agent. Mantê-los separados significa que um agente diferente, com estado intrínseco diferente, pode operar no mesmo ambiente sem atrito.
  • O passo de raciocínio é uma única instrução if . Substituí-lo por algo mais poderoso, seja uma árvore de decisão, uma rede neural ou um modelo de linguagem, exige apenas mudar o que está entre a percepção e a ação. A estrutura do laço, a organização do estado e o passo de ação permanecem idênticos.

O que muda quando o raciocínio chama um LLM

Você chama a interface de chat-completions como qualquer outra função: entregue a ela uma lista de mensagens e um nome de modelo, e ela devolve uma mensagem do assistente mais metadados.

Sobre o chat(). É o wrapper fornecido pelo curso que você executa ao vivo um pouco mais adiante nesta página. O trecho abaixo prevê o formato de chamada e os campos que ele retorna, para que os nomes já sejam familiares quando você chegar à célula executável. 
const reply = await chat({
  model:    "nvidia/nemotron-3-nano-30b-a3b",
  messages: [{ role: "user", content: "Hi" }],
});
// reply.choices[0].message  → { content, reasoning_content }
// reply.choices[0].finish_reason → "stop" | "tool_calls" | "length"

Três fatos sobre essa função moldam como os agentes construídos sobre ela precisam funcionar:

Profundo · ConstruçãoComparar onde as APIs mantêm o estado da conversa?

Este curso usa a Chat Completions API o tempo todo: você mantém a conversa como um array messages[] no seu próprio código e reenvia o array completo a cada turno. A mais recente Responses API pode, em vez disso, manter a thread no servidor, de modo que você envia apenas a nova entrada e uma referência ao turno anterior. De qualquer forma, o modelo permanece sem estado e inalterado entre as chamadas. A conversa vive fora dele, em um estado que seu código ou o servidor guarda.

As duas interfaces envolvem a mesma chamada sem estado. Elas diferem apenas em quem guarda a conversa entre os turnos.

Uma chamada de verdade, no seu navegador

A célula abaixo envia uma chat-completion ao modelo. Ela precisa de uma chave de API da NVIDIA, mas o nível gratuito cobre todos os exercícios. Você a insere uma vez, e o curso então a mantém no seu navegador e a reutiliza em todas as páginas, para que você nunca a cole duas vezes.

Pressione Run para enviar uma única requisição. Ela se sustenta inteiramente sozinha, sem nenhum laço em volta e sem carregar nada de um turno anterior.

Profundo · ProtocoloInspecionar a solicitação e a resposta HTTP brutas?

O que o chat() realmente envia

chat() é um wrapper de conveniência em torno de um único POST HTTP comum no formato de transmissão compatível com a OpenAI. Essa requisição carrega três coisas:

  • o endpoint para onde enviar,
  • um cabeçalho Authorization que carrega sua chave,
  • e um corpo JSON com model e messages.

A célula abaixo faz essa chamada manualmente e mostra os dois lados. Abra request para ver o que sai do seu navegador com a chave omitida, e raw response para ver o objeto completo que o chat() devolve.

Todos os endpoints deste curso falam esse mesmo formato, incluindo o runtime do agente OpenClaw no Módulo 3.

Duas coisas que essa chamada faz discretamente, e por quê. Nenhuma é mágica, e vale a pena entender ambas antes de confiar nelas.
  • Sua requisição pode passar por um proxy. Se você selecionou a opção LMS/iframe ao informar a chave, a requisição não segue diretamente para build.nvidia.com. Como esse endpoint não retorna os cabeçalhos de origem cruzada (CORS) exigidos por fetch no navegador, a chamada passa por um proxy que os acrescenta. O proxy também adiciona um cabeçalho de atribuição para identificar o tráfego do curso. A lição envia sua chave nessa requisição sem armazená-la nem substituí-la.
  • O streaming é encapsulado em um helper. chatStream() envia a mesma requisição de chat com streaming ativado e interpreta o fluxo de eventos como texto de resposta, texto de raciocínio, metadados de uso e sinal de término. O helper conecta esses elementos ao painel da lição e ao botão Stop, deixando a célula concentrada no conceito. O código-fonte do helper pode ser aberto pelo menu da célula.
Aplicado · CicloComparar formas de raciocinar sobre o labirinto dentro de um ciclo fixo?

Trocar a função de decisão sem alterar o ciclo

Você agora tem as duas metades de um agente. A função sem estado chat() combina com o ciclo perceber, raciocinar e agir do agente reflexo anterior. Antes de conectar o modelo ao ciclo, observe a etapa de decisão com rotinas que não são modelos de linguagem.

Execute os nós em ordem. Cada um aplica uma regra de decisão diferente ao mesmo ciclo que resolve o labirinto:

  • A regra constante "sempre leste" alcança o objetivo em um corredor reto, depois trava na primeira parede do labirinto, já que um rumo fixo não consegue virar.
  • A busca em profundidade (DFS) segue um ramo até o fim antes de voltar.
  • A busca em largura (BFS) explora a fronteira por níveis e encontra o caminho mais curto em uma grade sem pesos.
  • O A* usa uma heurística de distância para priorizar caminhos promissores sem perder a garantia de menor caminho.
Somente a etapa de decisão varia. DFS, BFS e A* leem o estado atual do labirinto e devolvem um movimento. Uma linha no último nó escolhe a função, enquanto o ciclo abaixo permanece igual para cada opção. A chamada chat() pode ocupar a mesma etapa. Duas bordas mudam: o código representa a percepção como texto e o modelo devolve uma chamada de ferramenta que o código aplica.

Como usar um modelo de linguagem para escolher movimentos

O ciclo ainda amostra o mundo e aplica um movimento validado. Somente a etapa de decisão muda. Em vez de DFS, BFS ou A*, o modelo lê a representação do labirinto e solicita ao código uma chamada de choose_direction.

Execute as células nesta ordem e depois altere um controle por vez:

  1. Comece pelo nó do mecanismo. Ele exporta os utilitários e o resolvedor compartilhado state.runMaze, que percorre corredores automaticamente e chama o modelo somente nas bifurcações.
  2. Execute o nó editável do agente. DIRECTIVE é a instrução central do sistema; o objeto de opções controla modelo, tamanho, mapa textual, imagem, histórico de movimentos, trilha de coordenadas e repetição do schema da ferramenta.
  3. Use primeiro os padrões funcionais. Depois, ative includeImage, troque model para comparar modelos ou defina advanced para ampliar o labirinto.
Um schema transforma a resposta em uma ação tipada. A regra constante devolve uma string; a BFS, uma lista. choose_direction oferece o mesmo contrato ao modelo e o aplica por meio de JSON Schema. Assim, o ciclo lê um valor tipado em vez de interpretar texto livre, e o modelo de linguagem ocupa a etapa de decisão antes usada por BFS e A*.

O ciclo em detalhe

Coloque a chamada chat() dentro do laço que reenvia o histórico, e um único turno de qualquer agente LLM neste curso assume o mesmo formato de quatro estágios. Nomeie os estágios agora, porque toda questão de segurança e confiabilidade mais à frente remete a uma destas quatro setas.

  • Amostrar localmente. Seu código lê uma fatia do ambiente, que pode ser a célula do labirinto e seus movimentos válidos, ou a última mensagem do usuário, ou o conteúdo de um arquivo. Ele nunca tenta abarcar o mundo inteiro de uma vez, porque tudo o que o turno exige é o pedaço estreito de estado que o modelo precisa para agir desta vez.
  • Perceber localmente. Essa fatia é renderizada em um contexto completo e construído: o prompt de sistema, o histórico messages[] em andamento, resultados de ferramentas anteriores e a fatia que você acabou de amostrar. Tudo isso é texto puro. Para um agente LLM, a percepção é engenharia de contexto.
  • Agir localmente. O modelo mapeia esse texto em mais texto: um sinal de intenção, idealmente uma chamada de ferramenta tipada como { "move": "east" } em vez de prosa livre. A intenção apenas solicita uma ação, e nunca executa uma. Seu código a lê e aplica uma atualização limitada ao ambiente (doMove(...)), validando-a primeiro.
  • Impactar localmente. A atualização muda o mundo. Nada permanece dentro do modelo. O estado durável está no ambiente e no contexto que o código reconstruirá. No turno seguinte, a amostragem local lê o mundo alterado e o ciclo recomeça.

Olhe de perto o meio dessa lista. O passo de perceber-a-agir é um único mapeamento texto-para-texto sem estado , no qual um contexto completo e construído entra e um sinal de intenção volta. O modelo apenas transforma texto, então perceber o mundo e transformar uma intenção em uma mudança real continuam sendo trabalho do seu código nos dois lados desse mapeamento.

Isso deixa a caixa verde abaixo como a única parte que você não escreveu. Um agente, portanto, tem apenas duas escolhas: o que você alimenta em seu contexto e o que você faz com a intenção que ele retorna.

amostrar → perceber → (texto → texto) → agir → impactar
Cada passagem do laço age apenas localmente. O modelo lê um pequeno pedaço do mundo, como uma única célula do labirinto, e devolve uma ação limitada antes que o passo texto-para-texto sem estado entre eles esqueça tudo o que acabou de ver. Um agente que realiza muita coisa é apenas esse ciclo modesto repetido muitas vezes, enquanto o ambiente carrega o estado adiante de uma passagem para a próxima. O Módulo 1b constrói esse ciclo em código, onde você pode ver o contexto crescer a cada turno.

Antes de continuar

Cada pergunta pode ser respondida ajustando um controle na célula do labirinto-LLM acima e rodando de novo.

  1. Tire o texto do modelo multimodal. Defina includeText:false e includeImage:true e execute novamente. Agora o modelo vê somente a imagem do labirinto. Ele ainda alcança o objetivo? Precisa de mais decisões do que na execução com texto e imagem?
  2. Remova a dica de estratégia da DIRECTIVE. Exclua a linha que recomenda ramos ainda não visitados e execute a mesma célula. Compare a quantidade de decisões com a execução que continha a dica. Quanto daquela competência veio de uma única frase?
  3. Troque o modelo de decisão. Mude model:"vision" para model:"super" e execute novamente. Ciclo, labirinto, percepção e ação permanecem iguais; somente o modelo muda. O modelo de texto maior alcança o objetivo com menos decisões?

Experimente · o modelo como uma função pura

O menor artefato do curso é uma única chamada chat() sem ferramentas e sem memória ao redor. Cada mensagem que você envia se sustenta sozinha, executando a função pura e sem estado que o laço vai depois envolver. Digite algo abaixo e observe a resposta chegar em streaming.

← Configuração