A maioria das APIs é projetada para desenvolvedores humanos que leem documentação, navegam por exemplos e depuram com stack traces. Mas em 2026, os consumidores de API que mais crescem são os agentes de IA, e eles interagem com as APIs de forma muito diferente.
Esta é a história de como redesenhamos a API de IA unificada da LemonData em torno de um princípio simples: não seja inteligente, seja informativo. O resultado é o que chamamos de design de API agent-first, e ele reduziu o desperdício de tokens dos nossos usuários em mais de 60%.
O Que É Design de API Agent-First?
Design de API agent-first significa estruturar as respostas da sua API, especialmente as respostas de erro, para que um agente de IA possa entender o que deu errado e corrigi-lo sem ajuda externa.
Erro de API tradicional:
{"error": {"message": "Model not found"}}
Erro de API agent-first:
{
"error": {
"code": "model_not_found",
"message": "Model 'gpt5' not found",
"did_you_mean": "gpt-4o",
"suggestions": [{"id": "gpt-4o"}, {"id": "gpt-4o-mini"}],
"hint": "Use GET /v1/models to list all available models."
}
}
A diferença? Com uma API tradicional, o agente precisa pesquisar na web, encontrar a documentação, analisar o HTML e adivinhar. Com uma API agent-first, ele se autocorrige em uma única etapa.
Por Que as APIs Tradicionais Falham com Agentes de IA
Veja o que acontece quando um agente de IA acessa um agregador de API típico pela primeira vez:
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"error": {"message": "Model not found"}}
Agent: (pesquisa na web por "lemondata models list")
Agent: (busca uma página de docs, talvez a errada)
Agent: (analisa o HTML, encontra um nome de modelo)
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
API: 200 ✓
Seis etapas. Múltiplas requisições de rede. Centenas de tokens desperdiçados. E este é o "caminho feliz", onde o agente adivinhou a URL correta da documentação.
Com design agent-first:
Agent: POST /v1/chat/completions {"model": "gpt5"}
API: 400 {"did_you_mean": "gpt-4o", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-4o"}
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 Fica no Lado do Modelo
A tentação é construir APIs "inteligentes": autocorrigir o nome do modelo, rotear silenciosamente para um modelo semelhante, adicionar um motor de recomendação. Rejeitamos tudo isso.
Quando um agente envia model: "gpt5", você não conhece sua intenção. Talvez ele esteja testando se o GPT-5 existe. Talvez ele tenha uma restrição de orçamento. Talvez precise de uma capacidade específica. O roteamento automático para gpt-4o alteraria silenciosamente o custo, a qualidade da saída e as capacidades, tudo sem o conhecimento do agente.
A decisão correta é falhar rápido e falhar de forma informativa. Forneça todos os dados ao agente. Deixe que ele decida.
Quatro Padrões de Design de API Agent-First
Padrão 1: Modelo Não Encontrado → Sugestões Aproximadas (Fuzzy)
{
"error": {
"code": "model_not_found",
"did_you_mean": "gpt-4-turbo",
"suggestions": [
{"id": "gpt-4o"},
{"id": "gpt-4o-mini"},
{"id": "claude-sonnet-4-5"}
],
"hint": "Did you mean 'gpt-4-turbo'? Use GET /v1/models to list all available models."
}
}
O campo did_you_mean usa uma resolução de três camadas: mapeamento de alias estático de dados de produção, correspondência de string normalizada e distância de edição limitada. Todos os candidatos são validados contra a lista de modelos ativos, para que nunca sugiramos um modelo que esteja offline no momento.
Padrão 2: Saldo Insuficiente → Alternativas Cientes do Orçamento
{
"error": {
"code": "insufficient_balance",
"balance_usd": 0.12,
"estimated_cost_usd": 0.35,
"suggestions": [
{"id": "gpt-4o-mini", "estimated_cost_usd": 0.02},
{"id": "deepseek-chat", "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. O agente pode fazer o downgrade autonomamente para um modelo de IA mais barato, sem necessidade de intervenção humana.
Padrão 3: Falha em Todos os Canais → Alternativas em Tempo Real
{
"error": {
"code": "all_channels_failed",
"retryable": true,
"retry_after": 30,
"alternatives": [
{"id": "claude-sonnet-4-5", "status": "available"},
{"id": "gpt-4o", "status": "available"}
],
"hint": "All channels for 'claude-opus-4-6' temporarily unavailable. Retry in 30s or try an alternative."
}
}
A lista de alternatives não é estática. É uma consulta em tempo real contra nossos dados de integridade do canal, para que o agente receba informações atualizadas sobre o que realmente está funcionando agora.
Padrão 4: Rate Limited → Tempo de Reentrada 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 valores arbitrários. O agente sabe o tempo exato de espera. Para saber mais sobre como lidar com limites de taxa de forma eficaz, consulte nosso guia de rate limiting 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-LemonData-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-LemonData-Native-Endpoint: /v1/messages
Estamos dizendo ao agente: "isso funcionou, mas há uma maneira melhor". O agente pode mudar para o endpoint nativo na próxima chamada, obtendo acesso a recursos como pensamento estendido e cache de prompt que não estão disponíveis através do formato compatível com OpenAI.
Colocamos isso nos headers, não no corpo da resposta, porque o corpo segue a especificação da OpenAI/Anthropic. Headers são o ponto de extensão seguro.
A Resposta /v1/models como uma "Cola" para o Agente
Adicionamos três campos a cada 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. Essencial para estimativa de custo.cache_pricing: preços de cache de prompt upstream mais desconto de cache semântico da plataforma.
Combinado com os campos existentes (preço, capacidades, aliases, tokens máximos), um agente pode tomar decisões de seleção de modelo totalmente informadas a partir de uma única chamada de API.
llms.txt: A Primeira Leitura do Agente
Servimos um llms.txt dinâmico em api.lemondata.cc/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, não codificados rigidamente)
- 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 provavelmente acertará na primeira tentativa.
Baseado em Dados, Não em Conhecimento
Cada sugestão em nosso sistema vem de dados de produção. O mapa de alias did_you_mean foi alimentado por 30 dias de erros reais de model_not_found em nossos logs de requisição. As sugestões de modelos são classificadas por padrões de uso reais. Os "nomes de modelos comuns" no llms.txt são gerados a partir do nosso banco de dados.
Rastreamos cada erro de modelo em um sorted set do Redis. Quando um erro de digitação acumula acessos suficientes, ele é promovido ao mapa de alias. Quando um modelo fica offline, ele desaparece automaticamente de todas as sugestões. O sistema se aprimora sozinho.
A Restrição de Design que Fez Funcionar
Estabelecemos uma regra: sem novos endpoints, sem novos SDKs, sem alterações que quebrem a compatibilidade. Tudo tinha que funcionar dentro do formato de erro compatível com OpenAI existente. Novos campos são opcionais, então qualquer cliente que os ignore terá a mesma experiência de antes.
Essa restrição nos forçou a ser precisos sobre quais informações realmente ajudam um agente a se autocorrigir, em vez de construir novas APIs elaboradas que ninguém adotaria.
Como Aplicar o Design Agent-First na Sua Própria API
Se você está construindo APIs que agentes de IA consumirão:
- Cada erro deve ser acionável. Inclua o que deu errado, por que e o que fazer a seguir.
- Sugira alternativas, não autocorrija. Deixe o agente tomar decisões informadas.
- Use campos estruturados, não prosa.
did_you_meané analisável; "Você quis dizer..." em uma string não é. - Baseie as sugestões em dados reais. Padrões de uso de produção superam listas codificadas rigidamente.
- Ofereça descoberta legível por máquina através de
llms.txt, especificações OpenAPI ou listas de modelos estruturadas. - 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.
O ponto de partida prático é menor:
- adicione um ou dois campos de dica legíveis por máquina aos seus erros de maior volume
- torne o
/v1/modelsou o endpoint equivalente de descoberta de modelos mais rico e explícito - publique uma visão geral legível por máquina, como o
llms.txt - teste todo o ciclo com um cliente agente, não apenas com curl
Se você já está operando através de uma camada de gateway, o guia de gateway de IA unificado mostra por que esse plano de controle é importante. Se você ainda está em uma integração direta compatível com OpenAI, o guia de migração é o lugar mais fácil para começar antes de adicionar mais comportamentos amigáveis aos agentes.
FAQ
O que é design de API agent-first?
O design de API agent-first é uma abordagem onde as respostas de erro incluem dicas estruturadas e legíveis por máquina que permitem que os agentes de IA se autocorrijam sem intervenção humana ou consultas a documentações externas.
Como o agent-first é diferente do design de API developer-first?
APIs developer-first otimizam para a legibilidade humana: mensagens de erro claras, boa documentação, exemplos úteis. APIs agent-first adicionam campos estruturados (did_you_mean, suggestions, hint) que as máquinas podem analisar e agir programaticamente.
O design agent-first quebra clientes existentes?
Não. Os campos agent-first são aditivos, o que significa que os clientes existentes podem ignorá-los e continuar funcionando sem alterações.
Como a LemonData implementa o design agent-first?
O gateway de API de IA unificado da LemonData adiciona dicas de erro estruturadas a todos os mais de 300 modelos. Cada resposta de erro inclui sugestões acionáveis, e o endpoint llms.txt fornece descoberta de API legível por máquina.
A LemonData fornece acesso unificado a mais de 300 modelos de IA através de uma única API. Experimente gratuitamente para testar a API agent-first com $1 em créditos iniciais.
