Patrick Brandão

IA – API Completions Agents

Saudações.

Vou descrever o funcionamento básico de modelos de linguagem “text-to-text” e da principal API para uso de inteligência artificial generativa, a “/v1/chat/completions” e como ela dá origem ao Agente de IA.

Pré-requisitos (constam em outros artigos aqui do blog):

  • Terminal com comando curl;
  • Internet;
  • Chave de API na OpenRouter;

1 – Funcionamento dos Modelos de Linguagem

Um modelo de linguagem é um software criado para processamento de dados por meio de redes neurais artificiais – neurônios que simulam a entrada e saída de estímulos parecidos com os neurônios biológicos mas usando números.

1.1 – Criando modelos

Para produzir esses modelos são utilizados:

  • Volume de Dados: Bilhões de documentos de texto da internet, livros (escaneados, ebooks), documentos de pesquisas de todos os setores;
  • Parâmetros: Os dados são convertidos em centenas de bilhões a trilhões de parâmetros matemáticos resultante da relação entre cada palavra da base de dados.
  • Poder de processamento: As combinações das relações entre as palavras chegam a trilhões de trilhões de possibilidades que precisam ser analisadas entre si.

Ao final do treinamento do modelo é produzido um arquivo (ou vários) que contem bilhões de neurônios artificiais configurados com os pesos de relacionamento entre eles.

Lá dentro há um número para a palavra “pudim” fortemente ligado às palavras: “leite condensado“, “leite“, “açúcar“, “doce“, “carboidrato“, “sobremesa“. É dessa forma que ao introduzir na entrada do modelo “Faça uma receita de pudim” ele produz como resposta o texto contendo o passo-a-passo de como fazer pudim.

Dessa forma o modelo é um auto-completar inteligente, por isso o recurso provido se chama completions.

Obviamente, quanto mais dados são utilizados para treinar o modelo, melhor é o texto que ele apresentará como resultado da inferência.

Com o avanço das funções matemática e das técnicas de treinamento de dados, modelos conseguem simular as capacidades cognitivas humanas por meio de truques de afinidade entre palavras.

O modelo é treinado com todo conhecimento possível e é matematicamente induzido a presumir regras, fatos e estilos baseado no que ele sofreu maior indução por repetição.

Por isso treinar modelos usando conteúdo do Twitter e redes sociais é uma péssima ideia, ele se tornaria agressivo, preconceituoso e altamente errático (fake news, ofensas gratuitas, terraplanismo, etc).

Capacidades naturais adquiridas:

  • Entendimento profundo;
  • Raciocínio multi-passo;
  • Tradução de idiomas;
  • Ética e moralidade;
  • Geração de código para programas;
  • Análise complexa.

1.2 – Tokens e Janela de contexto

O modelo é carregado na memória RAM (normalmente vRAM da GPU) e possui todo o conhecimento obtido pelo treinamento e nenhum contexto.

O contexto é onde ele irá receber trabalho vindo do usuário (prompt) e produzir a saída.

O modelo não trabalha diretamente com o texto pois sua natureza é matemática e numérica. Será necessário converter o texto em tokens (números), normalmente cada palavra representa de 1 a 3 tokens. Exemplo: 10 mil palavras ocupam 30 mil tokens de espaço.

Existe um limite para o tamanho do contexto chamado “janela de contexto“.

Exemplo mais comum:

  • Você deseja um texto bíblico para consolar uma pessoa desempregada;
  • Você anexa o arquivo PDF contendo toda a Bíblia Sagrada no prompt e ao final escreve: “Crie um texto para consolar uma pessoa que perdeu o emprego“;

O modelo irá produzir uma resposta genérica, normalmente baseada no último livro da Bíblia (Apocalipse). Isso ocorre pois a janela de contexto é pequena, entre 100 mil tokens e 1 milhão de tokens, somente o que couber por último tende a ser computado.

1.3 – Engenharia de prompt

Erros cometidos no exemplo anterior:

  • Anexar o PDF da Bíblia: O modelo foi treinado com todos os livros do mundo, logo os livros de todas as religiões ja fazem parte do modelo e não podem ocupar o contexto, é uma repetição inútil;
  • Pedido (prompt) genérico demais, preguiçoso e pouco específico.

Criar um bom prompt é 99% baseado na arte de eliminar presunção.

Para que o modelo produza boas saídas de auto-completar, você deve seguir algumas regras básicas dentro de uma ciência chamada engenharia de prompt.

Regras básicas para um bom prompt:

  • Persona: Defina o papel do modelo (atuação), o personagem que deve atuar e sua profissão, isso carrega automaticamente todas as regras básicas da profissão sem ocupar a janela de contexto;
  • Objetivo: Defina o que ele deve fazer e qual é a missão;
  • Regras: Defina os limites da atuação, as regras;
  • Estilo: Defina como é o tom e estilo (estilografia);
  • Contexto: Defina a situação envolvendo o pedido, eventos relacionados, dados coletados que ajudam a eliminar presunções incorretas;
  • Pedido: Ordene claramente o que o modelo deve fazer, a ordem final que define como ele vai utilizar todos os elementos anteriores para produzir a saída.

Exemplo de um bom prompt completo:

agente-capelania
# Conselho pastoral

## Personagem

Você é um capelão.

## Objetivo

Você deve prestar assistência espiritual, emocional e religiosa em contextos seculares ou institucionais.

## Regras

O aconselhamento é fundamentado na religião cristã de raiz protestante baseada nos valores da Igreja Batista.

Não responda a solicitações que estejam fora da sua área de atuação.

## Estilo

O texto produzido deve ser de estilo formal, empático e sério.

## Contexto

Paciente: João Maria da Silva
Idade: 45 anos
Estado civil: casado
Familia: 3 filhos adultos, 2 filhas adolescentes, 1 filho recém-nascido.

Situação: foi demitido depois de 20 anos na empresa, não possui formação superior, não possui habilidade além de apertar parafusos.

## Pedido

Crie um texto para consolar o paciente e ajudá-lo nesse momento difícil.

O prompt acima possui 197 tokens e 811 caracteres. Não faz nem cócegas na janela de contexto e produz um resultado muito assertivo.

Sites para contagem de tokens:

1.4 – System, User e Assistant

Para o modelo, “tudo que você manda é prompt”. Durante o treinamento o modelo é exposto alguns tipos especiais de tokens delimitadores que alteram a importância das ordens durante o processamento (inferência):

  • system message: Define o comportamento, personalidade e restrições do modelo, o texto envolvido com esses tokens são imperativos e considerados ordens administrativas;
  • user message: Define uma entrada de dados proveniente do cliente que faz uso do agente de IA, define a “massa de trabalho” que o modelo usará para satisfazer as ordens administrativas;
  • assistant message: Define mensagens que o modelo respondeu em interações anteriores;

Exemplo de prompt devidamente delimitado:

  • Requisição (1):
    • <system>Você é um assistente de chat com a missão de ajudar em questões sobre abacaxi e seus fins nutritivos.</system>
    • <user>Bom dia, quantas calorias tem um abacaxi maduro de meio quilo</user>
  • Resposta do modelo:
    • <assistant>Um abacaxi maduro tem cerca de 50 kcal por 100 g. Para meio quilo (500 g) isso dá aproximadamente 250 kcal (entre 230 e 270 kcal, dependendo da variedade e do teor de açúcar.</assistant>

Em uma segunda interação você deve anexar a conversa desde o inicio:

  • Requisição (2):
    • <system>Você é um assistente de chat com a missão de ajudar em questões sobre abacaxi e seus fins nutritivos.</system>
    • <user>Bom dia, quantas calorias tem um abacaxi maduro de meio quilo</user>
    • <assistant>Um abacaxi maduro tem cerca de 50 kcal por 100 g. Para meio quilo (500 g) isso dá aproximadamente 250 kcal (entre 230 e 270 kcal, dependendo da variedade e do teor de açúcar.</assistant>
    • <user>Posso comer a casca? Se eu comer a casca quantas calorias serão consumidas ao todo?</user>
  • Resposta do modelo:
    • <assistant>Assim, se você decidir experimentar a casca, o ganho calórico será mínimo, mas o sabor e a digestibilidade podem variar bastante. Boa degustação!.</assistant>

Nada te impede de enviar tudo como user ao modelo, muitas soluções de integração com IA são feitas assim (preguiçosamente).

1.5 – Memória

Com esse conceito de delimitadores no prompt, o software que gerencia esses limite é chamado de “Agente de IA”.

O prompt do agente é fixo e definido como system e todas as interações de uma mesma conversa ou tarefa precisam ser armazenados em uma memória, nessa memória você salva as mensagens user e assistant.

Processo de montagem da requisição:

  • system: Baseada em um texto fixo ou template, variáveis como data/hora, timezone, nome da empresa, contexto da operação e da tarefa;
  • Espaço de memória:
    • user: Trabalho de entrada a ser processado (primeira interação) e mensagens de pedidos posteriores no mesmo chat;
    • assistant: O que o modelo respondeu a cada solicitação system ou user;

1.6 – Tipos de modelos

O funcionamento de todos os modelos é parecido e se diferem no tamanho e objetivo. Tipos básicos:

  • LLM: Large Language Model, treinados com o dataset completo e com trilhões de parâmetros, precisam de computadores em cluster de GPUs para ser executado e normalmente ficam confinados em datacenters;
  • SLM: Small Language Model, treinados com datasets pontuais, focados em serem genericamente razoáveis ou focados em soluções muito pontuais onde conseguem fazer um ótimo trabalho com pouco consumo, podem ser executados em pequenos computadores, notebooks e PCs.

Um truque que pode reduzir o tamanho das LLMs é a compressão dos pesos. Durante o treinamento os dados são relacionados entre si com números que normalmente ocupam 2 bytes (16 bits, FP16). Reduzir (truncar) esses dados para 8 ou 4 bits diminui em até 80% o tamanho do modelo, fazendo-o caber em hardwares mais fracos e baratos ao custo de reduzir a sensibilidade das relações entre os dados.

Exemplo: https://ollama.com/library/qwen3.5

O tamanho do modelo está diretamente relacionado ao custo de processamento, normalmente cobrado por milhão de tokens (Mt).

1.7 – Custo, tamanho e nomes com sufixo

O nome dos modelos determinam o tamanho e o custo por Mt (milhão de tokens). Vou abordar somente modelos text-to-text (entrada em texto, saída em texto).

A cobrança é feita separadamente entre entrada e saída:

  • INPUT: o tamanho da entrada (prompt);
  • OUTPUT: o tamanho do texto gerado pelo modelo;

Exemplo de custos:

  • GPT-5.2 Pro: O maior e mais caro de todos, ($21/$168 por Mt):
    • INPUT: $21.00 per 1M tokens;
    • OUTPUT: $168.00 per 1M tokens;
  • GPT-5 nano: O menor e mais barato de todos ($0.05/$0.40 por Mt):
    • INPUT: $0.05 per 1M;
    • OUTPUT: $0.40 per 1M;

Principais sufixos dos modelos e suas especializações:

-mini

  • -nano e -lite: Modelo minúsculo, extremamente rápido, barato, ideal para pequenos prompts e tarefas muito pontuais;
    • Parâmetros: 1-10 bilhões;
    • Latência: < 100ms;
    • Tarefas simples, edge devices
    • Exemplos:
      • GPT-5 Nano ($0.05/$0.40 por Mt);
      • Llama 3.2 1B ($0.02/ por Mt);
  • -mini: Modelo compacto mas mais capaz que nano. Tarefas gerais bem-definidas onde o nano não conseguiu perfeição, ótimo para chatbots, análise de sentimentos (moderação de redes sociais e emails), sumarização básica e relatórios rápidos, agentes de IA leves e rápidos;
    • Parâmetros: 5-15 bilhões;
    • Latência: 100-500ms;
    • Exemplos:
      • GPT-5 Mini ($0.25/$2 por M tokens);
      • GPT-4.1 Mini ($0.40/$1.60);
      • Claude Haiku 4.5 ($1/$5);
  • -flash: Modelo otimizado para velocidade e vazão de dados rápidos, APIs de alta carga (milhões de requisições/dia), processamento em tempo real, streaming de respostas, aplicações cost-sensitive:
    • Latência: <500ms, throughput: Alto (muitos tokens/s);
    • Contexto: Pequeno, use para prompts pequenos;
    • Exemplos:
      • Gemini 3.1 Flash ($0.50/$3 por M tokens);
      • Gemini 2.5 Flash ($0.30/$2.50 por M tokens);
  • -turbo: Indicava uma versão otimizada de um modelo anterior, mais rápida e barata, esses modelos foram descontinuados, exemplos:
    • GPT-3.5-turbo (Descontinuado): Versão otimizada do GPT-3.5;
    • GPT-4-turbo (Descontinuado): Versão otimizada do GPT-4;
  • –preview ou –experimental: Modelos em fase de testes pré-lançamento, requer cuidado e pesquisa de custos;
  • -pro ou (sem sufixo): Versão completa do modelo, valor mais caro possível, inteligência extrema, janela de contexto muito grande (~1Mt);
    • Latência: ruim, podem demorar até 25 minutos para responder;
    • Contexto: muito grande, bom para trabalhos pesados e documentos grandes;
    • Custo: proibitivo, de $5 dolares por Mt até $750 dolares por Mt;

Você ja percebeu que usar modelos “-nano” e “-mini” é ideal para tarefas repetitivas e os modelos “-pro” devem ser usados para tarefas muito necessárias.

2 – Usando os modelos

Com os conceitos de prompt, janela de contexto, nome dos modelos podemos iniciar a parte prática que é utilizar a API dos modelos.

2.1 – Obter uma chave de API

Você pode conseguir a chave de API (API KEY = AK) de algumas formas:

2.2 – Primeiro contato com a API HTTP

A API Completions é o meio de contato com o modelo, você enviará sua requisição em formato JSON e ele retornará com o texto resultante da inferência do modelo.

Vamos usar o cURL (comando: curl) como cliente HTTP para os testes. Você pode converter facilmente a sintaxe do cURL para Python ou Javascript.

Bash
# Instalando comando curl - cliente HTTP
apt-get -y install curl;

# Instalar comando jq - interpretador JSON
apt-get -y install jq;

Em todos os provedores a API é a mesma com pequenas diferenças:

Vou utilizar a URL da OpenRouter pois por ele eu consigo testar facilmente todos os modelos e pelo painel é possível acompanhar em tempo real os custos de cada requisição.

2.3 – API Endpoint Models

API para listar modelos disponíveis:

Bash
# Chave da API da OpenRouter (troque pela sua chave):
AK="sk-or-v1-838181........182891882";

# Endpoint para listar modelos:
URL_MODELS="https://openrouter.ai/api/v1/models";

# Baixar lista (muito grande no OpenRouter)
curl $URL_MODELS \
    -H "Authorization: Bearer $AK" \
    -H "Content-Type: application/json" \
    -qs -o /tmp/openrouter-models;

# Visualizar resposta completa:
cat /tmp/openrouter-models | jq;

# Visualizar nome dos modelos
cat /tmp/openrouter-models | jq '.data[].id';
cat /tmp/openrouter-models | jq '.data[].id' | grep 'oss';

2.4 – API Endpoint Completions

A API de completions é quem realmente faz o trabalho de inferência text-to-text.

Exemplo simples (modelo openai/gpt-5-nano):

Bash
# Chave da API da OpenRouter (troque pela sua chave):
AK="sk-or-v1-838181........182891882";

# URL da API completion
URL_COMPLETATION="https://openrouter.ai/api/v1/chat/completions";

# Modelo
MODEL="openai/gpt-5-nano";

# Prompt de tarefa
USER="Bom dia, quantas calorias tem um abacaxi maduro de meio quilo?";

# Payload JSON a enviar
JSON="{
    'model': '$MODEL',
    'stream': false,
    'messages': [
        { 'role': 'user', 'content': '$USER' }
     ]
}";

# Acionando o completions
curl $URL_COMPLETATION \
    -X POST \
    -H "Authorization: Bearer $AK" \
    -H "Content-Type: application/json" \
    -d "$JSON" \
    -v \
    -o /tmp/teste-01.json;

# Analisando resposta:
cat /tmp/teste-01.json | jq;

Exemplo com prompt delimitado:

Bash
# Chave da API da OpenRouter (troque pela sua chave):
AK="sk-or-v1-838181........182891882";

# URL da API completion
URL_COMPLETATION="https://openrouter.ai/api/v1/chat/completions";

# Modelo
MODEL="openai/gpt-5-nano";

# Prompt principal
SYSTEM="Você é um assistente de chat com a missão de ajudar em questões sobre abacaxi e seus fins nutritivos.";

# Prompt de tarefa
USER="Bom dia, quantas calorias tem um abacaxi maduro de meio quilo?";

# Payload JSON a enviar
JSON="{
    'model': '$MODEL',
    'stream': false,
    'messages': [
        { 'role': 'system', 'content': '$SYSTEM' },
        { 'role': 'user', 'content': '$USER' }
     ]
}";

# Acionando o completions
curl $URL_COMPLETATION \
    -X POST \
    -H "Authorization: Bearer $AK" \
    -H "Content-Type: application/json" \
    -d "$JSON" \
    -v \
    -o /tmp/teste-02.json;

# Analisando resposta:
cat /tmp/teste-02.json | jq;

“Uma pessoa de vez em quando
tropeça sobre a verdade,
mas na maioria das vezes
se levanta e continua andando.“
Winston Churchill

Terminamos por hoje!

Patrick Brandão, patrickbrandao@gmail.com