DEV Community: Lucas

Como Usar GLM-5.2 Sem Restrições

Lucas — Tue, 07 Jul 2026 08:20:47 +0000

GLM-5.2 é um dos poucos modelos de classe de fronteira que você pode executar no seu próprio hardware. Ele é distribuído como pesos abertos sob licença MIT, sem restrições regionais. Na prática, “usar sem restrições” depende de identificar qual limite você está enfrentando: UI do chat, ajuste de instrução, cota de API, roteamento de raciocínio ou infraestrutura.

Experimente o Apidog hoje

Em resumo

GLM-5.2 (Z.ai / Zhipu AI) tem pesos abertos, aproximadamente 753B parâmetros em arquitetura MoE, licença MIT, contexto de 1M de tokens e sem bloqueio regional.
A maioria das “restrições” vem da interface de chat para consumidor ou do ajuste de instrução do modelo, não de um limite rígido da licença.
A API bruta oferece controle de prompt do sistema e permite desativar o thinking.
A auto-hospedagem dá controle total da pilha: prompt, runtime, filtros, logs e limites.
Compilações “abliteradas” da comunidade removem recusas embutidas, como já acontece com DeepSeek R1 e QwQ. A disponibilidade para o GLM-5.2 muda com frequência, então verifique no Hugging Face.
Ao auto-hospedar, moderação e responsabilidade legal passam a ser suas.

1. Identifique qual restrição você quer remover

“Restrição” pode significar coisas diferentes. Antes de trocar de provedor ou baixar pesos, classifique o problema.

Restrição	Onde acontece	Como contornar
Recusas do ajuste de instrução	Nos pesos do modelo de chat	Auto-hospedagem, prompt de sistema mais específico ou build abliterada
Filtros do app de chat	Interface web do consumidor	Usar API bruta
Limites de plano e taxa	Provedor hospedado	Plano pago, outro provedor ou execução local
Latência de raciocínio	Roteamento com `thinking`	Desativar `thinking` quando não for necessário
Controle de política	Camada do provedor/app	Usar endpoint compatível com OpenAI, roteador ou servidor próprio

A região não entra nessa lista porque os pesos do GLM-5.2 são licenciados sob MIT sem restrições regionais. A disponibilidade de APIs hospedadas pode variar por provedor, mas os pesos podem ser auto-hospedados.

2. Use a API bruta em vez do aplicativo de chat

A forma mais rápida de ganhar controle é parar de usar a janela de chat do consumidor e chamar a API diretamente.

Configuração básica:

Base URL: https://api.z.ai/api/paas/v4/
Endpoint: POST /chat/completions
Modelo: glm-5.2

Exemplo mínimo com curl e thinking desativado:

curl https://api.z.ai/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $ZAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.2",
    "thinking": { "type": "disabled" },
    "temperature": 0.7,
    "messages": [
      {
        "role": "system",
        "content": "You are a direct technical assistant. Answer concisely."
      },
      {
        "role": "user",
        "content": "Explain how abliteration changes a model."
      }
    ]
  }'

A mesma chamada usando o SDK Python da OpenAI, redirecionado para z.ai:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_ZAI_KEY",
    base_url="https://api.z.ai/api/paas/v4/",
)

resp = client.chat.completions.create(
    model="glm-5.2",
    temperature=0.7,
    extra_body={
        "thinking": {
            "type": "disabled"
        }
    },
    messages=[
        {
            "role": "system",
            "content": "You are a direct technical assistant. Answer concisely."
        },
        {
            "role": "user",
            "content": "Explain how abliteration changes a model."
        },
    ],
)

print(resp.choices[0].message.content)

O ganho prático aqui vem de dois pontos:

Você controla o system prompt.
Você pode desativar thinking quando quiser uma resposta mais direta e com menor latência.

Para o conjunto completo de parâmetros, consulte o guia da API GLM-5.2.

Os preços mudam, então valide antes de colocar em produção. Na data da escrita original, fontes secundárias listavam cerca de US$ 1,40 por 1M de tokens de entrada e US$ 4,40 por 1M de tokens de saída. Confira os valores atuais na tabela de preços do GLM-5.2. Se custo for a restrição principal, veja também como usar o GLM-5.2 gratuitamente.

3. Auto-hospede os pesos abertos

A resposta mais completa para “sem restrições” é executar o modelo por conta própria.

Como os pesos são licenciados sob MIT, você pode baixar, servir e modificar o GLM-5.2 conforme os termos da licença. Quando o modelo roda na sua infraestrutura:

não há filtro da UI do fornecedor;
não há limite de taxa externo;
o prompt de sistema é seu;
a política de moderação é sua;
logs, armazenamento e observabilidade ficam sob seu controle.

O caminho mais simples para começar é via Ollama:

ollama run glm-5.2

Mas há uma limitação importante: GLM-5.2 é um modelo MoE com aproximadamente 753B parâmetros. O modelo completo exige muita VRAM.

Na prática, você provavelmente vai precisar de uma destas opções:

build quantizada;
máquina multi-GPU alugada;
variante menor do GLM;
pipeline local usando um modelo menor para desenvolvimento.

Se seu hardware for limitado, o GLM-4.7-Flash roda localmente com muito menos recursos e pode servir como substituto durante o desenvolvimento.

Para configurar o ambiente local, consulte o guia geral para executar GLM localmente e o passo a passo de configuração do Ollama.

Depois de servir localmente, o Ollama expõe um endpoint compatível com OpenAI em:

http://localhost:11434/v1

Então o mesmo código da API hospedada funciona mudando apenas a base_url.

Exemplo:

from openai import OpenAI

client = OpenAI(
    api_key="ollama",
    base_url="http://localhost:11434/v1",
)

resp = client.chat.completions.create(
    model="glm-5.2",
    messages=[
        {
            "role": "system",
            "content": "You are a concise technical assistant."
        },
        {
            "role": "user",
            "content": "Summarize the deployment options for GLM-5.2."
        },
    ],
)

print(resp.choices[0].message.content)

4. Use builds da comunidade sem censura, quando disponíveis

As recusas normalmente vêm do ajuste de instrução. A comunidade open source costuma remover esse comportamento com um processo chamado abliteração, que tenta suprimir a direção interna associada à recusa sem exigir retreinamento completo.

A mesma abordagem já é usada em builds sem censura de modelos como:

Como os pesos do GLM-5.2 são abertos e licenciados sob MIT, essa técnica também pode ser aplicada. Porém, uma build abliterada pronta do GLM-5.2 não é garantida. A disponibilidade muda com frequência, então procure uma versão atual no Hugging Face em vez de assumir que ela já existe.

Fluxo típico quando houver uma build disponível:

Baixe os pesos abliterados.
Carregue no Ollama, vLLM ou runtime compatível.
Exponha um endpoint compatível com OpenAI.
Teste prompts críticos antes de conectar ao produto.
Adicione sua própria camada de moderação, se o endpoint for exposto a usuários.

Essa é a forma mais forte de reduzir recusas embutidas, mas também transfere mais responsabilidade para você.

5. Use um provedor ou roteador que permita controlar políticas

Se você não quiser manter sua própria infraestrutura, use um provedor de roteamento como meio termo.

O GLM-5.2 aparece no OpenRouter como:

z-ai/glm-5.2

Ele também está disponível na biblioteca Ollama.

Um roteador permite:

trocar o host subjacente sem reescrever sua aplicação;
manter uma API compatível com OpenAI;
aplicar sua própria configuração de moderação;
evitar filtros específicos da UI de chat do consumidor;
centralizar logs, fallback e controle de custo.

Esse caminho é útil quando você quer mais controle que o app de chat, mas ainda não quer operar GPUs.

Se quiser comparar o GLM-5.2 com outras alternativas abertas, veja o panorama de LLMs sem restrições.

6. Teste cada configuração no Apidog antes de implementar

Qualquer uma das opções acima termina em um endpoint compatível com OpenAI. Antes de colocar em produção, valide o comportamento real do endpoint.

O Apidog ajuda porque permite inspecionar a resposta bruta, inclusive streaming SSE, em vez de ver apenas o texto final.

Passo a passo:

Crie uma nova requisição no Apidog.
Aponte para o endpoint desejado:
- API hospedada: https://api.z.ai/api/paas/v4/chat/completions
- Ollama local: http://localhost:11434/v1/chat/completions
Para a API hospedada, adicione o header:

Authorization: Bearer <key>

Defina o corpo da requisição:

{
  "model": "glm-5.2",
  "stream": true,
  "thinking": {
    "type": "disabled"
  },
  "messages": [
    {
      "role": "system",
      "content": "You are a concise technical assistant."
    },
    {
      "role": "user",
      "content": "Explain the deployment options for GLM-5.2."
    }
  ]
}

Envie a requisição.
Observe o fluxo SSE.
Compare respostas com thinking ativado e desativado.
Verifique o objeto usage para acompanhar consumo de tokens.
Repita com prompts reais do seu produto.

Esse teste evita descobrir em produção que o prompt de sistema não teve o efeito esperado, que o streaming está diferente do previsto ou que a latência aumentou com o raciocínio ativado.

7. Responsabilidade ao remover restrições

Remover filtros de produto e executar pesos sem censura é uma prática legítima em pesquisa, red-teaming e ambientes onde você quer implementar sua própria moderação.

Mas, ao auto-hospedar, você assume:

política de uso;
moderação;
logs;
auditoria;
exposição legal;
segurança do endpoint.

Mantenha três regras práticas:

Você ainda está sujeito à lei e aos termos das plataformas onde implanta.
Se outros usuários acessarem o modelo, adicione uma camada de moderação apropriada.
“Sem restrições” deve significar controle técnico e redução de recusas falsas positivas, não permissão para gerar conteúdo prejudicial ou ilegal.

Perguntas frequentes

O GLM-5.2 é realmente de código aberto?

Os pesos são lançados sob licença MIT, uma das licenças mais permissivas. Você pode executá-los, modificá-los e auto-hospedá-los, inclusive para uso comercial, sujeito aos termos da licença.

Para identidade e especificações do modelo, veja o que é GLM-5.2.

A API do GLM-5.2 censura respostas?

O modelo de instrução possui alinhamento do ajuste, então pode recusar alguns prompts. A API oferece controle de system prompt e permite desativar thinking, o que resolve muitos problemas de tom, latência e recusa excessiva.

Para remover recusas embutidas de forma mais completa, a alternativa é auto-hospedar uma build abliterada, caso exista uma disponível.

Posso executar o GLM-5.2 em um laptop?

Não o modelo completo de aproximadamente 753B parâmetros. Para desenvolvimento local, use uma build quantizada, uma máquina GPU alugada ou uma variante menor, como o GLM-4.7-Flash. Depois, aponte o mesmo código para o modelo maior quando necessário.

O GLM-5.2 possui bloqueio regional?

Não. Os pesos são licenciados sob MIT sem restrições regionais. A disponibilidade da API hospedada pode variar por provedor, mas a auto-hospedagem está aberta a qualquer pessoa.

Karate para Testes de API: Guia Prático da DSL

Lucas — Tue, 07 Jul 2026 07:50:56 +0000

Você quer testes de API legíveis, versionados no Git junto com o código e executáveis em qualquer pipeline de CI. O Karate atende bem esse caso: ele usa uma DSL baseada em Gherkin para escrever cenários Dado / Quando / Então, sem exigir glue code em Java para testes HTTP comuns. Neste guia, você verá como estruturar arquivos .feature, configurar ambientes, escrever asserções JSON e rodar tudo em CI.

Experimente o Apidog hoje

O que é o Karate

Karate é um framework open source de automação de testes de API baseado em Java. Você escreve testes em arquivos .feature, usando a sintaxe Gherkin do Behavior-Driven Development, mas sem precisar implementar definições de steps como no Cucumber.

Um teste HTTP básico no Karate já vem com suporte nativo para:

montar requisições;
enviar métodos HTTP;
validar status codes;
comparar JSON;
usar matchers flexíveis como #string, #number e #[10];
executar testes por Maven, Gradle, JUnit 5 ou jar standalone.

Além de testes de API, o projeto também inclui recursos para mocks, testes de performance com Gatling e automação de UI. Aqui, o foco é o núcleo de testes de API.

Como os testes são arquivos de texto, eles funcionam bem em um workflow baseado em código, nativo do Git. Um pull request mostra exatamente quais cenários, payloads ou asserções foram alterados.

Se você ainda não usa o estilo Dado / Quando / Então, veja também o guia sobre Behavior-Driven Development.

Como funciona: arquivos `.feature` e `karate-config.js`

Um teste Karate começa com um arquivo .feature. Cada arquivo possui uma Funcionalidade: e um ou mais Cenário:.

Exemplo mínimo:

Funcionalidade: API de Usuário

Cenário: Listar todos os usuários
  Dado url 'https://jsonplaceholder.typicode.com'
  E caminho 'users'
  Quando método get
  Então status 200
  E match response == '#[10]'

O fluxo é direto:

url define a base da API.
caminho adiciona o recurso.
método get envia a requisição.
status 200 valida o HTTP status.
match response == '#[10]' verifica que a resposta é um array com 10 itens.

O marcador #[10] é próprio do Karate. Ele valida o tamanho do array sem exigir código JavaScript.

Para entender melhor a sintaxe Gherkin aplicada a APIs, consulte o guia Gherkin para BDD e testes de API.

Configurando ambientes com `karate-config.js`

Em projetos reais, você normalmente precisa alternar entre ambientes como dev, qa, staging e prod. O Karate centraliza isso no arquivo karate-config.js.

Crie um arquivo assim na raiz dos testes:

function fn() {
  var env = karate.env || 'dev';

  var config = {
    baseUrl: 'https://jsonplaceholder.typicode.com'
  };

  if (env === 'qa') {
    config.baseUrl = 'https://qa.example.com';
  }

  return config;
}

Agora, no arquivo .feature, use a variável baseUrl:

Funcionalidade: API de Usuário

Background:
  * url baseUrl

Cenário: Listar usuários
  Dado caminho 'users'
  Quando método get
  Então status 200

Para trocar o ambiente em tempo de execução:

java -jar karate.jar -Dkarate.env=qa src/test/java/features

Assim, você evita hardcode de URLs nos cenários.

Exemplo prático: criando um usuário

Este cenário envia um payload JSON, valida o status code e verifica a forma da resposta:

Funcionalidade: Criar usuário

Background:
  * url baseUrl

Cenário: Criar um novo usuário retorna 201
  Dado caminho 'users'
  E requisição { name: 'Ada', job: 'engineer' }
  Quando método post
  Então status 201
  E match response.name == 'Ada'
  E match response.id == '#string'

Pontos importantes:

Background: roda antes de cada cenário do arquivo.
* é um step curinga, útil para configuração.
requisição recebe JSON diretamente.
#string valida que id existe e é uma string, sem fixar um valor específico.

Esse estilo reduz boilerplate: não há DTO, POJO, serializer ou código de setup HTTP.

Asserções e comparação de JSON

A principal palavra-chave para validação no Karate é match.

Comparação exata

E match response == { id: '#number', name: 'Ada', job: 'engineer' }

Aqui, o objeto precisa ter os campos esperados. Os matchers flexíveis validam tipos:

#number: número;
#string: string;
#boolean: booleano;
#uuid: UUID.

Isso é útil para campos gerados dinamicamente, como IDs e timestamps.

Comparação parcial com `contains`

Quando você só precisa validar parte da resposta:

E match response contains { name: 'Ada' }

O teste passa mesmo que a resposta tenha outros campos.

O Karate também suporta:

E match response !contains { error: true }
E match response contains only { name: 'Ada', job: 'engineer' }
E match response contains any [{ name: 'Ada' }, { name: 'Grace' }]
E match response contains deep { user: { name: 'Ada' } }

Validação de arrays

Para validar o tamanho de um array:

E match response == '#[10]'

Para validar cada item do array:

E match each response == { id: '#number', name: '#string' }

Essa linha verifica que todos os objetos retornados possuem id numérico e name string.

Para mais padrões de validação, veja o guia prático de asserções de API.

Testes orientados a dados

Para executar o mesmo cenário com múltiplas entradas, use Cenário com Estrutura e Exemplos.

Funcionalidade: Criar usuários

Cenário com Estrutura: Criar usuários a partir de uma tabela
  Dado url baseUrl
  E caminho 'users'
  E requisição { name: '<name>', job: '<job>' }
  Quando método post
  Então status 201
  E match response.name == '<name>'

  Exemplos:
    | name  | job        |
    | Ada   | engenheira |
    | Grace | cientista  |
    | Alan  | analista   |

O Karate executa o cenário uma vez para cada linha da tabela.

Para manter dados grandes fora do .feature, leia um arquivo externo:

Exemplos:
  | read('classpath:test-data/users.json') |

O Karate suporta JSON e CSV para esse tipo de execução orientada a dados.

Rodando Karate em CI

Você tem duas opções comuns para executar Karate em pipelines.

Opção 1: Maven, Gradle e JUnit 5

Em projetos Java, adicione a dependência karate-junit5 e crie um runner apontando para os arquivos .feature.

A vantagem é que seu pipeline continua simples:

mvn test

ou:

gradle test

Isso encaixa os testes de API no mesmo fluxo dos testes automatizados existentes.

Opção 2: jar standalone

Se você não quer usar Maven ou Gradle, baixe o karate.jar nos releases do projeto e execute os testes diretamente:

java -jar karate.jar src/test/java/features

Para filtrar por tags, executar em paralelo e definir diretório de saída:

java -jar karate.jar --tags @smoke --threads 4 --output reports src/test/java/features

Para passar o ambiente:

java -jar karate.jar -Dkarate.env=qa src/test/java/features

Após a execução, o Karate gera um relatório HTML no diretório de saída, útil como artefato de CI.

Para uma visão mais ampla sobre pipelines, veja como automatizar testes de API em CI/CD.

Pontos fortes e compensações

O Karate funciona bem quando você quer:

testes versionados no Git;
cenários legíveis;
validação JSON com pouco boilerplate;
execução headless em CI;
uma abordagem code-first para testes de API.

As principais compensações:

exige Java instalado;
a DSL precisa ser aprendida;
reutilização avançada pode exigir JavaScript ou interoperabilidade Java;
pessoas não desenvolvedoras podem ter dificuldade para criar e manter cenários.

Ou seja: o Karate é forte para times que tratam testes como código e querem manter a suíte próxima da aplicação.

Karate vs uma abordagem sem código com Apidog

O Karate é baseado em código: você escreve arquivos .feature, versiona no Git e executa por build tool ou jar.

O Apidog segue uma abordagem visual e sem código. Você cria cenários na UI, encadeia requisições e adiciona asserções por configuração, sem escrever DSL.

Como o ciclo de vida da API fica no mesmo lugar — design, depuração, mocking, documentação e testes — os testes podem reutilizar endpoints e esquemas já definidos. Isso reduz a barreira para QA, produto e outras pessoas que não querem manter um projeto Java.

As suítes visuais também podem rodar em CI com o Apidog CLI.

Instale com Node:

npm install -g apidog-cli

Execute um cenário ou suíte salvo por ID:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioOrSuiteId> -e <environmentId> -r cli,html,junit

Principais flags:

-t: cenário, pasta ou suíte;
-e: ambiente;
-r: reportadores, como cli, html, json e junit;
-d ou --iteration-data: arquivo ou ID de dados de teste para execução orientada a dados.

O Apidog CLI é headless e roda em qualquer CI com Node. Ele executa cenários salvos no Apidog; não é um remetente interativo de requisições nem um gerador de carga.

Veja mais em Apidog CLI para CI/CD e na comparação Apidog CLI vs Newman.

A diferença principal é o estilo de autoria:

Karate: DSL em arquivos versionados no Git.
Apidog: criação visual com execução headless em pipeline.

Como escolher

Escolha Karate se:

seu time é majoritariamente desenvolvedor;
vocês já usam Java/JVM;
testes devem viver no Git junto com o código;
a equipe quer controle detalhado por DSL;
a suíte será mantida como código.

Escolha uma ferramenta sem código como o Apidog se:

QA e produto também precisam criar ou editar testes;
você quer conectar testes com design e documentação de API;
prefere evitar um projeto Java só para validar APIs;
precisa manter execução em CI via CLI.

Algumas equipes usam os dois: Karate para regressões profundas mantidas por engenharia e uma ferramenta visual para cobertura ampla que mais pessoas conseguem estender.

Se você ainda está comparando opções, veja como escolher um framework de teste de automação de API.

Perguntas frequentes

Preciso saber Java para usar o Karate?

Não para escrever testes básicos de API. Os arquivos .feature usam a DSL do Karate com sintaxe Gherkin. Você precisa ter Java instalado para executar os testes, e conhecimento de Java ou JavaScript ajuda em helpers e reutilização avançada.

Qual é a diferença entre Karate e Cucumber?

Ambos usam Dado / Quando / Então. No Cucumber, você normalmente implementa o código das definições de steps. No Karate, os steps HTTP e asserções já vêm prontos para testes de API.

O Karate pode rodar sem Maven ou Gradle?

Sim. Use o karate.jar standalone:

java -jar karate.jar <caminho>

Ele suporta tags, paralelismo e diretório de saída personalizado.

O que significam #string, #number e #[10]?

São matchers flexíveis do Karate. #string valida uma string, #number valida um número e #[10] valida um array com 10 itens.

Testes de API sem código ainda podem rodar em CI?

Sim. Uma ferramenta visual como o Apidog pode executar cenários salvos via Apidog CLI em qualquer pipeline com Node. Assim, você cria os testes na UI e mantém execução automatizada em CI.

Testes de Regressão de API: Como Identificar Erros Críticos Antecipadamente

Lucas — Tue, 07 Jul 2026 07:37:31 +0000

Você envia uma pequena alteração para um endpoint. O código compila, o recurso funciona e você implanta. Dois dias depois, um cliente móvel começa a travar porque um campo que antes era string agora é um objeto. A mudança parecia local. Não era.

Experimente o Apidog hoje

Teste de regressão de API serve para detectar esse tipo de quebra antes que ela chegue aos consumidores. A ideia é simples: você salva um conjunto de requisições e asserções que representam o comportamento atual da API e executa esse conjunto a cada alteração. Se um código de status, formato de resposta, campo obrigatório ou valor contratual mudar, o teste falha e aponta onde ocorreu a regressão.

O que é teste de regressão de API

Teste de regressão significa reexecutar testes que já passaram para confirmar que o comportamento existente continua válido após uma alteração.

Em APIs, esse comportamento é o contrato HTTP usado pelos consumidores:

Rotas disponíveis
Métodos HTTP
Códigos de status
Estrutura da resposta
Tipos dos campos
Campos obrigatórios
Valores com significado contratual

APIs regridem por motivos comuns:

Um campo JSON é renomeado
Um 200 vira 204
Uma validação nova rejeita entradas antes aceitas
Uma atualização de ORM muda o formato de datas
Uma dependência altera mensagens de erro
Um campo obrigatório deixa de ser retornado

Essas quebras raramente aparecem como erro de compilação. Elas aparecem como integrações quebradas.

O foco do teste de regressão de API não é testar todo o sistema. É proteger a superfície HTTP à qual outros sistemas se acoplam.

O que usar como baseline

O baseline é o comportamento esperado que será comparado nas próximas execuções.

Ele deve cobrir o que quebraria um consumidor real, sem travar o teste em dados voláteis.

Use estas quatro camadas como referência.

1. Códigos de status

Cada endpoint deve retornar um status conhecido para entradas conhecidas.

Exemplos de regressão:

POST /users retornava 201 e passou a retornar 200
GET /users/42 retornava 200 e passou a retornar 500
DELETE /users/42 retornava 204 e passou a retornar 404

2. Esquema de resposta

Valide estrutura e tipos:

{
  "id": 42,
  "email": "alice@example.com",
  "status": "active",
  "roles": ["admin"]
}

Asserções úteis:

body.id é number
body.email é string
body.status é string
body.roles é array

Mudanças como estas devem falhar:

- "email": "alice@example.com"
+ "email": { "value": "alice@example.com" }

3. Campos-chave

Não valide todos os valores. Valide os que têm significado contratual.

Bons candidatos:

id deve existir
status deve estar em um enum conhecido
total deve ser número
email deve ter formato de e-mail
items deve ser array

Exemplo:

body.status é um de ["active", "pending", "suspended"]

4. Contrato OpenAPI

Compare a resposta real com a especificação OpenAPI.

Se a especificação diz que email é obrigatório e a API deixa de retorná-lo, isso deve falhar.

Para aprofundar essa abordagem, veja teste de contrato de API.

Exemplo de baseline para um endpoint

Um baseline mínimo para GET /v1/users/42 poderia ser:

GET /v1/users/42 -> 200

Asserções:
- body.id está presente
- body.id é number
- body.email está presente
- body.email é string
- body.email corresponde ao formato de e-mail
- body.status é um de ["active", "pending", "suspended"]
- body.roles é array
- response time < 800 ms

Essas verificações protegem o contrato sem depender de valores dinâmicos.

Evite isto:

body.createdAt == "2026-01-01T10:00:00Z"

Prefira isto:

body.createdAt é string
body.createdAt segue formato ISO 8601

Para mais exemplos de verificações em respostas, veja asserções de API.

Teste manual vs. automatizado

Você pode testar regressão manualmente: abrir um cliente de API, reenviar requisições salvas e inspecionar respostas.

Isso funciona para poucos endpoints. Depois, quebra por três motivos:

Pessoas esquecem de executar os testes
Casos repetitivos são ignorados
O teste não roda automaticamente em pull requests, merges ou deploys

Automatizar remove essa decisão humana. O conjunto roda sempre.

Critério	Manual	Automatizado
Executa em cada alteração	Não, depende da disciplina	Sim
Cobertura	Poucos endpoints	Conjunto completo
Custo por execução	Tempo humano	Computação
Roda de madrugada	Não	Sim
Esforço inicial	Baixo	Moderado

Para qualquer API usada por clientes, apps móveis, parceiros ou outros serviços, automatize.

Como construir um conjunto de regressão reutilizável

Um conjunto de regressão é um grupo de requisições salvas com asserções.

A meta é:

Criar uma vez
Executar sempre
Estender quando novos endpoints ou bugs aparecerem

1. Agrupe por recurso

Organize por área da API:

/users
/orders
/payments
/auth

Exemplo:

Regression Suite
├── Users
│   ├── GET /users/{id}
│   ├── POST /users
│   └── PATCH /users/{id}
├── Orders
│   ├── GET /orders/{id}
│   └── POST /orders
└── Auth
    └── POST /login

Isso facilita identificar qual grupo observar quando um serviço muda.

2. Use variáveis de ambiente

Não codifique valores como URL base, tokens ou IDs fixos em cada requisição.

Use variáveis:

{{baseUrl}}
{{accessToken}}
{{tenantId}}
{{userId}}

Exemplo de ambientes:

local:
  baseUrl = http://localhost:3000

staging:
  baseUrl = https://staging.api.example.com

production:
  baseUrl = https://api.example.com

Assim, o mesmo conjunto roda em local, staging ou produção mudando apenas o ambiente.

3. Encadeie requisições

Fluxos reais normalmente dependem de respostas anteriores.

Exemplo CRUD:

POST /users
  extrai body.id como userId

GET /users/{{userId}}
  valida dados criados

PATCH /users/{{userId}}
  atualiza status

DELETE /users/{{userId}}
  remove recurso

Esse tipo de fluxo detecta regressões que não aparecem em testes isolados.

Essa prática se aproxima do teste de integração de API, porque valida a sequência entre endpoints.

4. Use dados para cobrir casos de borda

Em vez de criar várias requisições quase iguais, use uma tabela de dados.

Exemplo CSV:

email,expectedStatus
alice@example.com,201
bob@test.co,201
not-an-email,422
,422
a@b,422

A mesma requisição roda cinco vezes, cada uma com entrada e status esperado diferentes.

Exemplo de lógica do teste:

POST /users
body.email = {{email}}

Asserção:
response.status == {{expectedStatus}}

Adicione uma nova linha quando encontrar um novo caso de borda. Você aumenta cobertura sem duplicar requisições.

5. Mantenha o conjunto rápido

Um conjunto lento será ignorado.

Boas práticas:

Rode apenas o conjunto principal em pull requests
Deixe fluxos longos para execução noturna
Simule serviços externos lentos
Evite dependência de dados instáveis
Paralelize requisições independentes quando a ferramenta permitir

Um bom objetivo para PRs é manter o conjunto principal em poucos minutos.

Como executar o conjunto na CI

Um conjunto salvo apenas no seu laptop não protege o repositório.

Execute os testes nos eventos que podem introduzir regressões:

Pull requests
Merges no branch principal
Deploys para staging
Deploys para produção, quando aplicável

O padrão é:

Instalar um runner headless
Apontar para o conjunto salvo
Executar contra um ambiente
Fazer a build falhar se alguma asserção falhar
Publicar relatório

O Apidog fornece o apidog-cli para isso.

Instale com Node:

npm install -g apidog-cli

Execute um cenário, pasta ou conjunto salvo pelo ID:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  -r cli,html,junit

Parâmetros:

--access-token: autentica a execução. Armazene como segredo da CI.
-t: ID do cenário, pasta ou conjunto.
-e: ID do ambiente.
-r: formatos de relatório.

Formatos comuns:

cli    imprime resultado no console
html   gera relatório legível
junit  gera XML para a CI exibir testes aprovados/falhos

Exemplo com GitHub Actions

name: API Regression

on: [pull_request]

jobs:
  regression:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v6

      - uses: actions/setup-node@v6
        with:
          node-version: '22'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API regression suite
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 123456 \
            -e 789012 \
            -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Se uma asserção falhar, o runner retorna código diferente de zero e o job fica vermelho. O pull request deve ser bloqueado até a regressão ser corrigida ou explicitamente aceita.

Para exemplos completos de pipeline, veja Apidog CLI para CI/CD e como automatizar testes de API no GitHub Actions.

Executando com arquivo de dados

Se o cenário usa dados externos, passe o arquivo com -d:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  -d ./test-data/emails.csv \
  -r cli,junit

Exemplo de estrutura:

test-data/
└── emails.csv

Com isso, uma única requisição pode ser executada várias vezes com entradas diferentes.

Executando testes de um branch específico

Se você mantém versões diferentes do conjunto em branches, use --branch:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  --branch feature/new-user-api \
  -r cli,junit

Para manter histórico de execuções na nuvem, adicione:

--upload-report

Exemplo:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 123456 \
  -e 789012 \
  -r cli,junit \
  --upload-report

Use diferenciação de esquema para detectar quebras antes do deploy

Asserções detectam regressões na API em execução. A diferenciação de esquema detecta regressões na especificação.

O fluxo é:

A especificação OpenAPI fica versionada no repositório
Um pull request altera a especificação
A CI compara a nova versão com a anterior
Mudanças são classificadas como seguras ou incompatíveis

Exemplos de mudanças normalmente seguras:

Adicionar campo opcional
Adicionar novo endpoint
Adicionar novo valor opcional

Exemplos de mudanças incompatíveis:

Remover campo
Renomear campo
Alterar tipo de string para object
Tornar campo opcional obrigatório
Remover valor de enum
Alterar código de status esperado

A diferenciação ajuda o revisor a ver algo como:

Breaking change: removed response property user.phone

em vez de revisar manualmente uma parede de YAML.

Combine isso com testes de contrato contra a API ao vivo:

A especificação diz o que deve acontecer
A API real é validada contra essa especificação
Se código e contrato divergirem, o teste falha

Mudanças incompatíveis nem sempre são bugs. Às vezes são intencionais. O ponto é torná-las explícitas e passar por versionamento, comunicação e descontinuação.

Para esse processo, veja como versionar e descontinuar APIs em escala.

Como o Apidog ajuda nesse fluxo

O Apidog reúne design de API, cenários de teste, asserções e execução headless em CI.

Na prática, você pode:

Criar cenários visualmente
Encadear requisições
Extrair valores de uma resposta para a próxima
Adicionar asserções de status, esquema e campos
Validar respostas contra o esquema salvo do endpoint
Executar cenários com dados CSV ou JSON
Rodar tudo na CI com apidog-cli

Exemplo de fluxo:

POST /users
  salva body.id em userId

GET /users/{{userId}}
  valida status 200
  valida body.id
  valida body.email
  valida schema

PATCH /users/{{userId}}
  valida status 200
  valida body.status

DELETE /users/{{userId}}
  valida status 204

O apidog-cli não é um cliente interativo nem um gerador de carga. Ele tem um escopo específico: reproduzir conjuntos salvos de forma headless e reportar o resultado.

Para um fluxo scriptado completo, veja o guia de pipeline de CI/CD do Apidog CLI.

Fluxo inicial para implementar esta semana

Use este plano se você ainda não tem regressão automatizada de API.

1. Escolha os cinco endpoints mais chamados

Comece pelos endpoints com maior impacto:

GET /users/{id}
POST /login
GET /orders/{id}
POST /orders
GET /me

O risco costuma estar onde há mais tráfego e mais consumidores.

2. Crie uma requisição salva por endpoint

Para cada endpoint, adicione pelo menos:

- Código de status esperado
- Validação de esquema
- Dois ou três campos-chave

Exemplo:

GET /orders/{{orderId}}

Asserções:
- status == 200
- body.id é string
- body.total é number
- body.status é um de ["created", "paid", "cancelled"]
- body.items é array

3. Adicione um fluxo encadeado

Escolha o recurso principal e teste o ciclo completo:

Criar -> Ler -> Atualizar -> Excluir

Exemplo:

POST /products
GET /products/{{productId}}
PATCH /products/{{productId}}
DELETE /products/{{productId}}

4. Adicione teste orientado a dados

Escolha um endpoint com validação forte, como cadastro ou pagamento.

Exemplo:

name,email,expectedStatus
Alice,alice@example.com,201
Bob,bob@test.co,201
Invalid,not-an-email,422
Empty,,422

5. Conecte à CI

Adicione um job que:

- instala apidog-cli
- executa o conjunto
- gera relatório JUnit
- falha o pull request se houver regressão

6. Transforme bugs escapados em testes

Quando uma regressão chegar à produção:

Corrija o bug
Reproduza o caso no conjunto de regressão
Adicione uma asserção
Garanta que o mesmo bug não escape novamente

Esse é o ciclo que torna o conjunto mais forte com o tempo.

FAQ

Como o teste de regressão de API difere do teste de regressão geral?

Teste de regressão geral verifica o comportamento do sistema como um todo, incluindo UI, lógica de negócio e integrações internas.

Teste de regressão de API foca na superfície HTTP:

Rotas
Métodos
Códigos de status
Esquemas de resposta
Campos obrigatórios
Valores contratuais

Esse foco mantém o conjunto rápido o suficiente para rodar em cada pull request.

Com que frequência devo executar o conjunto?

Execute em toda alteração que possa afetar a API.

Na prática:

Em cada pull request
Em cada merge no branch principal
Antes de deploys importantes

Mantenha um conjunto rápido para PRs e deixe fluxos longos para execuções noturnas.

O que devo afirmar para evitar testes frágeis?

Afirme o que quebraria um consumidor.

Boas asserções:

status == 200
body.id existe
body.id é string
body.status está em enum conhecido
body.createdAt segue formato ISO 8601

Evite travar valores voláteis:

body.createdAt == "2026-01-01T10:00:00Z"
response.time == 132 ms

Prefira validar tipo, formato e limites.

Posso executar regressão de API sem escrever código?

Sim. Ferramentas como o Apidog permitem criar cenários e asserções visualmente. Depois, o apidog-cli executa esses cenários na CI sem exigir um harness de teste escrito à mão.

Como lidar com mudanças intencionais que quebram compatibilidade?

Não trate como surpresa.

Use um processo explícito:

Detecte a quebra via diff de esquema
Revise a mudança no pull request
Versione o endpoint se necessário
Comunique consumidores
Deprecie o comportamento antigo
Atualize o baseline deliberadamente

O objetivo não é impedir toda mudança. É impedir que mudanças incompatíveis cheguem aos consumidores sem controle.

O que é Flowise? O construtor low-code de código aberto para apps LLM e agentes de IA

Lucas — Tue, 07 Jul 2026 04:19:09 +0000

Se você quer criar um aplicativo LLM ou um agente de IA sem conectar cada componente manualmente em Python, o Flowise oferece uma alternativa visual e low-code. Você monta nós, conecta entradas e saídas, testa o fluxo na própria interface e publica um endpoint REST para consumir no seu app. Neste guia, você verá o que é o Flowise, quando usar chatflows, agentflows ou assistentes, como executar localmente, como chamar o endpoint de previsão e como testar esse contrato de API. Se você já leu nossa explicação sobre LangGraph, pense no Flowise como o lado visual-first do espectro. O código-fonte está no README do projeto no GitHub.

Experimente o Apidog hoje

O que é o Flowise

Flowise é uma plataforma open source para construir agentes de IA e fluxos de trabalho com LLMs. Ele é distribuído sob a licença Apache 2.0, então você pode executá-lo localmente, hospedá-lo por conta própria ou fazer um fork.

A ideia central é uma tela baseada em nós. Cada nó representa um bloco de construção:

modelo de chat;
armazenamento de vetores;
carregador de documentos;
memória;
retriever;
ferramenta externa;
lógica personalizada.

Você arrasta os nós para a tela, conecta as saídas às entradas e define como os dados fluem. Quando o fluxo está pronto, o Flowise o expõe como uma API REST que pode ser chamada por qualquer frontend, backend ou serviço interno.

Nos bastidores, o Flowise conecta componentes de frameworks como LangChain e LlamaIndex. Se você já trabalhou com cadeias, agentes, retrievers, vector stores ou query engines, os conceitos serão familiares. A diferença é a forma de montagem: em vez de importar classes e escrever a orquestração em código, você compõe o fluxo visualmente.

A troca é clara:

você ganha velocidade, legibilidade e colaboração visual;
você perde parte do controle granular de uma implementação code-first.

Chatflows, agentflows e assistentes

Flowise oferece três tipos principais de construtores. Escolher o tipo certo evita complexidade desnecessária.

Tipo de construtor	Melhor para	Escopo
Assistente	Iniciantes; assistentes de chat que seguem instruções, usam ferramentas e fazem RAG sobre arquivos enviados	Mais restrito, mais guiado
Chatflow	Sistemas de agente único, chatbots, fluxos LLM mais simples; suporta Graph RAG e rerankers	Agente único
Agentflow	Sistemas multiagente e orquestração complexa com ramificação, looping e roteamento	Mais amplo; um superconjunto de Chatflow e Assistente

Quando usar um chatflow

Use um chatflow quando você precisa de um pipeline direto:

receber uma pergunta;
recuperar contexto;
chamar um modelo;
retornar uma resposta.

Esse formato funciona bem para:

chatbots de suporte;
assistentes internos;
RAG sobre documentação;
fluxos LLM com um único agente.

Quando usar um agentflow

Use um agentflow quando o fluxo precisa coordenar múltiplos passos ou agentes.

Exemplos:

um agente classifica a intenção e outro executa a tarefa;
o fluxo roteia perguntas para diferentes ferramentas;
há ramificações condicionais;
o workflow precisa repetir etapas até alcançar um critério;
múltiplos agentes passam trabalho uns para os outros.

O agentflow é a camada indicada para orquestração mais complexa.

Quando usar um assistente

Use um assistente quando você quer sair do zero rapidamente.

Você define instruções, adiciona ferramentas e aponta arquivos para recuperação. É a opção mais guiada e com menos decisões de arquitetura.

Como montar um fluxo no Flowise

A construção no Flowise segue um padrão simples.

Crie um novo chatflow.
Arraste um nó de modelo de chat para a tela.
Escolha um provedor, como OpenAI, Anthropic ou um modelo local.
Se precisar de RAG, adicione um carregador de documentos.
Adicione um armazenamento de vetores.
Conecte o carregador ao vector store.
Adicione um retriever para buscar contexto.
Conecte o contexto ao modelo.
Se precisar manter histórico, adicione um nó de memória.
Salve o fluxo.
Abra o painel de chat e teste uma pergunta real.

Um fluxo RAG básico pode seguir esta estrutura:

Pergunta do usuário
        |
        v
Retriever -> Contexto recuperado
        |
        v
Modelo de chat
        |
        v
Resposta

O editor visual também suporta:

expressões;
nós de código personalizados;
ramificação;
looping;
roteamento;
lógica condicional.

Quando um nó pronto não cobre seu caso, você pode criar uma função personalizada e manter o restante do fluxo visual.

Implantando o Flowise

O Flowise roda como uma aplicação Node.js e usa a porta 3000 por padrão.

Rodando com npm

Para testar localmente:

npm install -g flowise
npx flowise start

Depois, abra:

http://localhost:3000

Rodando com Docker

Para uma execução mais repetível:

docker run -d --name flowise -p 3000:3000 flowiseai/flowise

Verifique se o container está rodando:

docker ps

Acesse:

http://localhost:3000

O Flowise também suporta implantações auto-hospedadas e air-gapped, úteis quando seus dados não podem sair da sua rede.

Chamando o endpoint de previsão REST

Depois que um fluxo é salvo, o Flowise expõe uma API REST para ele. A documentação oficial de previsão cobre o formato completo da requisição.

Cada chatflow ou agentflow recebe um endpoint neste formato:

POST /api/v1/prediction/{id}

O {id} é o ID do fluxo.

Uma chamada mínima com curl:

curl -X POST http://localhost:3000/api/v1/prediction/<flow-id> \
  -H "Content-Type: application/json" \
  -d '{"question": "Qual é o horário de funcionamento da sua loja?"}'

O campo principal é question, mas o corpo pode incluir outros parâmetros, dependendo do fluxo.

Exemplo com configurações adicionais:

curl -X POST http://localhost:3000/api/v1/prediction/<flow-id> \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Resuma a política de reembolso.",
    "overrideConfig": {
      "temperature": 0.2
    },
    "history": [
      {
        "role": "user",
        "content": "Você pode me ajudar com dúvidas da loja?"
      },
      {
        "role": "assistant",
        "content": "Sim, posso ajudar."
      }
    ]
  }'

O corpo da requisição pode suportar:

question: pergunta enviada ao fluxo;
streaming: habilita transmissão de tokens;
overrideConfig: sobrescreve configurações por requisição;
history: envia histórico anterior;
uploads: envia imagens ou áudio, quando suportado pelo fluxo.

Quando o streaming está ativado, o Flowise emite eventos como:

start;
token;
metadata;
end.

Esse endpoint é o contrato entre o Flowise e o restante da sua aplicação. Por isso, ele deve ser tratado como qualquer outra API crítica: versionado, testado e monitorado.

Quando usar low-code e quando preferir code-first

Flowise é uma boa escolha quando você precisa de:

prototipagem rápida;
fluxos visuais legíveis pela equipe;
chatbots internos;
assistentes RAG;
demos funcionais;
colaboração com pessoas não engenheiras.

A tela visual ajuda a explicar o comportamento do agente sem exigir que todos leiam arquivos Python.

Frameworks code-first se destacam quando você precisa de mais controle. Se você está versionando lógica de agente no Git, escrevendo testes unitários detalhados para cada etapa ou criando máquinas de estado específicas, uma biblioteca como LangGraph ou o Google Agent Development Kit pode ser mais adequada.

O mesmo vale para o OpenAI Agents SDK quando seus agentes dependem de chamadas de ferramentas personalizadas.

Na prática, muitas equipes usam os dois caminhos:

prototipam no Flowise;
validam o comportamento com usuários;
estabilizam o design;
portam partes críticas para código, se necessário.

A decisão não precisa ser binária. O Flowise também oferece API, CLI, SDKs, tracing, avaliação e human-in-the-loop. Ele pode ir além de um protótipo simples. Mas quanto mais sua lógica se parece com software tradicional, mais uma stack code-first tende a recompensar.

Testando o endpoint de previsão e as APIs do fluxo

Um agente no Flowise é tão confiável quanto as APIs por trás dele.

Normalmente, o fluxo chama:

uma API de LLM;
um banco ou vector store;
ferramentas externas;
APIs REST internas;
serviços de terceiros.

Esses pontos podem falhar em produção. Por isso, teste tanto o endpoint do Flowise quanto as APIs que ele usa.

1. Teste o endpoint de previsão

Trate este endpoint como qualquer endpoint REST:

POST /api/v1/prediction/{id}

No Apidog, crie uma requisição com:

{
  "question": "Qual é o horário de funcionamento da sua loja?"
}

Depois, adicione asserções de API para validar o contrato da resposta.

Exemplos do que verificar:

status HTTP esperado;
presença do campo de resposta;
tipo dos campos retornados;
ausência de erro;
tempo máximo de resposta;
conteúdo mínimo esperado.

Exemplo de checklist:

Status é 200
Resposta contém texto
Resposta não contém campo de erro
Tempo de resposta está dentro do limite esperado

Isso ajuda a detectar mudanças no fluxo que quebram o contrato antes que seu app seja afetado.

2. Teste as APIs que o fluxo chama

Além do endpoint de previsão, teste diretamente cada dependência externa.

Por exemplo:

endpoint do provedor LLM;
API de busca;
API de CRM;
API de pedidos;
API de autenticação;
ferramenta interna chamada pelo agente.

Se você quer desenvolver sem gastar tokens ou bater em rate limits, use uma API mock com respostas realistas e previsíveis.

Esse padrão é útil para:

simular respostas do LLM;
simular ferramentas de terceiros instáveis;
testar erros controlados;
manter testes determinísticos;
rodar testes em CI sem depender de serviços externos.

Exemplo de resposta mockada para uma ferramenta de pedidos:

{
  "orderId": "12345",
  "status": "shipped",
  "estimatedDelivery": "2026-07-12"
}

Depois, valide se o fluxo interpreta esse formato corretamente.

Há um guia mais completo em nosso guia de harness de teste de agente de IA.

3. Separe ambientes

Também vale configurar ambientes diferentes para desenvolvimento, teste e produção.

No Apidog, você pode armazenar variáveis como:

base_url
flow_id
llm_api_key
tool_api_key

Assim, o mesmo teste pode rodar contra ambientes diferentes sem alterar a requisição.

Para baixar o Apidog e configurá-lo, o processo leva poucos minutos.

Perguntas frequentes

O Flowise é gratuito e de código aberto?

Sim. O Flowise é open source sob a licença Apache 2.0. Você pode executá-lo gratuitamente em uma implantação própria usando npm ou Docker. Também existe uma opção de nuvem hospedada se você preferir não gerenciar infraestrutura.

Para ambientes privados ou air-gapped, a rota auto-hospedada mantém tudo dentro da sua rede.

O Flowise usa LangChain?

O Flowise conecta componentes de LangChain e LlamaIndex. Os nós na tela mapeiam para conceitos familiares desses frameworks, como cadeias, agentes, armazenamentos de vetores, retrievers e motores de consulta.

Você usa esses blocos sem escrever manualmente todo o código de conexão.

Qual é a diferença entre um chatflow e um agentflow?

Um chatflow é indicado para sistemas de agente único, chatbots e pipelines LLM mais simples.

Um agentflow é mais amplo. Ele lida com sistemas multiagente e orquestrações com ramificação, looping e roteamento.

Comece com um chatflow para um assistente direto. Use um agentflow quando múltiplos agentes ou etapas precisarem coordenar trabalho.

Como eu testo a API de um fluxo do Flowise?

Chame o endpoint:

POST /api/v1/prediction/{id}

Envie um corpo JSON com uma question:

{
  "question": "Como acompanho meu pedido?"
}

Você pode fazer isso com curl, SDKs oficiais ou uma ferramenta dedicada.

No Apidog, você envia a requisição, valida a resposta, simula as APIs LLM e de ferramentas que o fluxo chama e executa os testes em CI.

Para detalhes sobre autenticação e streaming em endpoints LLM, veja nosso guia sobre como testar a API do ChatGPT com o Apidog.

Conclusão

Flowise é uma forma low-code de construir aplicativos LLM e agentes de IA. Você monta fluxos em uma tela de nós, escolhe entre chatflows, agentflows e assistentes, e publica um endpoint REST sem escrever toda a orquestração manualmente.

Ele funciona muito bem para protótipos, chatbots internos, assistentes RAG e fluxos que precisam ser entendidos pela equipe. Frameworks code-first ainda são melhores quando você precisa de controle profundo, testes unitários detalhados e lógica altamente customizada.

Independentemente da abordagem, o agente depende das APIs que chama. Teste o endpoint de previsão, simule LLMs e ferramentas externas, valide o contrato das respostas e execute esses testes de forma automatizada. Isso aumenta a chance de o agente se comportar em produção da mesma forma que se comportou na tela do Flowise.

Cypress Testes de API: Como Testar APIs com cy.request()

Lucas — Tue, 07 Jul 2026 04:17:42 +0000

Você já usa Cypress para testes end-to-end. Para validar uma API diretamente, você não precisa abrir a UI: use cy.request() para enviar requisições HTTP reais, verificar status codes e fazer asserções no corpo JSON. O comando roda no processo Node do Cypress, fora do navegador, e funciona bem para testar endpoints isolados ou preparar estado antes de um teste de interface.

Experimente o Apidog hoje

Neste guia, você verá como testar APIs com Cypress na prática: uso básico de cy.request(), asserções em respostas, encadeamento de chamadas com token de autenticação e stubbing de tráfego do navegador com cy.intercept(). Também verá quando o Cypress é suficiente e quando uma ferramenta nativa de API faz mais sentido.

Por que testar APIs com Cypress

Grande parte do que você valida na UI depende de uma API:

/login retorna um token.
/users retorna uma lista no formato esperado.
POST /orders cria um registro.
Uma resposta 500 exibe uma mensagem de erro na tela.

Testar esses endpoints diretamente ajuda em dois cenários:

Verificações mais rápidas: não há renderização, seleção de elementos ou espera por componentes da UI.
Setup de dados para testes e2e: em vez de clicar em vários formulários para criar dados, você envia requisições HTTP e começa o teste já no estado desejado.

Se o Cypress já está na sua stack, você pode adicionar testes de API nos mesmos arquivos de spec, com as mesmas asserções expect e no mesmo pipeline de CI.

Fundamentos do `cy.request()`

cy.request() envia uma requisição HTTP e retorna a resposta. Como ele roda no processo Node do Cypress, não fica sujeito a CORS ou à política de same-origin do navegador.

Formas comuns de uso:

cy.request(url)
cy.request(url, body)
cy.request(method, url)
cy.request(method, url, body)
cy.request(options)

A chamada mais simples usa GET por padrão:

cy.request('https://jsonplaceholder.typicode.com/users')

Para controlar método, headers, query params e payload, prefira o objeto de opções:

cy.request({
  method: 'POST',
  url: 'https://jsonplaceholder.typicode.com/posts',
  headers: {
    'Content-Type': 'application/json'
  },
  body: {
    title: 'API test',
    body: 'created from Cypress',
    userId: 1
  }
})

Opções úteis:

Opção	Uso
`method`	Verbo HTTP: `GET`, `POST`, `PUT`, `PATCH`, `DELETE` etc. O padrão é `GET`.
`url`	Endpoint da API.
`body`	Payload da requisição. Objetos são serializados como JSON.
`headers`	Cabeçalhos da requisição.
`auth`	Credenciais para autenticação HTTP Basic.
`qs`	Query string como objeto.
`failOnStatusCode`	Use `false` para testar respostas `4xx` ou `5xx` sem falhar automaticamente.

Exemplo com query string:

cy.request({
  method: 'GET',
  url: 'https://jsonplaceholder.typicode.com/posts',
  qs: {
    userId: 1
  }
}).then((response) => {
  expect(response.status).to.eq(200)
  expect(response.body).to.be.an('array')
})

Para testes negativos, desative failOnStatusCode. Por padrão, o Cypress falha o teste quando a resposta não é 2xx ou 3xx.

cy.request({
  method: 'GET',
  url: 'https://jsonplaceholder.typicode.com/users/99999',
  failOnStatusCode: false
}).then((response) => {
  expect(response.status).to.eq(404)
})

Fazendo asserções no status e no corpo

cy.request() retorna um objeto de resposta. Encadeie .then() para acessar os dados.

Propriedades mais usadas:

status: código HTTP.
body: corpo da resposta. Quando o Content-Type é JSON, o Cypress converte para objeto JavaScript.
headers: headers da resposta.
duration: tempo da requisição em milissegundos.

Exemplo completo:

describe('Users API', () => {
  it('returns a list of users', () => {
    cy.request('https://jsonplaceholder.typicode.com/users').then((response) => {
      expect(response.status).to.eq(200)
      expect(response.body).to.be.an('array')
      expect(response.body).to.have.length(10)
      expect(response.body[0]).to.have.property('email')
    })
  })
})

Como response.body já é um objeto JavaScript, você pode usar Chai normalmente:

cy.request('https://jsonplaceholder.typicode.com/users/1').then((response) => {
  expect(response.status).to.eq(200)

  expect(response.body).to.include({
    id: 1,
    username: 'Bret'
  })

  expect(response.body).to.have.nested.property('address.city')
  expect(response.body.email).to.match(/@/)
})

Também é comum validar headers:

cy.request('https://jsonplaceholder.typicode.com/users').then((response) => {
  expect(response.headers['content-type']).to.include('application/json')
})

Para estruturar melhor esse tipo de validação, veja também o guia sobre asserções de API e as melhores práticas de teste de API.

Encadeando requisições e reutilizando um token de autenticação

APIs reais geralmente exigem autenticação. O fluxo típico é:

Fazer login.
Ler o token da resposta.
Enviar o token nas próximas requisições.

Com cy.request(), esse encadeamento fica direto:

describe('Authenticated API flow', () => {
  it('logs in and fetches a protected resource', () => {
    cy.request({
      method: 'POST',
      url: 'https://api.example.com/login',
      body: {
        email: 'user@example.com',
        password: 'secret'
      }
    }).then((loginResponse) => {
      expect(loginResponse.status).to.eq(200)

      const token = loginResponse.body.token

      cy.request({
        method: 'GET',
        url: 'https://api.example.com/profile',
        headers: {
          Authorization: `Bearer ${token}`
        }
      }).then((profileResponse) => {
        expect(profileResponse.status).to.eq(200)
        expect(profileResponse.body).to.have.property('email', 'user@example.com')
      })
    })
  })
})

Se vários testes precisam do mesmo token, mova o login para um beforeEach:

describe('Protected API', () => {
  beforeEach(() => {
    cy.request({
      method: 'POST',
      url: 'https://api.example.com/login',
      body: {
        email: 'user@example.com',
        password: 'secret'
      }
    }).then((response) => {
      Cypress.env('authToken', response.body.token)
    })
  })

  it('gets the current user', () => {
    cy.request({
      method: 'GET',
      url: 'https://api.example.com/profile',
      headers: {
        Authorization: `Bearer ${Cypress.env('authToken')}`
      }
    }).then((response) => {
      expect(response.status).to.eq(200)
    })
  })
})

Esse padrão de login e reutilização de dados é comum em fluxos de teste de integração de API, onde uma chamada alimenta a próxima.

Usando `cy.request()` para preparar estado antes da UI

Um dos usos mais práticos de cy.request() é reduzir setup via interface.

Em vez de criar um usuário clicando por várias telas, crie via API e visite diretamente a página que você quer testar:

describe('User dashboard', () => {
  beforeEach(() => {
    cy.request({
      method: 'POST',
      url: 'https://api.example.com/test/users',
      body: {
        name: 'Ada Lovelace',
        email: 'ada@example.com'
      }
    }).then((response) => {
      expect(response.status).to.eq(201)
      Cypress.env('userId', response.body.id)
    })
  })

  it('shows the created user in the dashboard', () => {
    cy.visit(`/users/${Cypress.env('userId')}`)

    cy.contains('Ada Lovelace').should('be.visible')
    cy.contains('ada@example.com').should('be.visible')
  })
})

Esse padrão deixa seus testes de UI mais focados: a API prepara o estado, e a UI valida o comportamento visual.

`cy.intercept()` para stubbing

cy.request() acessa a API real. Quando você quer controlar o que o front-end recebe, use cy.intercept().

A diferença é importante:

cy.request() envia uma requisição HTTP real a partir do Node.
cy.intercept() intercepta requisições feitas pelo app no navegador.
cy.intercept() não intercepta chamadas feitas com cy.request().

Use cy.intercept() para testar como a UI reage a respostas específicas da API.

Exemplo de stub:

cy.intercept('GET', '/api/users', {
  statusCode: 200,
  body: [{ id: 1, name: 'Ada' }]
})

Agora, qualquer requisição do navegador para /api/users recebe esse payload fixo.

Isso é útil para simular cenários como:

lista vazia;
erro 500;
timeout;
payload incompleto;
usuário sem permissões.

Exemplo testando erro de API na UI:

it('shows an error banner when the API fails', () => {
  cy.intercept('GET', '/api/users', {
    statusCode: 500,
    body: { message: 'Server error' }
  }).as('getUsers')

  cy.visit('/dashboard')

  cy.wait('@getUsers')
    .its('response.statusCode')
    .should('eq', 500)

  cy.contains('Something went wrong').should('be.visible')
})

Configure a interceptação antes da ação que dispara a requisição. Caso contrário, o Cypress pode não capturar nada.

Você também pode simular uma resposta lenta:

cy.intercept('GET', '/api/users', {
  delay: 2000,
  statusCode: 200,
  body: []
}).as('getUsers')

cy.visit('/dashboard')

cy.contains('Loading').should('be.visible')
cy.wait('@getUsers')
cy.contains('No users found').should('be.visible')

Se você está decidindo entre falsificar uma resposta ou simular um serviço inteiro, veja os posts sobre API mocking e API stubbing vs API mocking.

Quando Cypress para API faz sentido

Use Cypress para testes de API quando eles estão próximos da sua suite de UI.

Bons casos de uso:

preparar dados antes de um teste e2e;
validar rapidamente endpoints dos quais a UI depende;
fazer smoke tests de API no mesmo pipeline do Cypress;
autenticar via API antes de visitar uma página;
simular respostas do backend com cy.intercept() para testar estados da UI.

Exemplo de smoke test simples:

describe('API smoke checks', () => {
  it('health endpoint is available', () => {
    cy.request('https://api.example.com/health').then((response) => {
      expect(response.status).to.eq(200)
      expect(response.body.status).to.eq('ok')
    })
  })
})

Quando uma ferramenta nativa de API faz mais sentido

O Cypress funciona bem para verificações de API dentro de uma suite de navegador. Mas ele não foi projetado como uma plataforma completa de teste de API.

Em uma suite grande e autônoma de API, algumas limitações aparecem:

cada requisição precisa ser escrita em código;
headers, bodies e query params ficam espalhados pelos arquivos de teste;
não há um construtor visual de requisições;
não há uma definição de API compartilhada como fonte central;
o Cypress ainda inicializa contexto de navegador, mesmo em execuções focadas em API;
colaboração entre QA, backend e frontend pode ficar menos fluida.

É nesse cenário que uma ferramenta nativa de API se encaixa melhor. O Apidog é construído em torno da própria API: você define endpoints, ambientes, autenticação, cenários e asserções em um workspace compartilhado. Para casos comuns, é possível montar requisições e validações visualmente, sem escrever tudo como código.

Para CI, o Apidog CLI executa cenários salvos de forma headless em qualquer etapa que rode Node:

npm install -g apidog-cli

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioOrSuiteId> \
  -e <environmentId> \
  -r cli,html,json,junit

Flags principais:

-t: cenário ou suite salvo.
-e: ambiente.
-r: formatos de relatório, como cli, html, json e junit.
-d ou --iteration-data: arquivo de dados para execução iterativa.
--upload-report: envia resultados de volta ao workspace.

A saída JUnit se integra bem à maioria dos dashboards de CI.

Uma regra prática:

use cy.request() para verificações de API que suportam seus testes de navegador;
use uma ferramenta nativa de API quando o teste de API for o trabalho principal.

Se você está comparando opções, veja também as ferramentas de automação de testes de API que rodam em CI/CD e as 30 melhores ferramentas de teste de API.

FAQ

`cy.request()` é executado no navegador?

Não. cy.request() roda no processo Node do Cypress, fora do navegador. Por isso, ele não é bloqueado por CORS ou pela política de same-origin.

Também por isso cy.intercept() não intercepta cy.request(). Se você precisa capturar uma requisição feita pelo navegador, dispare a chamada através do aplicativo e use cy.intercept().

Como testar uma resposta `400` ou `404` sem falhar o teste?

Use failOnStatusCode: false:

cy.request({
  method: 'GET',
  url: 'https://api.example.com/users/invalid-id',
  failOnStatusCode: false
}).then((response) => {
  expect(response.status).to.eq(404)
})

Sem essa opção, o Cypress falha automaticamente em respostas que não sejam 2xx ou 3xx.

Posso usar `cy.request()` para fazer login antes de um teste de UI?

Sim. Esse é um padrão comum.

Você pode enviar um POST para o endpoint de login, ler o token em response.body e armazená-lo em Cypress.env(), localStorage ou cookie, dependendo de como sua aplicação autentica o usuário.

Exemplo:

cy.request({
  method: 'POST',
  url: 'https://api.example.com/login',
  body: {
    email: 'user@example.com',
    password: 'secret'
  }
}).then((response) => {
  window.localStorage.setItem('token', response.body.token)
})

cy.visit('/dashboard')

Qual é a diferença entre `cy.request()` e `cy.intercept()`?

cy.request() envia uma requisição HTTP real e retorna a resposta real. Use para testar endpoints ou preparar dados.

cy.intercept() observa, espera ou simula requisições feitas pelo front-end no navegador. Use para controlar o que a UI recebe da API.

Em resumo:

Comando	Uso principal
`cy.request()`	Testar API real ou preparar estado
`cy.intercept()`	Espionar ou simular chamadas feitas pela UI

Devo usar Cypress ou uma ferramenta dedicada para testes de API?

Use Cypress quando as verificações de API complementam uma suite de testes de navegador que você já executa.

Para uma suite grande de API, execução focada em CI, colaboração entre times e uma definição compartilhada de endpoints, uma ferramenta nativa de API como o Apidog tende a ser mais adequada.

Para decidir a estratégia, consulte também as melhores práticas de teste de API.

Como Economizar na API Claude (Opus 4.8 e Fable 5)

Lucas — Tue, 07 Jul 2026 04:17:37 +0000

Sua fatura do Claude é composta principalmente por tokens de entrada, não de saída. A API é sem estado (stateless), então, a cada turno, você reenvia o histórico completo da conversa: prompt do sistema, definições de ferramentas, documentos colados e mensagens anteriores. Em loops de agente longos ou sessões de Claude Code, esse contexto reenviado cresce rápido — e você paga por ele em cada solicitação.

Experimente o Apidog hoje

As alavancas que realmente reduzem custo são as que diminuem o que você envia, reduzem a taxa por token ou evitam reenviar contexto morto. Este guia mostra como aplicar cada uma: primeiro recursos nativos, depois o proxy pxpipe, e por fim onde uma API mock ajuda durante desenvolvimento e testes.

Se você quer revisar os fundamentos de precificação primeiro — como o medidor funciona, o que é um token, como caching e batching são cobrados — veja nosso explicador de custos da API Claude. Aqui o foco é reduzir a fatura na prática.

Alavanca 1: Cache de prompts

O cache de prompts costuma ser a mudança com maior retorno para cargas de trabalho de agentes. A ideia é simples:

Separe um prefixo estável da solicitação.
Marque esse prefixo como armazenável em cache.
Reutilize exatamente os mesmos bytes nas próximas chamadas.

Esse prefixo normalmente inclui:

prompt do sistema;
definições de ferramentas;
documentos de referência longos;
instruções fixas de formato;
contexto base compartilhado entre turnos.

Na próxima solicitação que começar com os mesmos bytes, o Claude lê do cache em vez de reprocessar o texto inteiro pelo preço cheio de entrada.

Quando o cache compensa

Leituras do cache custam cerca de 0.1x a taxa de entrada base, ou seja, você pode economizar até ~90% na parte cacheada.

Mas a escrita no cache custa mais:

TTL de 5 minutos: 1.25x o token de entrada normal;
TTL de 1 hora: 2x o token de entrada normal.

Por isso, cache só vale a pena quando o prefixo é reutilizado:

cache de 5 minutos: ponto de equilíbrio em aproximadamente 2 solicitações;
cache de 1 hora: ponto de equilíbrio em aproximadamente 3 solicitações.

Se você cacheia um prefixo usado uma única vez, ele encarece a chamada. Se reutiliza dezenas de vezes, a parte cacheada fica quase gratuita depois da primeira escrita.

Checklist para não invalidar o cache

O cache usa correspondência de prefixo em nível de byte. Qualquer alteração dentro da região cacheada força uma nova escrita.

Evite colocar no prefixo estável:

timestamp;
ID de sessão;
contador de requisições;
dados do usuário;
mensagens recentes;
ferramentas em ordem variável;
documentos montados dinamicamente.

Um padrão seguro é estruturar sua solicitação assim:

[REGIÃO CACHEÁVEL]
- prompt do sistema fixo
- ferramentas em ordem fixa
- documentação estável
- políticas fixas de resposta

[REGIÃO DINÂMICA]
- mensagem atual do usuário
- histórico recente
- dados da sessão

Como verificar se está funcionando

Não assuma que o cache está ativo. Leia o campo:

usage.cache_read_input_tokens

Em chamadas repetidas com o mesmo prefixo, esse valor deve ser grande e diferente de zero.

Se ele estiver sempre em zero, algum byte do prefixo está mudando entre chamadas. Nesse caso, você está pagando preço cheio enquanto acredita estar usando cache.

Para a mecânica detalhada, veja o que é cache de prompt e como funciona.

Alavanca 2: Escolha o modelo certo

O gasto excessivo mais comum é usar um modelo maior do que a tarefa exige. Em vez de definir um modelo padrão para tudo, roteie por tipo de tarefa.

Precificação atual por 1M de tokens:

Modelo	ID do Modelo	Entrada	Saída	Janela de contexto
Fable 5	`claude-fable-5`	$10	$50	1M
Opus 4.8	`claude-opus-4-8`	$5	$25	1M
Sonnet 5	`claude-sonnet-5`	$3 ($2 intro)	$15 ($10 intro)	1M
Haiku 4.5	`claude-haiku-4-5`	$1	$5	200K

Pontos importantes:

Fable 5 custa 2x o Opus 4.8 na entrada e na saída.
Opus 4.8 tem janela de contexto de 1M sem prêmio adicional para contexto longo.
Sonnet 5 tem preço introdutório de $2/$10 até 31/08/2026, depois passa para $3/$15.
Haiku 4.5 é o modelo base a $1/$5, com janela menor de 200K.

Roteamento recomendado

Use uma matriz simples:

Tipo de tarefa	Modelo recomendado
Raciocínio de longo prazo muito difícil	Fable 5
Agentes, codificação e uso intenso de ferramentas	Opus 4.8
Produção de alto volume com boa qualidade	Sonnet 5
Classificação, extração, roteamento e respostas curtas	Haiku 4.5

Na prática:

Fable 5: use apenas quando a capacidade extra muda o resultado.
Opus 4.8: bom padrão para Claude Code e loops com muitas ferramentas.
Sonnet 5: útil para tráfego em volume quando custo por chamada importa.
Haiku 4.5: ideal para etapas simples do pipeline.

Exemplo de estratégia de roteamento:

function chooseClaudeModel(task: {
  type: "classification" | "coding" | "bulk_summary" | "hard_reasoning";
  volume: "low" | "high";
}) {
  if (task.type === "classification") return "claude-haiku-4-5";
  if (task.type === "hard_reasoning") return "claude-fable-5";
  if (task.volume === "high") return "claude-sonnet-5";

  return "claude-opus-4-8";
}

Um detalhe de faturamento sobre Fable 5: se um classificador de segurança recusar uma solicitação, o parâmetro beta fallbacks pode redirecionar essa vez para Opus 4.8. A vez redirecionada é cobrada nas taxas do Opus. Em geral, isso é um desconto, não uma cobrança surpresa.

Para análises mais detalhadas, veja:

Alavanca 3: API em lote com 50% de desconto

Se a tarefa não precisa de resposta em tempo real, use a API em Lote (Batch API).

Você envia tarefas para:

/v1/messages/batches

Elas são executadas de forma assíncrona e você busca os resultados depois. A maioria dos lotes termina em uma hora; o limite máximo é de 24 horas.

O desconto de 50% se aplica a todos os tokens do lote:

entrada;
saída.

Bons casos de uso

Use lote para trabalhos que podem esperar:

avaliações em conjunto de testes;
classificação em massa;
extração em backlog;
geração de resumos para registros existentes;
tags e metadados adjacentes a embeddings;
jobs noturnos;
reprocessamento offline.

Se metade do seu gasto com Claude vem de processamento noturno via endpoint síncrono, migrar essa metade para lote reduz diretamente 50% desse bloco de custo, sem mudar a qualidade.

A única troca é latência. Se você não precisava da resposta imediata, é uma economia direta.

Alavanca 4: Ajuste `effort`, `max_tokens` e `count_tokens`

Três controles ajudam a limitar quanto uma solicitação pode gastar.

1. Reduza `output_config.effort`

O parâmetro output_config.effort aceita:

low
medium
high
xhigh
max

Ele controla quanto o modelo “pensa” antes de responder. Tokens de pensamento são faturados.

Muitas tarefas executadas em high por hábito funcionam em medium ou low com qualidade suficiente.

Teste assim:

Escolha uma amostra real de prompts.
Rode com o esforço atual.
Rode um nível abaixo.
Compare qualidade, custo e latência.
Reduza o padrão se a qualidade se mantiver.

Exemplo de configuração conceitual:

{
  "model": "claude-opus-4-8",
  "max_tokens": 800,
  "output_config": {
    "effort": "medium"
  }
}

2. Defina `max_tokens`

max_tokens é um limite rígido para a saída.

Ele não reduz o custo de uma resposta que já seria curta, mas evita o pior caso: o modelo gerar 4.000 tokens quando você esperava um JSON pequeno.

Exemplos de teto por tarefa:

Tarefa	`max_tokens` sugerido
Classificação	20–100
Extração JSON simples	200–500
Resumo curto	300–800
Explicação técnica	1.000–2.000
Geração longa	limite específico do produto

Para respostas estruturadas, combine max_tokens com instruções explícitas:

Responda somente com JSON válido.
Não inclua explicações.
Use no máximo 5 campos.

3. Use `count_tokens` antes de enviar

O endpoint count_tokens informa quantos tokens de entrada a solicitação cobrará usando o tokenizador do próprio Claude.

Não use tiktoken para estimar Claude. tiktoken é o tokenizador da OpenAI e pode subestimar Claude em aproximadamente 15% a 20%.

Use count_tokens quando:

você tem orçamento por solicitação;
usuários podem colar documentos grandes;
o histórico cresce dinamicamente;
o prompt é montado por várias fontes;
você precisa bloquear chamadas caras antes de enviá-las.

Fluxo recomendado:

montar solicitação
→ chamar count_tokens
→ comparar com orçamento
→ resumir/cortar se necessário
→ enviar para /messages

Alavanca 5: Reduza o contexto reenviado

Como a API é sem estado, loops longos reenviam o histórico completo a cada turno.

No 30º turno, boa parte disso já é peso morto:

resultados de ferramentas já processados;
explorações abandonadas;
arquivos lidos uma única vez;
mensagens antigas que não influenciam mais a próxima decisão.

Você continua pagando tokens de entrada para reenviar tudo.

Duas funcionalidades no lado do servidor ajudam a podar esse contexto.

Edição de contexto

A edição de contexto:

clear_tool_uses_20250919

remove resultados de ferramentas obsoletos do contexto reenviado.

Use quando seu agente chama ferramentas com frequência e os resultados antigos não precisam continuar no prompt.

Compactação

A compactação:

compact_20260112

resume histórico antigo em uma forma menor.

Use em conversas longas para evitar reenviar a transcrição bruta inteira.

Essas duas abordagens rodam no lado do servidor. Você não precisa criar seu próprio sumarizador nem manipular arrays de mensagens manualmente.

Para sessões longas de Claude Code, essa é a mesma pressão que aparece ao atingir limites de contexto no meio da tarefa. Veja o guia sobre a janela de tokens do Claude Code e redefinições.

A regra prática é simples: não pague para reenviar contexto que o modelo não precisa mais.

Indo além: renderizar contexto como imagens com pxpipe

As alavancas anteriores reduzem ou reclassificam tokens enviados. O pxpipe tenta atacar o custo de entrada por outro caminho: renderizar contexto volumoso e estável como imagens para que seja tokenizado de forma mais barata.

O que é

pxpipe é um proxy local:

licenciado MIT;
escrito em TypeScript;
executado entre seu cliente e a API da Anthropic;
ativado apontando ANTHROPIC_BASE_URL para ele.

Ele inspeciona a solicitação antes de ela sair da sua máquina.

Como reduz custo

Texto denso é caro por token. O pxpipe reescreve partes grandes e estáveis da solicitação como imagens PNG compactas, por exemplo:

prompt do sistema;
documentação de ferramentas;
histórico antigo.

Segundo o projeto, conteúdo denso pode ficar em torno de 3.1 caracteres por token de imagem, contra cerca de 1 caractere por token de texto.

O projeto relata um exemplo em que um prompt de sistema mais documentação de ferramentas com ~48 mil caracteres vira cerca de 2.7 mil tokens de imagem, versus cerca de 25 mil como texto.

Importante: ele usa portões de lucratividade. Só transforma em imagem o conteúdo em que a matemática de tokens compensa. Prosa esparsa passa como texto.

Instalação

Inicie o proxy:

npx pxpipe-proxy

Ele sobe em:

127.0.0.1:47821

Aponte o Claude Code para o proxy:

ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude

Suporte a modelos

Por padrão, pxpipe transforma em imagem solicitações para:

claude-fable-5;
GPT 5.6.

Opus 4.7/4.8 e GPT 5.5 são opcionais, porque o projeto relata que eles leem contexto imagístico visivelmente pior.

Para habilitar outros modelos, use:

PXPIPE_MODELS=claude-opus-4-8 npx pxpipe-proxy

Ou configure pelo painel na URL do proxy.

Todo o resto passa inalterado.

Economias relatadas

Estes números são relatados pelo próprio projeto, não verificados independentemente aqui:

59% de economia em snapshot de produção;
fatura de $100 caindo para cerca de $41 em 13.709 solicitações;
piloto SWE-bench Lite com redução de -65% no tamanho da solicitação.

Trate como benchmark de fornecedor. Meça no seu tráfego antes de adotar.

Desvantagens

pxpipe pode ajudar, mas não é dinheiro grátis.

1. Interage com cache de prompts

A transformação em imagem muda os bytes da solicitação. Como o cache de prompts depende de correspondência exata de prefixo, imagem e cache podem se contrapor.

Ambos atacam o mesmo custo: tokens de entrada.

Teste as duas opções no seu prefixo real:

cenário A: cache de prompts sem pxpipe
cenário B: pxpipe sem cache
cenário C: ambos, se aplicável

Compare custo, qualidade e taxa de acerto do cache.

2. O modelo lê imagens via visão

O projeto sinaliza que strings densas podem ser mal interpretadas, como:

IDs hexadecimais longos;
tokens exatos;
hashes;
chaves;
valores que exigem leitura literal.

Falhas podem ser silenciosas. A saída parece válida, mas baseada em uma leitura errada da imagem.

Valide qualidade em tarefas reais antes de usar em produção.

3. É um proxy de terceiros no caminho da solicitação

Mesmo rodando localmente, ele manipula seu tráfego.

Antes de usar em produção, avalie:

dados sensíveis;
logs;
política de rede;
revisão de segurança;
atualização de dependências;
comportamento em falhas.

pxpipe vale testar se seu contexto é grande, estável e denso. Para prompts esparsos ou altamente favoráveis a cache, os recursos nativos podem capturar a maior parte da economia.

Reduza tokens desperdiçados em desenvolvimento e teste

Nenhuma das alavancas anteriores muda um ponto: você queima tokens pagos enquanto ainda está construindo a integração.

Apidog não reduz sua fatura de produção do Claude, e nem pretende. Onde ele ajuda é no ciclo de desenvolvimento e teste.

Durante desenvolvimento, cada chamada contra a API Anthropic ao vivo custa tokens reais:

execução quebrada;
tentativa de parser;
ajuste de prompt;
teste local;
job de CI em cada push;
validação de tratamento de erro.

Grande parte disso não precisa de um modelo real. Você só precisa validar se sua aplicação envia e recebe o formato correto.

Use mock da API durante a construção

Em vez de chamar a API real em todos os testes, simule a resposta da Anthropic no Apidog.

Fluxo prático:

Defina o contrato do endpoint Claude que sua aplicação chama.
Modele o corpo da requisição esperado.
Modele a resposta esperada.
Configure um mock determinístico.
Aponte testes locais e CI para o mock.
Use a API real apenas para validações de qualidade do modelo.

Exemplo de resposta mockada:

{
  "id": "msg_mock_123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "{\"status\":\"ok\",\"category\":\"billing\"}"
    }
  ],
  "usage": {
    "input_tokens": 120,
    "output_tokens": 18
  }
}

Isso permite testar:

serialização da requisição;
parsing da resposta;
validação de JSON;
tratamento de erro;
timeouts;
retries;
integração com CI.

Você também documenta o contrato de request/response no mesmo lugar, para que o time alinhe a interface antes de gastar tokens reais.

O escopo é honesto: isso reduz tokens de desenvolvimento e teste, não sua fatura de produção.

Combine as alavancas

Essas técnicas não são exclusivas. A maior redução vem da combinação.

Um plano prático:

Cacheie o prefixo estável

Prompt do sistema, ferramentas e documentos. Depois confirme que cache_read_input_tokens é diferente de zero.
Roteie por tarefa

Use Opus 4.8 como padrão, Fable 5 só quando necessário, Sonnet 5 para volume e Haiku 4.5 para tarefas simples.
Mova trabalho offline para lote

Tudo que não é sensível à latência deve ir para /v1/messages/batches.
Controle cada solicitação

Ajuste effort, defina max_tokens e use count_tokens para bloquear prompts caros antes do envio.
Reduza reenvio de histórico

Use edição e compactação de contexto para loops longos.
Teste pxpipe quando o contexto for denso

Compare contra cache no seu tráfego real. Não presuma que as economias se somam.
Use mocks durante desenvolvimento

Tire testes locais e CI do medidor pago sempre que o modelo real não for necessário.

Comece por cache e roteamento de modelos. Esses dois normalmente explicam a maior parte da redução. Depois meça cada mudança separadamente, porque o único número que importa é a sua fatura real.

FAQ

Tokens de entrada ou saída custam mais na fatura do Claude?

Por token, saída custa mais do que entrada em todos os modelos. Mas, em cargas de trabalho de agente e codificação, entrada costuma dominar a fatura porque a API sem estado faz você reenviar o histórico completo a cada turno.

Por isso, as maiores alavancas miram tokens de entrada.

Cache de prompts ou Batch API economiza mais?

Depende da carga de trabalho.

Cache de prompts economiza até ~90% no prefixo repetido de tráfego interativo. É ideal para chats e loops de agente que reutilizam prompt do sistema e ferramentas.

Batch API corta 50% de tudo, mas apenas para trabalhos assíncronos.

Muitas equipes usam ambos:

cache no caminho interativo;
lote para processamento offline.

Devo usar Fable 5 como padrão?

Não.

Fable 5 custa o dobro do Opus 4.8 e é voltado ao raciocínio de longo prazo mais difícil. Para a maioria dos trabalhos de agente e codificação, Opus 4.8 é o padrão mais econômico.

Usar Fable por padrão quando Opus seria suficiente é uma das formas mais comuns de dobrar a fatura sem necessidade.

pxpipe se soma ao cache de prompts?

Não de forma limpa.

pxpipe altera os bytes da solicitação ao transformar texto em imagem. O cache de prompts depende de correspondência exata de bytes no prefixo.

Como ambos miram o mesmo custo de entrada, podem se contrapor. Teste no seu prefixo real e compare.

Apidog reduz meus custos de produção do Claude?

Não.

Apidog permite simular a API da Anthropic para que testes locais e CI usem um mock em vez de gastar tokens pagos durante desenvolvimento.

Isso reduz gasto de desenvolvimento e teste, não a fatura de produção.

Aprenda a Testar Webhooks: Ferramentas Essenciais e Tutorial Passo a Passo

Lucas — Tue, 07 Jul 2026 04:16:47 +0000

Para testar um webhook, você precisa expor uma URL acessível ao provedor, disparar um evento real ou de teste e validar se seu manipulador recebe o payload, verifica a assinatura, responde corretamente e executa o efeito esperado. Como o webhook é enviado pelo provedor para o seu app, o fluxo de teste é diferente de uma chamada REST comum: você precisa capturar requisições de entrada, simular eventos e automatizar asserções.

Experimente o Apidog hoje

Por que webhooks exigem um fluxo de teste diferente

Em uma API REST comum, você controla a requisição: escolhe o método, monta o body, envia e lê a resposta.

Com webhooks, o provedor controla o envio. Ele decide quando chamar seu endpoint, quais cabeçalhos enviar e qual payload usar. Isso cria alguns desafios práticos:

Você nem sempre consegue disparar o evento diretamente. Um evento como payment_intent.succeeded depende do Stripe ou de uma ferramenta de teste do provedor.
A entrega é assíncrona. Seu teste precisa capturar uma requisição recebida, não apenas aguardar um retorno síncrono.
O payload é definido pelo provedor. Seu código precisa aceitar exatamente o formato enviado por Stripe, GitHub, Slack ou outro serviço.
A maioria dos provedores assina as requisições. Seu endpoint deve validar a assinatura antes de confiar no body. Veja também o guia sobre verificação de assinatura de webhook.

Se você ainda está avaliando o padrão arquitetural, estes guias ajudam a comparar alternativas: webhooks vs polling e webhook vs WebSocket.

Ferramentas úteis para testar webhooks

Um fluxo de teste completo normalmente usa quatro tipos de ferramenta:

serviço de captura para inspecionar payloads reais;
túnel local para expor seu localhost;
ferramenta do provedor para disparar eventos;
ferramenta de teste para validar resposta e efeitos colaterais.

1. Capture o payload real antes de implementar

Antes de escrever ou ajustar o manipulador, capture um webhook real. Isso evita testar contra um JSON inventado que não representa o payload do provedor.

Serviços comuns:

webhook.site

O webhook.site gera uma URL pública temporária. Tudo que for enviado para ela aparece na interface: método, headers, body e query params.

Use para responder:

quais headers o provedor envia?
qual é o formato real do body?
onde vem o ID do evento?
qual header contém a assinatura?

Beeceptor

O Beeceptor fornece um endpoint HTTPS para receber webhooks e inspecionar payloads em tempo real. Também permite configurar mock servers, útil quando você quer capturar e simular usando a mesma ferramenta.

Pipedream RequestBin

O Pipedream RequestBin também permite criar URLs públicas para capturar requisições HTTP. Como limites gratuitos mudam com frequência, verifique a documentação atual do serviço antes de usar em um fluxo recorrente.

Depois de capturar um evento real, salve uma amostra do payload. Você vai reutilizá-la em testes manuais, automatizados e em CI.

2. Exponha seu ambiente local com um túnel

Provedores externos não conseguem acessar localhost:3000 diretamente. Para testar seu manipulador local, use um túnel que gere uma URL HTTPS pública e encaminhe o tráfego para sua máquina.

Usando ngrok

brew install ngrok

ngrok config add-authtoken $YOUR_TOKEN

ngrok http 3000

O comando imprime uma URL HTTPS pública. Configure essa URL no provedor, por exemplo:

https://abc123.ngrok-free.app/webhooks

Se seu servidor local estiver escutando em:

http://localhost:3000/webhooks

o provedor enviará o webhook para o ngrok, e o ngrok encaminhará para sua aplicação local.

Usando cloudflared

cloudflared tunnel --url http://localhost:3000

Assim como o ngrok, o cloudflared imprime uma URL pública que encaminha tráfego para sua porta local.

Esse padrão é útil para depurar com breakpoints, logs e ferramentas do seu editor. Para uma explicação mais detalhada, veja como testar APIs localhost com serviços de webhook.

3. Dispare eventos reais ou de teste do provedor

Depois de ter uma URL pública, você precisa fazer o provedor enviar um evento.

Stripe CLI

O Stripe CLI permite encaminhar eventos da sandbox para seu endpoint local.

stripe listen --forward-to localhost:3000/webhooks

Para filtrar eventos específicos:

stripe listen \
  --events payment_intent.succeeded,checkout.session.completed \
  --forward-to localhost:3000/webhooks

O comando também imprime um segredo de assinatura. Configure esse segredo na sua aplicação para validar o header Stripe-Signature.

Com o listener ativo, dispare eventos de teste:

stripe trigger payment_intent.succeeded

stripe trigger checkout.session.completed

stripe trigger --help

Atenção: alguns triggers criam objetos de API relacionados e podem gerar eventos em cascata. Por exemplo, payment_intent.succeeded também pode emitir payment_intent.created.

GitHub

O GitHub permite reentregar webhooks recentes.

Fluxo:

Abra o repositório.
Vá em Settings.
Acesse Webhooks.
Clique na URL do webhook.
Abra Recent Deliveries.
Selecione uma entrega.
Clique em Redeliver.

Restrições importantes:

só é possível reentregar eventos dos últimos 3 dias;
você precisa ter acesso de administrador ao repositório;
o GitHub não reenvia automaticamente entregas com falha.

Slack

Webhooks de entrada do Slack são simples de testar: basta fazer um POST com JSON para a URL do webhook.

curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
  -H 'Content-type: application/json' \
  -d '{"text":"Hello, world."}'

A URL do webhook do Slack é um segredo. Não coloque essa URL no frontend, em repositórios públicos ou em logs expostos.

4. Valide seu manipulador com payloads repetíveis

Capturar e disparar eventos confirma que a conexão funciona. Mas você ainda precisa validar se o manipulador está correto.

Um teste mínimo pode ser feito com curl:

curl -X POST http://localhost:3000/webhooks \
  -H 'Content-Type: application/json' \
  -H 'Stripe-Signature: t=...,v1=...' \
  -d '{
    "id": "evt_test",
    "type": "payment_intent.succeeded",
    "data": {
      "object": {
        "id": "pi_123",
        "status": "succeeded"
      }
    }
  }'

Esse teste é útil para smoke test, mas não escala bem. Para testes repetíveis, salve payloads, headers e asserções em uma ferramenta de API.

Testando webhooks com Apidog

Apidog é uma plataforma para projetar, depurar, testar, simular e documentar APIs.

Ele não funciona como uma “caixa de entrada de webhook” dedicada. O uso mais prático para webhooks é:

montar payloads de exemplo;
salvar requisições reutilizáveis;
validar respostas com asserções;
simular provedores com mock server;
executar cenários em CI com o Apidog CLI.

Crie uma requisição reutilizável para o webhook

Pegue o payload capturado em uma ferramenta como webhook.site ou copiado da documentação do provedor.

No Apidog:

Crie uma nova requisição.
Defina o método como POST.
Configure a URL do seu endpoint, por exemplo:

http://localhost:3000/webhooks

Cole o JSON no body.
Adicione os headers enviados pelo provedor, por exemplo:

Content-Type: application/json
Stripe-Signature: t=...,v1=...

Salve a requisição.

Agora você tem um teste repetível para enviar um payload conhecido ao seu manipulador sem reescrever comandos curl.

Crie variações para cobrir casos como:

payload válido;
campo obrigatório ausente;
assinatura inválida;
evento duplicado;
tipo de evento não suportado.

Adicione asserções para validar a resposta

Enviar o payload não basta. Você precisa validar o retorno do endpoint.

No Apidog:

Abra a requisição ou cenário.
Vá em Processadores Pós-execução.
Clique em + Adicionar.
Escolha Asserção.
Configure a regra de validação.

Exemplo de asserção:

JSONPath: $.data.status
Condição: Igual a
Valor esperado: succeeded

Você também pode validar o status HTTP:

Status code == 200

Para cenários de erro:

Status code == 400

ou:

Status code == 401

quando a assinatura for inválida.

Asserções visuais comparam valores como strings. Se precisar validar tipos com precisão, como número ou booleano, use script customizado com sintaxe pm.test compatível com Postman.

Exemplo conceitual:

pm.test("status deve ser succeeded", function () {
  const json = pm.response.json();
  pm.expect(json.data.status).to.eql("succeeded");
});

Use mock server para simular um provedor

Em alguns testes, seu serviço chama uma API externa depois de receber o webhook. Para evitar chamadas reais durante o desenvolvimento, você pode simular essa API com o mock server do Apidog.

O Apidog oferece três tipos de mock:

Mock Local: roda com o cliente desktop e só funciona enquanto ele estiver aberto.
Mock na Nuvem: hospedado pelo Apidog, funciona continuamente e pode ser ativado ou desativado.
Mock Runner: executado em infraestrutura auto-hospedada e compartilhado com a equipe.

Cada endpoint HTTP tem um módulo de mock. Copie a URL do mock na aba API em modo Design ou na aba Mock em modo Debug.

Importante: apenas caminhos que começam com / roteiam para o ambiente de mock.

Use essa URL em testes para obter respostas previsíveis sem chamar o provedor real.

Execute testes de webhook em CI com Apidog CLI

Depois que o cenário passar localmente, execute-o em CI.

Instale o CLI:

npm install -g apidog-cli

Verifique a instalação:

node -v
apidog -v
which node
which npm
which apidog

O Apidog CLI requer Node.js v16 ou superior.

Execute um cenário salvo:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  -d 3497013 \
  -r html,cli

Parâmetros:

-t: ID do cenário de teste;
-e: ID do ambiente, obrigatório;
-d: dados de teste, como arquivo CSV/JSON ou ID de dataset;
-r: reporters, como cli, html, json ou junit.

Para detalhes de uso, veja o tutorial do Apidog CLI.

Quer montar e validar testes de webhook visualmente? Experimente o Apidog gratuitamente, sem necessidade de cartão de crédito.

Fluxo recomendado para testar webhooks

Use esta sequência como checklist:

Capture um payload real.

Aponte o provedor para uma URL do webhook.site ou ferramenta similar.
Analise headers e assinatura.

Identifique Content-Type, header de assinatura, ID do evento e formato do body.
Suba seu manipulador local.

Execute sua aplicação em uma porta local, por exemplo localhost:3000.
Abra um túnel.

Use ngrok http 3000 ou cloudflared tunnel --url http://localhost:3000.
Configure a URL pública no provedor.

Exemplo:

   https://abc123.ngrok-free.app/webhooks

Dispare um evento real ou de teste.

Use stripe trigger, o botão Redeliver do GitHub ou um POST do Slack.
Teste assinatura válida e inválida.

O manipulador deve aceitar a requisição válida e rejeitar a adulterada.
Valide resposta e efeitos colaterais.

Verifique status HTTP, body, escrita no banco, publicação em fila ou chamada downstream.
Automatize.

Salve o cenário no Apidog e execute com Apidog CLI no CI.

Se você está projetando o sistema de webhooks, veja também como projetar webhooks confiáveis e melhores práticas de webhook de pagamento. Para contexto arquitetural, consulte o guia da API de webhooks e webhooks e arquitetura orientada a eventos.

Perguntas frequentes

Como testar um webhook?

Forneça ao provedor uma URL acessível, dispare um evento real ou de teste e valide se seu endpoint recebeu o payload, verificou a assinatura, retornou o status correto e executou o efeito esperado.

Como testar webhooks localmente?

Execute seu manipulador localmente e exponha a porta com um túnel:

ngrok http 3000

ou:

cloudflared tunnel --url http://localhost:3000

Depois, configure a URL HTTPS pública no provedor e dispare um evento.

Como testar um webhook com Postman?

Você pode usar o Postman para enviar um POST com payload e headers personalizados para seu endpoint. Ele é útil para validar resposta, mas não recebe webhooks reais sozinho. Para capturar eventos reais, combine com um serviço de captura ou túnel. O mesmo se aplica ao Apidog.

Como testar webhooks do Stripe?

Use o Stripe CLI:

stripe listen --forward-to localhost:3000/webhooks

Depois dispare um evento:

stripe trigger payment_intent.succeeded

Use o segredo exibido pelo stripe listen para validar o header Stripe-Signature.

Como testar um webhook do Slack?

Envie um POST JSON para a URL de webhook de entrada:

curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
  -H 'Content-type: application/json' \
  -d '{"text":"Hello, world."}'

Se o teste funcionar, a mensagem aparecerá no canal configurado.

Como testar uma URL de webhook?

Envie um POST de amostra e confirme o status HTTP, o body da resposta e os efeitos colaterais. Para um teste mais confiável, use um payload real capturado, teste assinaturas válidas e inválidas e automatize asserções.

Observabilidade de API: O Que É e Como Implementar

Lucas — Mon, 06 Jul 2026 09:13:35 +0000

A observabilidade de API é a capacidade de entender por que sua API se comporta de determinada forma analisando a telemetria que ela emite: métricas, logs e traces. Na prática, uma API observável permite investigar incidentes, latência, erros e regressões sem precisar publicar uma nova versão apenas para adicionar mais logs.

Experimente o Apidog hoje

O que a observabilidade de API realmente significa

Na teoria de controle, um sistema é observável quando você consegue inferir seu estado interno a partir de suas saídas externas. Em software, isso significa que a API deve emitir dados suficientes para responder perguntas como:

Qual endpoint ficou lento?
Qual região foi afetada?
Qual versão da API gerou mais erros?
Qual serviço interno adicionou latência?
Qual requisição específica falhou e por quê?

A diferença prática é esta: se um cliente relata que o checkout ficou lento às 2h da manhã para usuários de uma região específica, você não deveria precisar fazer deploy de novo para adicionar console.log. A telemetria já coletada deve permitir investigar o incidente.

Observabilidade vs monitoramento

Monitoramento e observabilidade se complementam, mas não são a mesma coisa.

O monitoramento acompanha sinais conhecidos e dispara alertas quando eles passam de um limite definido. Exemplo:

taxa de erro acima de 2%;
latência p99 acima de 500 ms;
CPU acima de 80%;
endpoint /checkout retornando 5xx.

A observabilidade permite fazer perguntas novas durante a investigação. Exemplo:

a latência aumentou apenas para POST /v2/checkout?
o problema acontece só na versão 2026-05 da API?
há correlação com uma região específica?
qual chamada downstream consumiu mais tempo?
quais logs compartilham o mesmo trace_id?

Em resumo: o monitoramento diz que algo está errado; a observabilidade ajuda a encontrar a causa. Para aprofundar o lado de alertas e verificações, veja o guia de monitoramento de API.

Aspecto	Monitoramento	Observabilidade
Pergunta respondida	Um sinal conhecido está fora da faixa?	Por que o sistema está se comportando assim?
Definido quando	Antes do incidente	Durante a investigação
Melhor para	Falhas conhecidas e violações de SLO	Problemas novos ou inesperados
Saída	Alertas e dashboards	Telemetria consultável de alta cardinalidade

Os três pilares: métricas, logs e traces

A observabilidade normalmente combina três tipos de telemetria: métricas, logs e traces. O OpenTelemetry formaliza esses dados como sinais de telemetria, junto com outros recursos como baggage, eventos e perfis em desenvolvimento.

1. Métricas

Métricas são medições numéricas agregadas ao longo do tempo. Para APIs, comece com:

requisições por segundo;
taxa de erro;
latência p50, p95 e p99;
throughput por endpoint;
disponibilidade por rota crítica.

Evite depender apenas de médias. Uma média de 120 ms pode esconder um p99 de 4 segundos, que é o que usuários reais podem estar sentindo.

Exemplo de métricas úteis por endpoint:

http_requests_total{method="POST", path="/v2/checkout", status="200"}
http_requests_total{method="POST", path="/v2/checkout", status="503"}
http_request_duration_ms_bucket{method="POST", path="/v2/checkout"}

Métricas são baratas de armazenar e rápidas de consultar. Use-as para dashboards, alertas e SLOs.

2. Logs

Logs registram eventos discretos com timestamp. Para observabilidade, prefira logs estruturados em JSON em vez de texto livre.

Exemplo:

{
  "timestamp": "2026-06-22T02:14:09Z",
  "level": "error",
  "method": "POST",
  "path": "/v2/checkout",
  "status": 503,
  "duration_ms": 4812,
  "trace_id": "8f3a1c9d2e7b4a16",
  "user_region": "ap-southeast-1",
  "api_version": "2026-05"
}

Campos recomendados para logs de API:

timestamp
level
trace_id
request_id
method
path
status
duration_ms
user_region
api_version
client_id ou tenant_id, se aplicável

O campo mais importante para correlacionar dados é o trace_id. Ele conecta logs individuais ao fluxo completo da requisição.

3. Traces

Um trace distribuído acompanha uma requisição enquanto ela passa por diferentes serviços. Cada etapa é registrada como um span.

Exemplo de fluxo:

POST /v2/checkout
├── API Gateway: 20 ms
├── Auth Service: 35 ms
├── Checkout Service: 120 ms
├── Payment Service: 3900 ms
└── Notification Service: 40 ms

Nesse exemplo, a causa da lentidão está no serviço de pagamento. Sem traces, você provavelmente começaria a investigar serviço por serviço.

Os três pilares funcionam melhor juntos:

Uma métrica dispara o alerta: p99 subiu.
Um trace mostra onde o tempo foi gasto.
Os logs filtrados por trace_id explicam o erro específico.

Use RED como ponto de partida

Você não precisa instrumentar tudo no primeiro dia. Para APIs, comece com o método RED:

Rate: quantas requisições por segundo a API processa.
Errors: quantas requisições falham.
Duration: quanto tempo as requisições levam.

Rate     = requisições por segundo
Errors   = % de respostas 5xx e 4xx inesperadas
Duration = latência p95 e p99 por endpoint

RED funciona bem para APIs, gateways e service meshes porque é centrado em requisições. Para infraestrutura, complemente com USE:

utilização;
saturação;
erros.

Uma abordagem prática:

API      → RED
Servidor → USE
Banco    → RED + USE, dependendo do caso

Transforme sinais em metas com SLIs e SLOs

Coletar telemetria é só o começo. Para tornar os dados acionáveis, defina SLIs e SLOs.

Um SLI é uma métrica que representa a qualidade do serviço. Exemplos:

SLI de disponibilidade = requisições bem-sucedidas / total de requisições
SLI de latência        = % de requisições abaixo de 300 ms
SLI de erro            = requisições 5xx / total de requisições

Um SLO é a meta para esse indicador. Exemplos:

99,9% das requisições devem retornar sem erro em 28 dias.
95% das requisições de checkout devem concluir em menos de 300 ms.
99% das chamadas de autenticação devem concluir em menos de 200 ms.

Sem SLO, um gráfico de latência é apenas uma linha. Com SLO, ele vira um critério objetivo para decidir quando priorizar confiabilidade em vez de novas funcionalidades.

Instrumente com OpenTelemetry

Você pode dividir a stack de observabilidade em duas partes:

Geração de telemetria: o que seu código emite.
Backend de análise: onde você armazena e consulta os dados.

Para geração, OpenTelemetry é o padrão mais importante. Ele é um projeto da CNCF, surgiu da fusão entre OpenTracing e OpenCensus e é independente de fornecedor.

Com OpenTelemetry, você pode:

gerar traces, métricas e logs;
padronizar nomes e atributos com convenções semânticas;
exportar dados via OTLP;
usar auto-instrumentação quando disponível;
enviar telemetria para diferentes backends;
reduzir dependência de um fornecedor específico.

Para armazenamento e análise, você pode usar ferramentas como Prometheus com Grafana para métricas, ou plataformas como Datadog e Honeycomb para traces, métricas e logs. Se você usa Datadog, este passo a passo da API do Datadog mostra como enviar e consultar dados programaticamente.

A principal vantagem do OpenTelemetry é instrumentar uma vez e trocar o backend depois sem reescrever toda a instrumentação.

Inclua testes e verificações sintéticas

Observabilidade não deve começar apenas em produção. Testes também geram sinais úteis.

Shift left: testes de contrato em CI

Antes do deploy, testes de contrato verificam se a API ainda corresponde à especificação. Isso ajuda a detectar mudanças incompatíveis antes que cheguem aos usuários.

Cada execução de CI gera dados úteis:

commit
branch
ambiente
cenário executado
resultado
duração
timestamp

O Apidog CLI permite executar cenários de teste em pipelines. Ele é construído em Node.js e requer Node v16 ou superior.

Instalação:

npm install -g apidog-cli

# verificar instalação
node -v && apidog -v

Executar um cenário de teste:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli

Onde:

-t = ID do cenário de teste
-e = ID do ambiente
-r = formatos de relatório: cli, html, json ou junit

Para executar com dados de iteração em CSV ou JSON:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli -d ./data.csv

Para enviar um resumo do relatório para a nuvem Apidog:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli --upload-report

Para um pipeline completo, veja o guia do Apidog CLI para CI/CD. Para todas as flags disponíveis, consulte a referência completa do CLI.

Monitoramento sintético em produção

Monitoramento sintético executa requisições roteirizadas contra sua API em produção, em intervalos definidos, como um usuário real faria.

Comece simples:

chamar um endpoint de saúde;
validar status code;
medir latência;
verificar payload mínimo;
registrar falhas.

Uma verificação de saúde da API é o ponto inicial. O monitoramento sintético expande isso para fluxos de várias etapas, como login, criação de recurso e checkout.

Essas verificações também são sinais de observabilidade. Uma execução sintética falhando às 02:00 com duração de 4 segundos deve ser correlacionável com logs, métricas e traces.

Para comparar opções, veja a lista de ferramentas de teste sintético e a lista de ferramentas de monitoramento de API.

Gerando sinais recorrentes com Tarefas Agendadas do Apidog

O Apidog pode gerar sinais sintéticos recorrentes por meio de Tarefas Agendadas. O recurso executa automaticamente cenários de teste em horários definidos, captura resultados e ajuda em testes de regressão agendados.

Você encontra o recurso no módulo de Testes, em Tarefas Agendadas.

Ao configurar uma tarefa, defina:

Cenários de Teste: um ou mais cenários para executar.
Modo de Execução: por exemplo, todo domingo às 23h ou a cada 6 horas.
Notificação: após cada execução ou apenas em caso de falha.

Pontos importantes:

Tarefas Agendadas estão em Beta.
O recurso requer um Runner auto-hospedado configurado.
As opções atuais de “Executar Em” listam Runner auto-hospedado.
Apidog Cloud aparece como “em breve”.
O número de execuções depende do plano de assinatura.

Para uma configuração prática, veja o passo a passo das Tarefas Agendadas do Apidog.

O benefício é fechar o ciclo: você projeta e testa a API, depois executa os mesmos cenários periodicamente para gerar sinais de aprovação, falha e latência.

Um caminho prático para tornar sua API observável

Se você está começando do zero, siga esta ordem:

Padronize logs estruturados
- Use JSON.
- Inclua trace_id, request_id, método, rota, status e duração.
- Evite logs de texto livre para eventos importantes.
Adicione correlação por requisição
- Gere ou propague um trace_id.
- Inclua o mesmo ID em logs, traces e respostas de erro quando fizer sentido.
Instrumente com OpenTelemetry
- Comece pelos endpoints críticos.
- Exporte traces e métricas via OTLP.
- Mantenha atributos consistentes, como http.method, http.route e http.status_code.
Monitore RED
- Rate.
- Errors.
- Duration com p95 e p99.
Defina SLIs e SLOs
- Disponibilidade.
- Latência.
- Taxa de erro.
- Janelas de medição, como 7, 14 ou 28 dias.
Adicione testes de contrato ao CI
- Execute cenários em cada pull request ou antes do deploy.
- Exporte relatórios em junit ou json quando precisar integrar com outras ferramentas.
Execute verificações sintéticas
- Comece com health checks.
- Evolua para fluxos críticos.
- Agende execuções recorrentes.
Correlacione tudo
- Métrica aponta o sintoma.
- Trace mostra o caminho.
- Log explica o evento.
- Teste sintético confirma impacto externo.

Você não precisa implementar tudo de uma vez. Só migrar de logs de texto livre para logs JSON com trace_id já melhora bastante sua capacidade de investigação.

Checklist rápido

Use este checklist para revisar sua API:

[ ] Logs são estruturados em JSON
[ ] Cada requisição tem trace_id ou request_id
[ ] Erros incluem contexto suficiente para debug
[ ] Latência é medida por percentis, não apenas média
[ ] Métricas RED existem por endpoint crítico
[ ] Há SLOs definidos para disponibilidade e latência
[ ] Traces mostram chamadas entre serviços
[ ] Testes de contrato rodam em CI
[ ] Verificações sintéticas rodam em produção
[ ] Alertas apontam para sintomas acionáveis

Perguntas frequentes

O que é observabilidade de API?

Observabilidade de API é a capacidade de entender o estado interno de uma API a partir da telemetria que ela emite: métricas, logs e traces. Uma API observável permite investigar por que ela se comporta de certa maneira sem adicionar nova instrumentação primeiro.

Observabilidade de API e monitoramento são a mesma coisa?

Não. Monitoramento acompanha sinais predefinidos e alerta quando eles cruzam limites. Observabilidade permite fazer perguntas novas durante a investigação. O monitoramento informa que algo está errado; a observabilidade ajuda a descobrir por quê.

Quais são os três pilares da observabilidade?

Os três pilares são métricas, logs e traces. Métricas mostram números agregados, logs registram eventos discretos e traces acompanham uma requisição entre serviços.

Como tornar uma API observável?

Comece com logs estruturados e trace_id em cada requisição. Depois, adicione OpenTelemetry, métricas RED, SLIs, SLOs, testes de contrato em CI e verificações sintéticas em produção.

OpenTelemetry é obrigatório?

Não. Observabilidade é uma propriedade do sistema, não uma ferramenta específica. Mas OpenTelemetry é um padrão CNCF independente de fornecedor e facilita instrumentar uma vez para enviar dados a diferentes backends, como Prometheus, Datadog ou Honeycomb.

Como Usar a CLI do Apidog no Hermes Agent

Lucas — Mon, 06 Jul 2026 09:12:20 +0000

O Hermes Agent roda no seu terminal, mantém contexto entre sessões e executa comandos de shell reais. Isso permite usar o Hermes como parte do seu loop de testes de API: se ele consegue executar um comando, ele consegue executar seus cenários do Apidog.

Experimente o Apidog hoje

O executor é a CLI do Apidog, o pacote npm apidog-cli. Ela executa, direto do terminal, os cenários de teste criados visualmente no Apidog e retorna um código de saída que o Hermes pode interpretar.

Neste guia, você vai configurar o Hermes para:

Ler instruções de teste a partir de AGENTS.md.
Executar apidog run usando a ferramenta terminal.
Validar o resultado pelo código de saída.
Opcionalmente, conectar o servidor Apidog MCP para que o Hermes também leia a especificação da API enquanto codifica.

Se a CLI ainda não estiver instalada, siga primeiro o guia como instalar a CLI do Apidog com um agente de codificação de IA. Volte quando este comando imprimir uma versão:

apidog --version

Você também precisa de uma conta Apidog com pelo menos um cenário de teste salvo.

O que significa usar a CLI do Apidog no Hermes

O Hermes Agent, construído pela Nous Research, roda no terminal e executa ações por meio de ferramentas integradas. Para este fluxo, a ferramenta importante é terminal.

Na prática, usar a CLI do Apidog no Hermes significa:

Registrar o fluxo de trabalho em um arquivo de contexto, como AGENTS.md, para que o Hermes saiba qual comando executar.
Executar apidog run pela ferramenta terminal, como qualquer outro comando de shell.
Tratar o código de saída como fonte da verdade:
- 0: todas as asserções passaram.
- diferente de 0: houve falha.
Opcionalmente, conectar o servidor Apidog MCP, para expor a especificação da API ao Hermes durante a implementação.

Não é necessário instalar um plugin específico do Apidog no Hermes. O Hermes só precisa saber qual comando executar e como interpretar o resultado.

O mecanismo: arquivo de contexto em vez de lembrete no chat

O Hermes carrega contexto do projeto no início da sessão. Ele procura arquivos de instrução no diretório de trabalho, incluindo:

AGENTS.md
CLAUDE.md

Esses arquivos são injetados no prompt do sistema. Portanto, se o seu repositório já usa AGENTS.md, o Hermes também consegue ler essas instruções.

Colocar o comando no chat funciona apenas para a sessão atual. Colocar o comando em AGENTS.md torna o fluxo reutilizável por:

você;
outros membros do time;
futuras sessões do Hermes;
automações locais baseadas no mesmo repositório.

O Hermes também lê SOUL.md, mas esse arquivo é voltado à persona do agente. Mantenha instruções de teste no AGENTS.md.

Passo 1: adicione um bloco Apidog ao `AGENTS.md`

Na raiz do repositório, abra ou crie o arquivo AGENTS.md:

touch AGENTS.md

Adicione um bloco com o comando real que o Hermes deve executar:

## API testing with the Apidog CLI

This repo uses the Apidog CLI (`apidog-cli`, the `apidog` command) to run API
test scenarios. The scenarios live in our Apidog project, not in this repo.

When you change an API handler, route, or response shape, run the relevant
Apidog scenario through the terminal tool before considering the change done:

    apidog run -t 605067 -e 1629989 -n 1 -r cli

- `-t 605067` is the checkout-flow test scenario.
- `-e 1629989` is the staging environment.
- The machine is already authenticated via `apidog login`, so do NOT pass
  an access token and do NOT print one.

Treat the exit code as the source of truth: `0` means every assertion passed,
non-zero means a failure. If it exits non-zero, read the failing assertion in
the report and fix the code, then re-run. Do not report a pass on a non-zero
exit.

Substitua:

605067 pelo ID real do cenário;
1629989 pelo ID real do ambiente.

Use normalmente um ambiente de staging ou desenvolvimento local. Evite apontar o Hermes para produção.

Esse bloco é importante por dois motivos:

Ele fornece o comando exato, evitando que o Hermes invente flags.
Ele define que o código de saída tem prioridade sobre qualquer resumo textual.

Isso reduz a chance de o agente declarar “testes passaram” quando a execução falhou.

Passo 2: copie o comando gerado pelo Apidog

Antes de pedir ao Hermes para executar o teste, obtenha um comando válido no Apidog.

No Apidog:

Abra o cenário de teste.
Vá para a aba CI/CD.
Escolha a opção de linha de comando.
Copie o comando apidog run.

O comando gerado terá este formato:

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli

Onde:

605067 é o ID do cenário;
1629989 é o ID do ambiente;
YOUR_ACCESS_TOKEN é o token de acesso.

Como a máquina já deve estar autenticada via apidog login, remova --access-token YOUR_ACCESS_TOKEN antes de colocar o comando no AGENTS.md.

Use este formato no contexto do Hermes:

apidog run -t 605067 -e 1629989 -n 1 -r cli

Passo 3: peça ao Hermes para executar o teste

Inicie o Hermes na raiz do repositório e peça para executar o cenário de acordo com o AGENTS.md.

Exemplo de prompt:

Execute nosso cenário de teste de API do Apidog da maneira que AGENTS.md descreve. Já estou autenticado, então não passe um token de acesso. Use apidog run -t 605067 -e 1629989 -n 1 -r cli. Mostre-me a saída completa e diga-me o código de saída.

O Hermes deve chamar a ferramenta terminal e executar:

apidog run -t 605067 -e 1629989 -n 1 -r cli

O reporter -r cli mostra a execução passo a passo no terminal, incluindo requisições, respostas e asserções.

Dependendo da configuração do Hermes, você pode ver um prompt de aprovação antes da execução. Para um cenário somente leitura contra staging, esse é um comando normalmente seguro para permitir.

Passo 4: valide pelo código de saída

Não valide apenas pelo texto do resumo. Valide pelo código de saída.

A regra é:

exit code 0     => todas as asserções passaram
exit code != 0  => houve falha

Se o Hermes disser que os testes passaram, mas o código de saída for diferente de 0, considere a execução falha.

Esse comportamento torna o apidog run útil tanto para o loop local do Hermes quanto para CI/CD.

Para consultar flags disponíveis, peça ao Hermes para executar:

apidog run --help

O guia completo da CLI do Apidog documenta os principais flags, incluindo reporters como:

cli
html
json
junit

Passo 5: integre o teste ao loop de edição do Hermes

O objetivo é fazer o Hermes executar o teste sem você precisar repetir o comando toda vez.

Um fluxo prático fica assim:

O Hermes altera um handler, rota ou formato de resposta.
Ele identifica, via AGENTS.md, que deve executar o cenário do Apidog.
Ele roda:

apidog run -t 605067 -e 1629989 -n 1 -r cli

Ele lê o código de saída.
Se for 0, continua.
Se for diferente de 0, lê a asserção com falha, corrige o código e executa novamente.

Isso transforma o cenário de API em parte do mesmo ciclo de desenvolvimento que testes unitários:

editar código -> executar teste -> ler falha -> corrigir -> executar novamente

Esse é o modelo de “delegar e verificar”: o Hermes executa o comando, mas você mantém a regra objetiva de validação pelo código de saída.

Para execuções longas, pastas grandes ou múltiplas iterações, a ferramenta terminal do Hermes aceita background=true. Assim, o Hermes pode iniciar a execução em segundo plano, continuar trabalhando e consultar o resultado depois.

Para padrões mais amplos, veja também:

Opcional: conecte o servidor Apidog MCP

A CLI permite ao Hermes executar testes. O servidor Apidog MCP permite que ele leia a especificação da API enquanto escreve código.

Os dois recursos se complementam:

MCP fornece o contrato da API ao Hermes.
CLI valida a implementação contra cenários reais.

O Hermes suporta o Model Context Protocol, ou MCP, nativamente.

Edite o arquivo:

~/.hermes/config.yaml

Adicione uma entrada em mcp_servers:

mcp_servers:
  apidog:
    command: "npx"
    args: ["-y", "apidog-mcp-server@latest", "--project=YOUR_PROJECT_ID"]
    env:
      APIDOG_ACCESS_TOKEN: "YOUR_ACCESS_TOKEN"

Depois de salvar, dentro do Hermes, execute:

/reload-mcp

Ou reinicie o Hermes.

Na inicialização, o Hermes descobre os servidores MCP e registra suas ferramentas com namespace, como:

mcp_apidog_<tool>

Assim, o agente pode consultar a especificação da API durante o raciocínio normal.

Para a configuração completa, incluindo ID do projeto e token, consulte o guia do servidor Apidog MCP.

Para uma versão empacotada desse loop, veja o guia da CLI do Apidog com Habilidades Claude.

Do loop local para a CI

Depois que o Hermes executa o cenário localmente e valida pelo código de saída, você tem o mesmo comando que pode ser usado na pipeline.

A diferença é a autenticação:

localmente: login já armazenado via apidog login;
na CI: token passado como segredo mascarado.

Você pode pedir ao Hermes para criar o passo de CI:

Escreva um passo do GitHub Actions que instale o apidog-cli e execute apidog run -t 605067 -e 1629989 -r junit, lendo o token de acesso de um segredo do repositório chamado APIDOG_ACCESS_TOKEN.

Um exemplo de estrutura seria:

- name: Install Apidog CLI
  run: npm install -g apidog-cli

- name: Run Apidog API tests
  run: apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit
  env:
    APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Os detalhes de segredos, reporters e validação por código de saída estão em CLI do Apidog no GitHub Actions.

Com isso, o mesmo comando passa a existir em três lugares:

no seu terminal;
no loop do Hermes;
na CI.

Todos usando o mesmo critério objetivo: o código de saída.

Armadilhas comuns

O Hermes ignora o bloco de contexto

Verifique se o arquivo está com o nome correto:

AGENTS.md

ou:

CLAUDE.md

Também confirme que ele está no diretório onde o Hermes foi iniciado.

Se necessário, reinicie a sessão para forçar uma nova leitura do contexto.

O Hermes apenas sugere o comando, mas não executa

O Hermes executa comandos pela ferramenta terminal, geralmente atrás de uma camada de aprovação.

Se houver uma execução pendente, aprove-a. Se a configuração estiver bloqueando comandos de terminal, permita pelo menos:

apidog run

`apidog whoami` mostra que você não está autenticado

O login é armazenado na máquina, não no Hermes.

Faça login manualmente:

apidog login --with-token

Depois peça ao Hermes para confirmar:

apidog whoami

Não cole tokens no chat se isso puder expô-los em logs ou histórico.

O Hermes inventa um flag

Se você vir erro de opção desconhecida, o Hermes provavelmente inferiu um flag inexistente.

Peça para ele consultar a ajuda:

apidog run --help

Depois atualize o AGENTS.md com o flag correto.

O Hermes relata sucesso em uma execução com falha

Essa é a falha mais importante a evitar.

Sempre peça o código de saída e compare:

0    => sucesso
!= 0 => falha

Quando o resumo textual e o código de saída discordarem, confie no código de saída.

Conclusão

A configuração prática é simples:

Adicione um bloco no AGENTS.md com o comando apidog run.
Remova tokens do arquivo de contexto.
Instrua o Hermes a executar o comando pela ferramenta terminal.
Valide sempre pelo código de saída.
Opcionalmente, conecte o servidor Apidog MCP em ~/.hermes/config.yaml.

Você continua criando cenários visualmente no Apidog. O Hermes apenas executa esses cenários e usa o resultado para orientar o loop de implementação.

A partir daqui, você pode levar o mesmo comando para sua pipeline com a CLI do Apidog no GitHub Actions ou consultar todos os flags no guia completo.

Perguntas frequentes

Preciso de um plugin Hermes para usar a CLI do Apidog?

Não. O Hermes executa comandos de shell pela ferramenta terminal, então ele pode chamar apidog run diretamente.

A configuração específica do Hermes é o bloco em AGENTS.md. O servidor MCP é opcional.

Onde coloco as instruções que ensinam o fluxo de trabalho ao Hermes?

Coloque em um arquivo de contexto que o Hermes carrega na inicialização, como:

AGENTS.md

ou:

CLAUDE.md

O local recomendado é a raiz do repositório.

Como garanto que o Hermes não simule um teste aprovado?

Peça sempre o código de saída.

apidog run retorna 0 somente quando todas as asserções passam. Se o texto do Hermes disser “passou”, mas o código de saída for diferente de 0, considere falha.

Como conecto o servidor Apidog MCP ao Hermes?

Adicione uma entrada mcp_servers em:

~/.hermes/config.yaml

Use o comando apidog-mcp-server com o ID do projeto e o token. Depois execute:

/reload-mcp

Ou reinicie o Hermes.

O guia do servidor Apidog MCP cobre os detalhes de projeto e autenticação.

Isso funciona da mesma forma em outros agentes de codificação de IA?

A CLI é a mesma. O que muda é como você instrui o agente.

No Hermes, use AGENTS.md e a ferramenta terminal. Outros agentes podem usar outros arquivos de instrução ou mecanismos de contexto.

A instalação e autenticação continuam iguais, então o guia de instalação também se aplica.

Vegeta Teste de Carga: Tutorial de HTTP com Taxa Constante

Lucas — Mon, 06 Jul 2026 09:08:46 +0000

Você quer medir como sua API se comporta exatamente a 500 requisições por segundo, não “o mais rápido que N threads conseguirem enviar”. A maioria das ferramentas de carga fixa a concorrência e deixa a taxa variar. O Vegeta faz o inverso: você define a taxa, e ele tenta enviar esse volume de requisições por segundo independentemente da velocidade de resposta do servidor. Isso importa quando você precisa validar throughput, latência e SLOs sob uma carga-alvo.

Experimente o Apidog hoje

O que é Vegeta

Vegeta é uma ferramenta de teste de carga HTTP via linha de comando, escrita em Go. Também pode ser usada como biblioteca Go, mas este guia foca na CLI.

A ideia principal é simples:

você define uma taxa constante de requisições, e o Vegeta tenta manter esse ritmo durante todo o teste.

Exemplo: “envie 100 requisições por segundo por 30 segundos”. Se o servidor ficar lento, o Vegeta continua emitindo novas requisições conforme o cronograma, em vez de esperar as anteriores terminarem.

Isso cria um modelo de carga aberto, mais próximo de tráfego real: usuários chegam em seu próprio ritmo; eles não esperam seu endpoint lento terminar para que o próximo usuário apareça.

Carga baseada em taxa vs. baseada em concorrência

A diferença prática é esta:

ferramentas baseadas em concorrência fixam usuários virtuais, threads ou workers;
ferramentas baseadas em taxa fixam a quantidade de requisições por segundo.

Em um modelo baseado em concorrência, cada worker geralmente executa um loop:

enviar requisição -> aguardar resposta -> enviar próxima requisição

Se o servidor fica lento, o loop demora mais. Como consequência, a taxa real de requisições cai. A ferramenta “recua” sem você perceber.

Em um modelo baseado em taxa, como no Vegeta, você fixa a taxa de chegada. Se o servidor não acompanha, as requisições começam a se acumular, a latência sobe e os erros aparecem no relatório.

Use cada modelo para perguntas diferentes:

Pergunta	Modelo mais adequado
Quantos usuários simultâneos minha API suporta?	Concorrência
O que acontece com 2.000 requisições por segundo?	Taxa
Em qual RPS a latência começa a degradar?	Taxa
Como duas builds se comportam sob a mesma carga?	Taxa

Para uma visão mais ampla do ecossistema, veja as principais ferramentas de teste de carga de API.

Instalar Vegeta

Escolha a opção adequada para seu ambiente.

macOS com Homebrew

brew update && brew install vegeta

Outros gerenciadores de pacotes

# MacPorts
port install vegeta

# Arch Linux
pacman -S vegeta

# FreeBSD
pkg install vegeta

Compilar a partir do código-fonte

Com Go instalado:

git clone https://github.com/tsenart/vegeta
cd vegeta
make vegeta

Você também pode baixar um binário pré-compilado pela página de releases do GitHub.

Confirme a instalação:

vegeta --help

O pipeline principal

O Vegeta foi desenhado para funcionar bem com pipes Unix:

echo "GET http://localhost:8080/" | vegeta attack -duration=5s -rate=100 | vegeta report

Leia o comando da esquerda para a direita:

echo escreve um alvo HTTP: método e URL.
vegeta attack lê o alvo pela entrada padrão e dispara 100 requisições por segundo por 5s.
vegeta report lê os resultados e imprime um resumo.

Esse teste gera aproximadamente:

100 req/s * 5s = 500 requisições

A flag -rate aceita requisições por unidade de tempo:

-rate=100       # 100 requisições por segundo
-rate=100/1s    # equivalente
-rate=50/500ms  # 50 requisições a cada 500 ms

Use -rate=0 apenas quando quiser remover o limite e enviar o máximo possível. Isso muda o tipo de teste: deixa de ser uma carga constante controlada e vira um teste de throughput máximo.

Como ler o relatório

Um relatório de texto se parece com isto:

Requests      [total, rate, throughput]  500, 100.20, 100.18
Duration      [total, attack, wait]      4.991s, 4.990s, 1.2ms
Latencies     [min, mean, 50, 90, 95, 99, max]  412us, 1.3ms, 1.1ms, 1.9ms, 2.4ms, 5.1ms, 12ms
Bytes In      [total, mean]              128500, 257.00
Bytes Out     [total, mean]              0, 0.00
Success       [ratio]                    100.00%
Status Codes  [code:count]               200:500
Error Set:

Na prática, avalie nesta ordem:

Latencies
- 50: mediana.
- 95: 95º percentil.
- 99: cauda lenta. Se esse valor está alto, usuários reais sentirão o problema.
Success [ratio]
- Deve estar próximo de 100% para uma carga suportada.
Status Codes
- Verifique se há 5xx, 429 ou outros códigos inesperados.
Error Set
- Deve estar vazio em uma execução saudável.

Uma média boa não compensa um percentil 99 ruim. Em APIs, a cauda costuma ser onde os incidentes começam.

Salve os resultados antes de gerar relatórios

Para testes rápidos, enviar direto para vegeta report é suficiente. Para qualquer execução que você queira comparar, versionar ou anexar ao CI, salve o arquivo binário de resultados.

echo "GET http://localhost:8080/" | \
  vegeta attack -duration=10s -rate=200 -output=results.bin

Depois gere relatórios a partir do arquivo.

Relatório de texto

vegeta report results.bin

JSON para dashboard ou automação

vegeta report -type=json results.bin > metrics.json

Histograma de latência

vegeta report -type='hist[0,2ms,5ms,10ms,25ms,100ms]' results.bin

O histograma mostra quantas requisições caíram em cada faixa de latência. É útil para identificar se a maioria das respostas está concentrada em uma faixa pequena ou se há dispersão significativa.

Criar um arquivo de alvos

APIs reais raramente são testadas com um único GET. Coloque seus endpoints em um arquivo e passe-o com -targets.

Crie targets.txt:

GET http://localhost:8080/api/users

POST http://localhost:8080/api/users
Content-Type: application/json
@./payload.json

GET http://localhost:8080/api/users/42

Crie o corpo da requisição em payload.json:

{ "name": "Ada", "role": "engineer" }

Execute:

vegeta attack -targets=targets.txt -rate=50 -duration=30s | vegeta report

Regras do formato:

a primeira linha de cada alvo é MÉTODO URL;
cabeçalhos vêm logo abaixo, no formato Chave: Valor;
uma linha iniciada com @ referencia um arquivo usado como corpo da requisição;
uma linha em branco separa um alvo do próximo;
linhas iniciadas com # são comentários.

O Vegeta percorre os alvos em ordem e repete a lista até a duração terminar.

Adicionar autenticação

Para adicionar cabeçalhos globais, use -header.

Exemplo com Bearer Token:

vegeta attack -targets=targets.txt -rate=50 -duration=30s \
  -header="Authorization: Bearer $TOKEN" | vegeta report

Você também pode adicionar outros cabeçalhos:

vegeta attack -targets=targets.txt -rate=50 -duration=30s \
  -header="Authorization: Bearer $TOKEN" \
  -header="X-Request-Source: load-test" | vegeta report

Usar formato JSON para alvos

Para geração programática, o Vegeta também aceita alvos em JSON. Cada linha é um objeto JSON.

Exemplo:

{"method": "GET", "url": "http://localhost:8080/api/users"}
{"method": "POST", "url": "http://localhost:8080/api/users", "header": {"Content-Type": ["application/json"]}, "body": "eyJuYW1lIjoiQWRhIn0="}

Execute com -format=json:

vegeta attack -format=json -targets=targets.json -rate=100 -duration=30s | vegeta report

O campo body deve estar em base64.

Esse formato funciona bem quando você gera alvos em tempo real. Para reduzir uso de memória em streams grandes, use -lazy.

generate-targets | vegeta attack -format=json -lazy -rate=100 -duration=30s | vegeta report

Gerar gráficos e comparar execuções

Um único número pode esconder degradações no meio do teste. Para visualizar latência ao longo do tempo, use vegeta plot.

vegeta attack -targets=targets.txt -rate=100 -duration=60s | \
  vegeta plot > plot.html

Abra plot.html no navegador. Você verá uma série temporal da latência durante a execução.

Para comparar diferentes níveis de carga:

vegeta attack -rate=50  -duration=30s -targets=targets.txt -output=50qps.bin
vegeta attack -rate=100 -duration=30s -targets=targets.txt -output=100qps.bin

vegeta plot 50qps.bin 100qps.bin > compare.html

Em ambientes sem interface gráfica, exporte CSV:

vegeta encode -to=csv results.bin > results.csv

Encontrar o limite de capacidade

Um fluxo simples para encontrar o ponto de degradação:

for rate in 50 100 200 400 800; do
  echo "Executando teste com ${rate} req/s"

  vegeta attack \
    -targets=targets.txt \
    -rate=${rate} \
    -duration=30s \
    -output="results-${rate}.bin"

  vegeta report "results-${rate}.bin" > "report-${rate}.txt"
done

Depois compare:

grep -E "Requests|Latencies|Success|Status Codes" report-*.txt

Procure o primeiro ponto em que:

o percentil 95 ou 99 sobe de forma relevante;
a taxa de sucesso cai;
aparecem códigos 5xx, 429 ou timeouts;
o throughput fica abaixo da taxa solicitada.

Esse ponto indica que a API começou a não acompanhar a carga desejada.

Quando usar o Vegeta

Use Vegeta quando a pergunta for sobre taxa, latência e capacidade:

medir throughput e latência em um RPS específico;
descobrir em qual taxa a latência começa a subir;
comparar duas builds sob carga idêntica;
comparar duas configurações de infraestrutura;
automatizar testes de carga em shell ou CI;
gerar relatórios simples sem depender de GUI.

Ele é uma ferramenta focada. Envia requisições HTTP em uma taxa definida e mede como o servidor responde.

Ele não é ideal para:

jornadas complexas com múltiplos passos e ramificações;
simular navegação realista de usuários;
validar regras de negócio;
verificar schemas ou campos específicos no corpo da resposta.

Esse foco é positivo: mantém os testes repetíveis, scriptáveis e fáceis de interpretar.

Se estiver comparando alternativas, veja também os guias sobre teste de carga k6 e teste de carga JMeter. Para conceitos e métricas, comece pelo tutorial de teste de desempenho de API.

Onde o teste funcional entra

Teste de carga responde:

“A API é rápida o suficiente sob esta carga?”

Ele não responde:

“A API está retornando os dados corretos?”

Uma execução do Vegeta pode mostrar 100% de respostas 200 enquanto o endpoint retorna o usuário errado, um preço desatualizado ou um JSON inválido. Para uma ferramenta de carga, isso ainda pode parecer sucesso.

Correção exige outro tipo de validação:

status esperado;
cabeçalhos esperados;
campos JSON;
schema;
regras de negócio;
encadeamento entre requisições.

Isso é teste funcional, e deve acontecer antes ou junto dos testes de carga.

É aqui que o Apidog complementa o Vegeta. No Apidog, você cria cenários funcionais com asserções sobre status, cabeçalhos e campos JSON, encadeia requisições e usa dados externos. Depois, o Vegeta mede se os caminhos já validados continuam rápidos sob centenas ou milhares de requisições por segundo.

Executar testes funcionais no CI com Apidog CLI

O Apidog oferece uma CLI headless para executar cenários funcionais em pipelines.

Instale com Node:

npm install -g apidog-cli

Execute um cenário, pasta ou suíte salvo por ID:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioOrSuiteId> \
  -e <environmentId> \
  -r cli,html,junit

Parâmetros principais:

-t: ID do cenário, pasta ou suíte;
-e: ID do ambiente;
-r: formatos de relatório, como cli, html, json e junit.

A saída junit funciona bem em dashboards de CI.

Veja o tutorial da linha de comando da CLI do Apidog e o guia de pipeline CI/CD para um fluxo passo a passo.

Um pipeline saudável fica assim:

1. Executar testes funcionais
2. Bloquear o pipeline se asserções falharem
3. Executar Vegeta nos endpoints aprovados
4. Publicar relatórios de carga

Perguntas frequentes

Vegeta suporta requisições POST com corpo?

Sim. No arquivo de alvos HTTP, defina o método e a URL na primeira linha, adicione Content-Type e referencie o corpo com @./payload.json.

Exemplo:

POST http://localhost:8080/api/users
Content-Type: application/json
@./payload.json

No formato JSON, use method, url e body em base64.

O que `-rate=0` faz?

Remove o limite de taxa e envia requisições tão rápido quanto workers e conexões permitirem.

Isso é útil para medir throughput máximo, mas não para um teste controlado de taxa constante. Para medições repetíveis, defina uma taxa explícita, como -rate=100.

Como leio os percentis de latência?

A linha Latencies mostra mínimo, média, mediana, percentis 90, 95, 99 e máximo.

Priorize:

95: comportamento lento para uma parte relevante dos usuários;
99: cauda extrema;
max: pior caso observado.

A média pode esconder problemas, então não use apenas mean.

Vegeta valida se minha API retorna dados corretos?

Não. Vegeta mede throughput, latência, códigos de status e erros de transporte. Ele não valida corpo da resposta, schema ou regras de negócio.

Combine Vegeta com uma ferramenta de teste funcional para validar correção antes de medir performance.

Como executo Vegeta em CI?

Como ele é um binário de linha de comando, basta adicionar uma etapa shell.

Exemplo:

vegeta attack \
  -targets=targets.txt \
  -rate=100 \
  -duration=30s \
  -output=results.bin

vegeta report results.bin
vegeta report -type=json results.bin > metrics.json

Publique results.bin, metrics.json e o relatório textual como artefatos do build.

Para evitar medir endpoints quebrados, rode primeiro um gate funcional, como a CLI do Apidog, e só depois execute a etapa de carga.

Claude Fable 5 Sem Restrições

Lucas — Mon, 06 Jul 2026 08:21:25 +0000

Se você pesquisou por “Claude Fable 5 sem restrições”, provavelmente está tentando resolver um destes dois cenários: confirmar se o modelo voltou após a suspensão ou encontrar uma versão “sem censura” com filtros desativados. A resposta curta: o acesso ao Fable 5 voltou, mas o classificador de segurança continua ativo e não pode ser desligado.

Experimente o Apidog hoje

A restrição que impedia o uso do claude-fable-5 foi removida. O modelo ficou suspenso por 19 dias sob controles de exportação dos EUA. Esses controles foram suspensos em 30 de junho de 2026, e o Fable 5 voltou em 1º de julho. Hoje, ele pode ser usado novamente via API, aplicativos Claude e principais plataformas de nuvem.

O que “Fable 5 sem restrições” realmente significa

Existem duas “restrições” diferentes sendo confundidas.

A primeira foi a suspensão por controle de exportação. Em 12 de junho de 2026, o Departamento de Comércio dos EUA restringiu o Fable 5 e o Mythos 5 após os modelos serem associados a abusos de cibersegurança impulsionados por jailbreaks. O acesso global foi interrompido. Essa foi a restrição que tornou o modelo inutilizável — e essa foi suspensa.

Para a linha do tempo completa, veja: por que o Fable 5 foi desativado.

A segunda é o classificador de segurança do modelo reimplantado. Ele não é um bloqueio regional, uma configuração de conta ou um cabeçalho de API. É parte do comportamento atual do Fable 5.

Na prática:

Você pode usar o Fable 5 novamente.
Você pode integrá-lo via API e nuvens compatíveis.
Você pode configurar limites, créditos e fallbacks.
Você não pode desativar o classificador de segurança.

Se você quer entender o retorno do modelo em mais detalhes, veja: Fable 5 está de volta.

A restrição que foi removida: suspensão de exportação

Linha do tempo operacional:

12 de junho de 2026: Fable 5 e Mythos 5 são suspensos. O acesso global é interrompido.
30 de junho de 2026: os controles de exportação são suspensos após reforço das salvaguardas.
1º de julho de 2026: Fable 5 volta a ficar disponível globalmente.

A partir de 6 de julho de 2026, o Fable 5 está novamente disponível em:

aplicativos Claude;
Claude Code;
API da Anthropic;
AWS Bedrock;
Google Vertex AI;
Microsoft Foundry.

A disponibilidade pode variar por conta e região. Antes de migrar produção, valide se o modelo aparece no catálogo da sua plataforma.

Se você mudou suas cargas de trabalho para um modelo alternativo durante a suspensão, não volte apenas trocando o nome do modelo. Faça uma migração controlada. Veja o guia: como voltar para o Fable 5.

O que continua ativo: classificador de segurança

O Fable 5 que voltou não é o mesmo binário que foi suspenso. A Anthropic o reimplantou com um novo classificador de segurança.

Quando uma requisição aciona esse classificador — por exemplo, padrões ligados a operações cibernéticas ofensivas, biologia adjacente a armas biológicas ou extração estilo destilação — o modelo não retorna apenas um erro rígido. Ele pode redirecionar a chamada para o Opus 4.8, que responde no lugar do Fable 5.

Segundo a Anthropic, o classificador detecta o jailbreak sinalizado em mais de 99% dos casos. Para entender a mecânica de roteamento, veja: como funcionam as salvaguardas de segurança do Fable 5.

O ponto importante para desenvolvedores:

Trate o redirecionamento como comportamento esperado da API, não como falha inesperada.

Como usar o Fable 5 com o mínimo de atrito legítimo

Você não pode remover a camada de segurança. Mas pode reduzir outros gargalos: acesso, limites, faturamento, fallbacks e prompts.

1. Use a API para controle total da integração

A API é a rota mais direta para usar o Fable 5 em aplicações próprias. Ela evita limites de sessão típicos dos aplicativos e permite controlar:

modelo;
tokens máximos;
mensagens;
fallback;
tratamento de resposta;
observabilidade;
custos.

Exemplo simplificado:

response = client.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Resuma esta especificação de API em tópicos técnicos."
        }
    ],
)

Para um fluxo completo de requisição, veja: como usar a API do Claude Fable 5.

Para comparar API, aplicativos Claude e planos, veja: como acessar o Fable 5.

2. Planeje limites de taxa

Na prática, muitos times não batem no classificador de segurança; batem em rate limits.

Se sua aplicação faz chamadas em lote, análise de documentos, geração de código ou automações internas, valide:

requisições por minuto;
tokens de entrada por minuto;
tokens de saída por minuto;
concorrência;
comportamento de retry;
filas e backoff.

Exemplo de retry com backoff simples:

import time

def call_with_retry(fn, retries=3):
    for attempt in range(retries):
        try:
            return fn()
        except RateLimitError:
            if attempt == retries - 1:
                raise
            time.sleep(2 ** attempt)

Os níveis e limites são explicados em: Limites de taxa do Fable 5 explicados.

Se o limite está nos aplicativos Claude, não na API, veja: abordagem de prompt perfeito para estender seu uso.

3. Prepare-se para créditos de uso em 7 de julho

Até 7 de julho, o Fable 5 está incluído em até 50% dos limites semanais de uso nos planos Pro, Max, Team e Enterprise selecionados.

Depois de 7 de julho, o uso contínuo passa para um modelo de créditos. Assentos Standard Enterprise não recebem a cota incluída e vão direto para créditos.

Taxas relatadas após 7 de julho:

US$ 10 por milhão de tokens de entrada
US$ 50 por milhão de tokens de saída

Confirme os valores na sua página de faturamento antes de planejar custos de produção.

Para workloads com alto volume, monitore:

custo_estimado = tokens_entrada * taxa_entrada + tokens_saida * taxa_saida

E registre por chamada:

modelo usado;
tokens de entrada;
tokens de saída;
se houve fallback;
custo estimado;
endpoint/plataforma.

Detalhes: a mudança de créditos de uso de 7 de julho explicada.

4. Trate fallbacks explicitamente

Como o classificador pode redirecionar chamadas para o Opus 4.8, sua integração deve estar pronta para receber uma resposta de outro modelo.

Na API da Anthropic, use o parâmetro beta fallbacks:

response = client.beta.messages.create(
    model="claude-fable-5",
    betas=["server-side-fallback-2026-06-01"],
    fallbacks=[{"model": "claude-opus-4-8"}],
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Summarize this API spec."
        }
    ],
)

A string beta deve ser exatamente:

server-side-fallback-2026-06-01

Antes de colocar em produção, valide na documentação atual do Claude, pois parâmetros beta podem mudar.

Também considere que uma resposta redirecionada é faturada com as taxas do Opus 4.8, não do Fable 5.

Checklist para implementação:

[ ] detectar qual modelo respondeu;
[ ] registrar fallback em logs;
[ ] calcular custo com base no modelo real;
[ ] testar respostas normais e redirecionadas;
[ ] garantir que parsers e validações aceitem ambos os caminhos;
[ ] adicionar alertas para aumento incomum de fallbacks.

Disponibilidade do parâmetro:

API da Anthropic: suporte via fallbacks;
Plataforma Claude na AWS: suporte via fallbacks;
Bedrock, Vertex e Foundry: tratamento via middleware do lado do cliente;
API de Lotes de Mensagens: tratamento via middleware do lado do cliente.

Guia completo: como lidar com as recusas do Fable 5.

5. Escreva prompts claros e compatíveis com política

Prompts ambíguos perto de temas sensíveis podem aumentar falsos positivos.

Prefira prompts com:

objetivo explícito;
contexto legítimo;
escopo técnico claro;
restrições de segurança;
formato esperado de saída.

Exemplo ruim:

Analise este exploit e melhore.

Exemplo melhor para um caso legítimo de defesa:

Estou revisando um relatório interno de segurança defensiva.
Explique, em alto nível, quais classes de vulnerabilidade aparecem no texto abaixo,
sem fornecer instruções exploráveis, payloads ou passos ofensivos.
Retorne a resposta em tópicos para priorização de correção.

Isso não contorna política. Apenas reduz ambiguidade quando a tarefa real é benigna.

Cuidado com “Fable 5 sem censura” ou “com jailbreak”

Se você encontrar um site, Discord, extensão ou revendedor anunciando Fable 5 “sem censura”, “com jailbreak” ou “sem limites”, não use.

Não existe produto legítimo com o classificador desativado.

Normalmente, essas ofertas caem em uma destas categorias:

revenda enganosa: acesso normal ao Fable 5 com marketing falso;
modelo diferente: outro modelo sendo vendido como se fosse Fable 5;
proxy irregular: chamadas feitas por chaves roubadas, compartilhadas ou em violação de termos.

Riscos práticos:

vazamento de prompts;
exposição de dados internos;
banimento de conta;
cobrança indevida;
respostas de modelo diferente do anunciado;
ausência de garantias de privacidade.

As formas legítimas de reduzir atrito são:

usar a API;
subir níveis de rate limit;
planejar créditos;
configurar fallbacks;
testar regressões;
escrever prompts claros.

Não há uma “quarta porta” confiável.

Teste de regressão na integração reativada

Se você está voltando workloads para o Fable 5, trate isso como mudança de contrato.

Antes da suspensão, uma chamada podia sempre retornar do Fable 5. Agora, dependendo da entrada, ela pode retornar via Opus 4.8.

Teste perguntas como:

Meu parser assume um único modelo?
Meu sistema registra o modelo real da resposta?
O cálculo de custo considera fallback?
O fluxo de streaming continua funcionando?
O frontend mostra erro quando não deveria?
O retry duplica chamadas redirecionadas?
O pipeline de CI cobre o caminho de fallback?

No Apidog, você pode modelar o contrato da requisição do Fable 5, simular resposta normal e resposta redirecionada para Opus, e validar se sua integração lida com ambos os cenários.

Exemplo de cenários de teste:

Cenário 1: resposta normal do Fable 5
- model: claude-fable-5
- status: 200
- tokens: dentro do esperado
- parser: sucesso

Cenário 2: fallback para Opus 4.8
- model: claude-opus-4-8
- status: 200
- custo: calculado como Opus
- parser: sucesso
- log: fallback=true

A Apidog CLI permite executar a mesma suíte em CI, garantindo que cada deploy valide o contrato antes de chegar à produção.

Importante: o Apidog não remove restrições do Fable 5, não altera o classificador e não desbloqueia nada. Ele ajuda a testar o comportamento da API que você já usa, incluindo redirecionamento e fallback.

Para uma lista mais ampla do que validar, veja: mudanças na API do Fable 5 e Mythos.

Perguntas Frequentes

Posso usar o Claude Fable 5 novamente a partir de julho de 2026?

Sim. A suspensão do controle de exportação foi suspensa em 30 de junho de 2026, e o modelo retornou em 1º de julho. Ele está disponível na API, nos aplicativos Claude, Claude Code e nas principais nuvens, sujeito à implantação por conta e região.

Existe uma versão sem censura do Fable 5?

Não. O classificador de segurança é integrado ao modelo reimplantado e não pode ser desativado. Qualquer Fable 5 “sem censura” ou “com jailbreak” sendo vendido é acesso normal mal rotulado, outro modelo ou um proxy que viola termos.

Por que o filtro de segurança não pode ser desativado?

Porque o uso indevido que ele impede foi o motivo da suspensão. O classificador é a condição que permitiu o retorno do Fable 5. Removê-lo recriaria o problema original.

O que acontece depois de 7 de julho de 2026?

A cota incluída do Fable 5, de até 50% dos limites semanais em planos selecionados, termina. Depois disso, o uso contínuo passa a funcionar com créditos. Confirme as taxas exatas na sua página de faturamento.

Como faço meu aplicativo continuar funcionando quando o Fable 5 redireciona uma requisição?

Trate o redirecionamento explicitamente. Na API da Anthropic, use o parâmetro beta fallbacks com server-side-fallback-2026-06-01 e configure claude-opus-4-8 como fallback. Em Bedrock, Vertex e Foundry, implemente middleware do lado do cliente. Depois, rode testes de regressão para os dois caminhos: resposta normal e resposta redirecionada.

O Que É ConnectRPC? O Protocolo Connect

Lucas — Mon, 06 Jul 2026 08:12:26 +0000

Se você já tentou chamar um serviço gRPC diretamente de um navegador, encontrou a limitação principal: navegadores não conseguem controlar “trailers” HTTP, então não conseguem falar gRPC puro. O caminho tradicional é colocar um proxy, como Envoy, entre o navegador e o backend. O ConnectRPC remove essa etapa ao permitir APIs baseadas em Protobuf que podem ser chamadas por navegadores, por curl e por clientes gRPC.

Experimente o Apidog hoje

Neste guia, você verá o que é o ConnectRPC, qual problema ele resolve, como ele se compara a gRPC, gRPC-Web e REST, como uma requisição Connect funciona via HTTP e como testar endpoints Connect e gRPC com ferramentas comuns de API.

O que é o ConnectRPC

ConnectRPC é uma família de bibliotecas para criar APIs HTTP compatíveis com navegadores e com gRPC usando Protocol Buffers.

O fluxo básico é:

Definir o contrato em um arquivo .proto.
Gerar código com buf.
Implementar os handlers do serviço.
Expor o serviço como handlers HTTP.

O Connect cuida de roteamento, serialização, compressão e geração de clientes.

O projeto foi criado pela Buf, a empresa por trás das ferramentas buf para Protobuf, e hoje é um projeto sandbox da Cloud Native Computing Foundation (CNCF). Isso faz com que o Connect se encaixe bem em fluxos “schema-first” já usados por equipes que trabalham com Protobuf.

Um servidor ConnectRPC pode falar três protocolos ao mesmo tempo:

gRPC: compatibilidade com clientes gRPC, incluindo streaming e trailers.
gRPC-Web: suporte para clientes gRPC-Web sem exigir um proxy separado.
Connect: protocolo HTTP próprio, mais simples de chamar de navegadores e ferramentas HTTP.

Na prática, isso significa que o mesmo backend pode atender:

um frontend TypeScript no navegador;
um serviço Go usando gRPC;
uma chamada manual com curl;
uma ferramenta de teste de API.

O problema que o Connect resolve

gRPC é eficiente e fortemente tipado, mas depende de características que não são expostas diretamente ao JavaScript no navegador, especialmente os HTTP trailers.

Por isso, um navegador não consegue atuar como cliente gRPC nativo. A solução comum é usar gRPC-Web junto com um proxy de tradução, como Envoy, entre o frontend e o backend gRPC.

Essa arquitetura funciona, mas adiciona complexidade:

mais um componente para configurar;
mais um ponto de falha;
mais um salto de rede para depurar;
mais configuração para ambientes locais, staging e produção.

O Connect usa outra abordagem. O protocolo Connect roda sobre HTTP padrão, então chamadas unárias podem ser feitas diretamente pelo navegador ou por qualquer cliente HTTP.

Você mantém:

contrato Protobuf;
geração de código;
tipagem forte;
interoperabilidade com gRPC.

Mas remove a necessidade de proxy apenas para permitir chamadas do navegador.

Connect vs gRPC vs gRPC-Web vs REST

As quatro abordagens resolvem problemas parecidos, mas com trade-offs diferentes.

gRPC

gRPC usa Protobuf sobre HTTP/2, com framing binário e trailers HTTP. É eficiente e suporta os quatro modos de streaming, mas não é simples de chamar diretamente de um navegador ou de um terminal.

Se quiser revisar a camada de transporte, veja como gRPC e HTTP/2 funcionam juntos.

gRPC-Web

gRPC-Web adapta gRPC para navegadores. Ele continua baseado em Protobuf e normalmente é usado com um proxy que traduz o tráfego para um backend gRPC nativo.

Veja também: o que é gRPC-Web.

Connect

Connect mantém o modelo de serviço do gRPC e o contrato Protobuf, mas usa um protocolo HTTP mais simples para chamadas unárias.

Uma chamada Connect pode usar:

HTTP/1.1, HTTP/2 ou HTTP/3;
corpo JSON ou Protobuf;
status HTTP real;
caminhos derivados diretamente do schema Protobuf.

Isso torna uma chamada Connect tão fácil de inspecionar quanto uma chamada REST.

REST

REST é orientado a recursos e amplamente suportado. É simples de chamar, depurar e integrar, mas não exige tipagem forte nem geração de código por padrão.

Se você está avaliando os dois modelos, veja gRPC vs REST.

Resumo prático:

Use gRPC quando precisar de alto desempenho, streaming completo e controle entre serviços.
Use gRPC-Web quando já tiver um backend gRPC e precisar expô-lo para navegadores.
Use Connect quando quiser Protobuf, geração de código e chamadas HTTP fáceis de testar.
Use REST quando compatibilidade universal e simplicidade forem mais importantes que contratos Protobuf.

O Connect se apoia no modelo de método do Protobuf e do gRPC, mas evita partes que navegadores e shells não conseguem lidar bem.

Como uma requisição Connect funciona via HTTP

Uma chamada unária Connect é um POST HTTP comum.

O caminho da URL vem do schema Protobuf no formato:

/<pacote>.<Serviço>/<Método>

Por exemplo, se você tiver:

pacote: greet.v1
serviço: GreetService
método: Greet

O endpoint será:

/greet.v1.GreetService/Greet

Você pode chamar esse método com curl:

curl \
  --header "Content-Type: application/json" \
  --data '{"name": "Jane"}' \
  http://localhost:8080/greet.v1.GreetService/Greet

Resposta:

{"greeting": "Hello, Jane!"}

Não há cliente especial, proxy ou decodificação manual. Para chamadas unárias, o corpo pode ser JSON simples.

O Connect suporta dois tipos de conteúdo para requisições unárias:

application/json: útil durante desenvolvimento e depuração.
application/proto: útil quando você quer payloads binários menores.

Exemplo usando Protobuf binário:

curl \
  --header "Content-Type: application/proto" \
  --data-binary @request.bin \
  http://localhost:8080/greet.v1.GreetService/Greet

Chamadas de streaming usam tipos de conteúdo diferentes:

application/connect+proto
application/connect+json

Nesses casos, cada mensagem é encapsulada em um envelope com:

um byte de sinalização;
quatro bytes de comprimento em big-endian;
a mensagem.

Chamadas unárias não usam esse envelope, por isso mapeiam tão bem para HTTP comum.

Se estiver escolhendo entre formatos de payload, veja Protobuf vs JSON.

Exemplo de contrato Protobuf

Um serviço Connect começa com um arquivo .proto.

Exemplo:

syntax = "proto3";

package greet.v1;

service GreetService {
  rpc Greet(GreetRequest) returns (GreetResponse) {}
}

message GreetRequest {
  string name = 1;
}

message GreetResponse {
  string greeting = 1;
}

A partir desse contrato, você gera:

tipos Protobuf;
interfaces de servidor;
clientes;
handlers Connect.

Geração de código com buf

O ConnectRPC oferece implementações em várias linguagens. Go e TypeScript, para navegador e Node.js, são estáveis e prontas para produção. Swift está disponível para plataformas Apple, Kotlin para JVM e Android, e Python está em beta.

A geração de código é feita com a cadeia de ferramentas buf.

Em um projeto Go, você normalmente usa:

protoc-gen-go para mensagens Protobuf;
protoc-gen-connect-go para handlers e clientes Connect.

Um arquivo buf.gen.yaml lista os plugins usados na geração.

Depois, execute:

buf generate

O resultado inclui estruturas tipadas e código de servidor/cliente.

Em Go, o código gerado integra com net/http, então um handler Connect é um handler HTTP comum. Isso permite montar endpoints Connect ao lado de rotas HTTP existentes.

Testando endpoints Connect com curl

Como chamadas unárias Connect são HTTP simples, comece testando com curl.

Exemplo com JSON:

curl \
  --request POST \
  --header "Content-Type: application/json" \
  --data '{"name": "Jane"}' \
  http://localhost:8080/greet.v1.GreetService/Greet

Verifique:

status HTTP;
corpo da resposta;
headers;
formato do JSON;
mensagens de erro.

Essa etapa é útil para validar se o endpoint está acessível antes de integrar o cliente gerado.

Testando e depurando Connect e gRPC com Apidog

No Apidog, você pode testar uma chamada unária Connect como uma requisição HTTP.

Configure:

método: POST;
URL: http://localhost:8080/greet.v1.GreetService/Greet;
header: Content-Type: application/json;
body:

{"name": "Jane"}

Você recebe a resposta JSON e o status HTTP real, da mesma forma que faria com curl, mas com interface visual, histórico e requisições salvas.

Para revisar os verbos HTTP usados nesse tipo de teste, veja o que são métodos HTTP.

Como um servidor Connect também fala gRPC, você pode testar o lado gRPC do mesmo serviço. O Apidog suporta endpoints gRPC: importe o arquivo .proto, navegue pelos métodos disponíveis e envie uma requisição tipada.

Assim, uma única ferramenta cobre:

chamadas Connect via HTTP;
chamadas gRPC nativas;
depuração manual;
cenários de teste salvos.

Se o foco for gRPC, veja como testar APIs gRPC de forma eficiente.

Automatizando testes em CI

Depois que as chamadas estiverem funcionando, mova os testes para execução automatizada.

Instale o Apidog CLI com Node:

npm install -g apidog-cli

Execute um cenário ou suíte salvo:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioOrSuiteId> \
  -e <environmentId> \
  -r cli,html,junit

O CLI roda em modo headless e pode ser usado em pipelines de CI que executam Node.

Use esse fluxo para:

validar regressões em endpoints Connect;
testar métodos gRPC;
gerar relatórios em HTML ou JUnit;
bloquear deploys quando cenários críticos falharem.

Para um passo a passo completo, veja o tutorial do Apidog CLI para testar uma API pela linha de comando.

Checklist de implementação

Use este roteiro ao adotar ConnectRPC em um serviço:

Defina o contrato em .proto.
Configure buf e os plugins da linguagem usada.
Rode buf generate.
Implemente os handlers gerados.
Registre os handlers no servidor HTTP.
Teste uma chamada unária com curl.
Teste a mesma chamada em uma ferramenta de API.
Se necessário, valide também o lado gRPC importando o .proto.
Salve cenários de teste.
Execute os testes em CI.

Perguntas frequentes

ConnectRPC é o mesmo que gRPC?

Não. ConnectRPC é um framework que implementa três protocolos: gRPC, gRPC-Web e Connect.

Um servidor Connect pode interoperar com clientes e servidores gRPC, mas o protocolo Connect é um protocolo HTTP separado, projetado para ser chamado diretamente por navegadores e ferramentas HTTP.

Ainda preciso de um proxy como Envoy para alcançar um navegador?

Não para o protocolo Connect.

O Connect funciona sobre HTTP padrão, então um navegador pode chamar um servidor Connect sem proxy de tradução. Você só precisa de um proxy como Envoy se estiver fazendo a ponte entre tráfego de navegador e um backend que fala apenas gRPC nativo.

Quais linguagens o ConnectRPC suporta?

Go e TypeScript, para navegador e Node.js, são estáveis e prontas para produção. Swift, Kotlin e Python também estão disponíveis, com Python em beta.

Todas elas geram código a partir do mesmo schema Protobuf.

Qual é a relação entre Connect e buf?

ConnectRPC foi criado pela Buf e usa a cadeia de ferramentas buf para geração de código.

Você executa:

buf generate

com plugins como protoc-gen-connect-go para gerar handlers e clientes a partir dos arquivos .proto.

Posso testar um endpoint Connect com um cliente de API normal?

Sim. Chamadas unárias Connect são requisições HTTP POST com corpo JSON ou Protobuf e status HTTP real.

Você pode usar curl, Apidog ou qualquer cliente HTTP. O Apidog também pode testar o lado gRPC do mesmo servidor importando o arquivo .proto.

DEV Community: Lucas

Como Usar GLM-5.2 Sem Restrições

Em resumo

1. Identifique qual restrição você quer remover

2. Use a API bruta em vez do aplicativo de chat

3. Auto-hospede os pesos abertos

4. Use builds da comunidade sem censura, quando disponíveis

5. Use um provedor ou roteador que permita controlar políticas

6. Teste cada configuração no Apidog antes de implementar

7. Responsabilidade ao remover restrições

Perguntas frequentes

O GLM-5.2 é realmente de código aberto?

A API do GLM-5.2 censura respostas?

Posso executar o GLM-5.2 em um laptop?

O GLM-5.2 possui bloqueio regional?

Karate para Testes de API: Guia Prático da DSL

O que é o Karate

Como funciona: arquivos .feature e karate-config.js

Configurando ambientes com karate-config.js

Exemplo prático: criando um usuário

Asserções e comparação de JSON

Comparação exata

Comparação parcial com contains

Validação de arrays

Testes orientados a dados

Rodando Karate em CI

Opção 1: Maven, Gradle e JUnit 5

Opção 2: jar standalone

Pontos fortes e compensações

Karate vs uma abordagem sem código com Apidog

Como escolher

Perguntas frequentes

Testes de Regressão de API: Como Identificar Erros Críticos Antecipadamente

O que é teste de regressão de API

O que usar como baseline

1. Códigos de status

2. Esquema de resposta

3. Campos-chave

4. Contrato OpenAPI

Exemplo de baseline para um endpoint

Teste manual vs. automatizado

Como construir um conjunto de regressão reutilizável

1. Agrupe por recurso

2. Use variáveis de ambiente

3. Encadeie requisições

4. Use dados para cobrir casos de borda

5. Mantenha o conjunto rápido

Como executar o conjunto na CI

Exemplo com GitHub Actions

Executando com arquivo de dados

Executando testes de um branch específico

Use diferenciação de esquema para detectar quebras antes do deploy

Como o Apidog ajuda nesse fluxo

Fluxo inicial para implementar esta semana

1. Escolha os cinco endpoints mais chamados

2. Crie uma requisição salva por endpoint

3. Adicione um fluxo encadeado

4. Adicione teste orientado a dados

5. Conecte à CI

6. Transforme bugs escapados em testes

FAQ

Como o teste de regressão de API difere do teste de regressão geral?

Com que frequência devo executar o conjunto?

O que devo afirmar para evitar testes frágeis?

Posso executar regressão de API sem escrever código?

Como lidar com mudanças intencionais que quebram compatibilidade?

O que é Flowise? O construtor low-code de código aberto para apps LLM e agentes de IA

O que é o Flowise

Chatflows, agentflows e assistentes

Quando usar um chatflow

Quando usar um agentflow

Quando usar um assistente

Como montar um fluxo no Flowise

Implantando o Flowise

Rodando com npm

Rodando com Docker

Chamando o endpoint de previsão REST

Quando usar low-code e quando preferir code-first

Testando o endpoint de previsão e as APIs do fluxo

1. Teste o endpoint de previsão

Como funciona: arquivos `.feature` e `karate-config.js`

Configurando ambientes com `karate-config.js`

Comparação parcial com `contains`

Fundamentos do `cy.request()`

Usando `cy.request()` para preparar estado antes da UI

`cy.intercept()` para stubbing

`cy.request()` é executado no navegador?

Como testar uma resposta `400` ou `404` sem falhar o teste?

Posso usar `cy.request()` para fazer login antes de um teste de UI?

Qual é a diferença entre `cy.request()` e `cy.intercept()`?

Alavanca 4: Ajuste `effort`, `max_tokens` e `count_tokens`

1. Reduza `output_config.effort`

2. Defina `max_tokens`

3. Use `count_tokens` antes de enviar