A maioria das APIs é construída para desenvolvedores humanos que leem documentações, navegam por exemplos e depuram com rastreamentos de pilha (stack traces). Em 2026, uma parcela crescente do tráfego de API vem de agentes de IA, e eles não interagem com APIs da mesma forma que os humanos.
É assim que redesenhamos a API de IA unificada da TokenLab em torno de um princípio: não tente ser inteligente, seja informativo. Chamamos o resultado de design de API "agent-first", e ele reduziu o desperdício de tokens para nossos usuários em mais de 60%.
Principais conclusões
- O design de API "agent-first" adiciona dicas estruturadas e legíveis por máquina às respostas de erro, para que os agentes de IA possam se autocorrigir sem pesquisas na web ou ajuda humana.
- Sugira alternativas, não faça autocorreção. Campos como
did_you_mean,suggestionseretryablepermitem que os agentes tomem decisões informadas em vez de ter uma decisão tomada por eles. - Cada sugestão é baseada em dados de produção, portanto, modelos offline ou obsoletos nunca aparecem na lista de candidatos.
- Os campos de dica são aditivos e compatíveis com versões anteriores, para que clientes existentes compatíveis com a OpenAI continuem funcionando sem alterações.
O que é design de API "Agent-First"?
O design de API "agent-first" significa estruturar suas respostas, especialmente as respostas de erro, para que um agente de IA possa entender o que deu errado e corrigir sem sair da conversa.
Erro de API tradicional:
{"error": {"message": "Model not found"}}
Erro de API "agent-first":
{
"error": {
"code": "model_not_found",
"message": "Model 'gpt5.5' not found",
"did_you_mean": "gpt-5.5",
"suggestions": [{"id": "gpt-5.5"}, {"id": "gemini-3.5-flash"}],
"hint": "Use GET /v1/models to list all available models."
}
}
Com uma API tradicional, o agente precisa pesquisar na web, encontrar a documentação, analisar HTML e adivinhar. Com uma API "agent-first", ele se autocorrigi em uma única etapa.
Por que as APIs tradicionais falham com agentes de IA
Observe o que acontece quando um agente acessa um agregador de API típico pela primeira vez:
Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API: 400 {"error": {"message": "Model not found"}}
Agent: (searches the web for "tokenlab models list")
Agent: (fetches a docs page, maybe the wrong one)
Agent: (parses HTML, finds a model name)
Agent: POST /v1/chat/completions {"model": "gpt-5.5"}
API: 200 ✓
Seis etapas, múltiplas requisições de rede, centenas de tokens desperdiçados. E esse é o caminho feliz, onde o agente por acaso adivinhou a URL correta da documentação.
Com o design "agent-first":
Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API: 400 {"did_you_mean": "gpt-5.5", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-5.5"}
API: 200 ✓
Duas etapas, zero pesquisas na web. O agente se autocorrigiu apenas com a resposta de erro.
O princípio fundamental: a inteligência permanece do lado do modelo
A tentação é construir APIs "inteligentes" que autocorrigem o nome do modelo, redirecionam silenciosamente para algo semelhante ou adicionam um mecanismo de recomendação. Rejeitamos tudo isso.
Quando um agente envia model: "gpt5.5", você não sabe realmente qual é a intenção dele. Talvez ele esteja verificando se existe um lançamento mais recente do GPT. Talvez ele tenha uma restrição orçamentária rígida. Talvez ele precise de uma capacidade específica que apenas um modelo suporta. O redirecionamento automático para gpt-5.5 alteraria silenciosamente o custo, a qualidade e as capacidades, e o agente nunca saberia que isso aconteceu.
A melhor atitude é falhar rápido e falhar de forma informativa. Dê ao agente todos os dados e deixe que ele decida.
Quatro padrões de design de API "Agent-First"
Padrão 1: Modelo não encontrado → Sugestões difusas
{
"error": {
"code": "model_not_found",
"did_you_mean": "gpt-5.5",
"suggestions": [
{"id": "gpt-5.5"},
{"id": "gemini-3.5-flash"},
{"id": "claude-sonnet-5"}
],
"hint": "Did you mean 'gpt-5.5'? Use GET /v1/models to list all available models."
}
}
O did_you_mean usa uma resolução de três camadas: mapeamento de alias estático a partir de dados de produção, correspondência de strings normalizada e distância de edição limitada. Cada candidato é verificado em relação à lista de modelos ativos, para que nunca sugiramos um modelo que esteja offline no momento.
Padrão 2: Saldo insuficiente → Alternativas conscientes do orçamento
{
"error": {
"code": "insufficient_balance",
"balance_usd": 0.12,
"estimated_cost_usd": 0.35,
"suggestions": [
{"id": "gemini-3.5-flash", "estimated_cost_usd": 0.02},
{"id": "deepseek-v4-flash", "estimated_cost_usd": 0.01}
],
"hint": "Insufficient balance. Try a cheaper model or top up."
}
}
Em vez de apenas dizer "dinheiro insuficiente", dizemos ao agente exatamente quanto ele tem, quanto precisa e quais modelos ele pode pagar agora. O agente pode reduzir autonomamente para um modelo de IA mais barato sem qualquer intervenção humana. Verifique os preços atuais por modelo no diretório de modelos da TokenLab antes de codificar limites de custo.
Padrão 3: Todos os canais falharam → Alternativas ao vivo
{
"error": {
"code": "all_channels_failed",
"retryable": true,
"retry_after": 30,
"alternatives": [
{"id": "claude-sonnet-5", "status": "available"},
{"id": "gpt-5.5", "status": "available"}
],
"hint": "All channels for 'claude-opus-4-8' temporarily unavailable. Retry in 30s or try an alternative."
}
}
A lista alternatives não é estática. É uma consulta ao vivo em nossos dados de integridade de canais, para que o agente obtenha informações em tempo real sobre o que realmente está funcionando agora, e não uma lista de fallback codificada que pode estar desatualizada.
Padrão 4: Limite de taxa excedido → Tempo de nova tentativa exato
{
"error": {
"code": "rate_limit_exceeded",
"retryable": true,
"retry_after": 8,
"limit": "1000/min",
"remaining": 0,
"hint": "Rate limited. Retry after 8s."
}
}
Sem adivinhações, sem backoff exponencial começando de um valor arbitrário. O agente sabe o tempo de espera exato. Para mais informações sobre como lidar bem com limites de taxa, consulte nosso guia de limites de taxa de API de IA.
Respostas de sucesso também carregam dicas
Quando um agente chama /v1/chat/completions com um modelo Claude, a resposta inclui:
X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages
Estamos dizendo ao agente: isso funcionou, mas existe uma maneira melhor. Ele pode mudar para o endpoint nativo na próxima chamada e aproveitar recursos como raciocínio estendido e cache de prompt que não são expostos através do formato compatível com a OpenAI.
Essas dicas vivem nos cabeçalhos, não no corpo da resposta, porque o corpo precisa seguir exatamente a especificação da OpenAI ou Anthropic. Os cabeçalhos são o ponto de extensão seguro que não quebrará nenhuma lógica de análise existente.
A resposta /v1/models como uma "cola" para o agente
Adicionamos três campos a cada entrada de modelo na resposta /v1/models:
category: modelo de chat, gerador de imagem, modelo de vídeo ou áudio. Chega de adivinhar pelo nome.pricing_unit: por token, por imagem, por segundo ou por requisição. Necessário para qualquer estimativa de custo real.cache_pricing: preços de cache de prompt upstream mais o desconto de cache semântico da plataforma.
Combinado com os campos existentes (preços, capacidades, aliases, tokens máximos), um agente pode fazer uma seleção de modelo totalmente informada a partir de uma única chamada de API. Você pode ver o catálogo completo ao vivo no diretório de modelos da TokenLab (observado em 07/07/2026), que atualmente lista mais de 300 modelos nas categorias de chat, imagem, vídeo e áudio, incluindo opções de fronteira atuais como Claude Sonnet 5, GPT-5.5 e Gemini 3.5 Flash. Verifique os preços e a disponibilidade atuais nessa página em vez de assumir que os números neste artigo estão atualizados.
llms.txt: A primeira leitura do agente
Servimos um llms.txt dinâmico em api.tokenlab.sh/llms.txt, uma visão geral legível por máquina de toda a API. Ele inclui:
- Um template de primeira chamada com código funcional
- Nomes de modelos comuns, gerados automaticamente a partir de dados de uso em vez de codificados
- Todos os 12 endpoints com parâmetros
- Parâmetros de filtro para descoberta de modelos
Um agente que lê este arquivo antes de sua primeira chamada de API tem muito mais probabilidade de acertar a requisição na primeira tentativa.
Baseado em dados, não em conhecimento
Cada sugestão no sistema vem de dados de produção. O mapa de alias did_you_mean foi semeado a partir de 30 dias de erros reais de model_not_found em nossos logs de requisição. As sugestões de modelos são classificadas pelo uso real. A lista de "nomes de modelos comuns" no llms.txt é gerada a partir do nosso banco de dados, não mantida manualmente.
Rastreamos cada erro de modelo em um conjunto ordenado do Redis. Assim que um erro de digitação acumula acessos suficientes, ele é promovido para o mapa de alias. Quando um modelo fica offline, ele sai automaticamente de todas as listas de sugestões. O sistema se ajusta com o tempo em vez de ficar desatualizado, o que é importante quando novos lançamentos de modelos como GPT-5.5, Claude Sonnet 5 e Gemini 3.5 Flash são lançados em cronogramas sobrepostos.
A restrição de design que fez funcionar
Estabelecemos uma regra: sem novos endpoints, sem novos SDKs, sem mudanças disruptivas. Tudo tinha que caber dentro do formato de erro existente compatível com a OpenAI. Novos campos são opcionais, então qualquer cliente que os ignore obtém exatamente a mesma experiência de antes.
Essa restrição forçou a precisão sobre o que realmente ajuda um agente a se autocorrigir, em vez de construir novas APIs elaboradas que ninguém se daria ao trabalho de adotar.
Como aplicar o design "Agent-First" à sua própria API
Se você está construindo APIs que agentes de IA consumirão:
- Torne cada erro acionável. Diga o que deu errado, por que e o que fazer a seguir.
- Sugira alternativas em vez de autocorrigir. Deixe o agente tomar a decisão informada.
- Use campos estruturados, não prosa.
did_you_meané analisável; "você quis dizer..." enterrado em uma frase não é. - Baseie as sugestões em dados reais. Padrões de uso de produção superam uma lista codificada que fica obsoleta.
- Forneça descoberta legível por máquina através de
llms.txt, uma especificação OpenAPI ou uma lista de modelos estruturada. - Mantenha a compatibilidade com versões anteriores. Novos campos de dica devem ser aditivos, nunca disruptivos.
Por onde começar sem reescrever tudo
A maioria das equipes não precisa redesenhar toda a sua API em uma semana. Um ponto de partida menor funciona bem:
- Adicione um ou dois campos de dica legíveis por máquina aos seus erros de maior volume.
- Torne o
/v1/modelsou seu endpoint de descoberta equivalente mais rico e explícito. - Publique uma visão geral legível por máquina, como
llms.txt. - Teste o loop completo com um cliente agente real, não apenas curl.
Se você já está operando através de uma camada de gateway, o guia de gateway de IA unificado explica por que esse plano de controle é importante. Se você ainda está em uma integração direta compatível com a OpenAI, o guia de migração é o lugar mais fácil para começar antes de adicionar comportamentos amigáveis a agentes.
FAQ
O que é design de API "agent-first"?
É uma abordagem onde as respostas de erro incluem dicas estruturadas e legíveis por máquina (campos como did_you_mean, suggestions e hint) para que os agentes de IA possam se autocorrigir sem intervenção humana ou consulta à documentação.
Como o "agent-first" é diferente do design de API "developer-first"?
APIs "developer-first" otimizam para a legibilidade humana: mensagens claras, boa documentação, exemplos úteis. APIs "agent-first" adicionam campos estruturados sobre isso para que as máquinas possam analisar o erro e agir programaticamente, sem ler nada.
O design "agent-first" quebra clientes existentes?
Não. Os campos são aditivos. Clientes existentes que não procuram por did_you_mean ou suggestions simplesmente os ignoram e continuam funcionando exatamente como antes.
A TokenLab fornece acesso unificado a mais de 300 modelos de IA, incluindo modelos de fronteira atuais como GPT-5.5, Claude Sonnet 5 e Gemini 3.5 Flash, através de uma única API listada no diretório de modelos. Comece gratuitamente para testar a API "agent-first" com US$ 1 em créditos iniciais.
Fontes
Preço observado em 2026-07-07
- TokenLab model directoryObservado em 2026-07-07
