Sua API funciona perfeitamente para devs. Isso não significa que ela funciona para um LLM.

Passei anos construindo APIs para desenvolvedores. Em janeiro, meu consumidor virou um LLM.

Continuei sendo desenvolvedora backend Java. Mas quase tudo que eu tinha como certo precisou ser revisto.

Antes, o consumidor era previsível: outro dev construindo uma tela. A preocupação era documentar bem, definir parâmetros de entrada e saída, escolher o protocolo, montar respostas intuitivas, cuidar de performance e paginação. Se o contrato estivesse claro, o trabalho do outro lado fluía.

Com um modelo do outro lado, o contrato claro deixou de ser suficiente.

O formato antigo funcionava? Funcionava. Mas quando começamos a testar de verdade, ficou evidente que funcionar não era o mesmo que funcionar bem.

O que mudou na prática:

📄 Documentação deixou de ser contrato e virou contexto. Não bastava listar os campos. Era preciso explicar o que cada um significa, o que o endpoint faz e quais regras de negócio existem por trás. Documentação e conhecimento de domínio viraram a mesma coisa.

🎯 Ambiguidade não gera erro, gera invenção. Um campo mal descrito não quebra a aplicação. Ele produz uma resposta plausível e errada, muito mais difícil de detectar do que um 500.

📑 Paginação virou decisão de projeto. O que fazia sentido para uma tela nem sempre faz sentido para um modelo que precisa raciocinar sobre o conjunto inteiro. Nem todo dado deve ser paginado.

🧩 O formato do retorno passou a ser parte do problema. Se já cuidávamos disso quando o consumidor era um dev, agora a pergunta é outra. Devemos agrupar dados de um mesmo contexto? Duas linhas precisam mesmo ser duas, ou deveriam ser uma? O cálculo de percentual sai pronto da API ou fica por conta do modelo? Vale ter endpoints de relatório, mais amplos, e outros bem específicos? Cada uma dessas escolhas esbarra no limite de contexto.

Seguimos construindo na base da tentativa e erro, e acho que essa é a parte mais honesta de trabalhar com algo tão recente: não existe manual pronto.

Quem já está construindo APIs para agentes: o que mais mudou na forma de projetar? 👇

#Backend #Java #LLM #MCP #AgentesDeIA #InovaçãoEmSaúde