Construí um Agente de IA que permite explorar APIs em inglês simples

Meu produto atual tem centenas de APIs. Cada vez que preciso consultar a especificação da API, tenho que navegar até o link do Swagger, rolar infinitamente ou usar a pesquisa do navegador para encontrar o que preciso—e depois filtrar manualmente as coisas. É frustrante e dolorosamente lento. Pior ainda, cada desenvolvedor que precisa integrar com a API tem que passar pela mesma experiência.

Essa frustração me levou a explorar como a IA poderia melhorar o processo. Este post é um mergulho profundo nessa jornada e como ela evoluiu para algo simples, robusto e eficaz.

Preparação

Documentação Rica de API

Como primeiro passo, revisei toda a documentação da API para garantir que tenha detalhes claros de resumo e descrição nos documentos do swagger. Este é um passo crítico para melhor descoberta em estágios posteriores. Também me certifiquei de que o resumo e a descrição são únicos para cada API.

paths": {     "/users/accounts/{account-id}": {       "put": {         "tags": [           "Account API"         ],         "summary": "Update Test suite by test-suite-id",         "externalDocs": {           "description": "Robust get account details description",           "url": "https://mydocs.com/description"         },

\

Categorização das APIs

Com centenas de APIs disponíveis, pode ser desafiador identificar quais estão relacionadas. Categorizar as APIs torna a gestão mais eficiente e posteriormente simplifica a seleção da API correta com base na entrada em linguagem natural. Esta categorização foi implementada usando o conceito de etiquetas definido na especificação OpenAPI.

\

"paths": {     "/users/accounts/{account-id}": {       "put": {         "tags": [           "Account API"         ],         "summary": "Update Test suite by test-suite-id",         "externalDocs": {           "description": "Robust get account details description",           "url": "https://mydocs.com/description"         },

\

Construindo Pesquisa em Linguagem Natural

Entrada do Usuário

Os usuários inseririam a pergunta em linguagem natural relacionada à API.

Exemplo: Como recuperar detalhes da conta?

Classificar Categoria

Nesta etapa, a pergunta e todas as categorias disponíveis são enviadas ao LLM. O LLM é encarregado de retornar a categoria de alto nível em que a pergunta se enquadra. O resultado desta etapa é uma das categorias.

Classificar API Específica

Com base na categoria identificada pelo LLM, o sistema envia outra solicitação ao modelo com a mesma pergunta — mas desta vez, inclui todos os detalhes da API dentro dessa categoria específica detectada na etapa anterior.

É aqui que a preparação anterior compensa: quanto mais descritiva e bem estruturada for a documentação da API, melhores serão os resultados. Descrições claras ajudam o LLM a determinar com precisão sobre qual API o usuário está solicitando informações.

O resultado desta etapa é uma única API específica.

Enriquecer Detalhes de Resposta da API

A especificação OpenAPI da API é então fornecida ao LLM para gerar uma descrição detalhada e rica em contexto da API junto com a pergunta original.

Por exemplo, se o usuário perguntar, "Como posso recuperar detalhes da conta usando um ID de conta?", a resposta incluirá os detalhes de especificação relevantes da API de Conta.

Extensão

Com a capacidade aprimorada do sistema de detectar com precisão a API apropriada, os usuários agora podem dar um passo adiante — gerando trechos de código para interagir diretamente com várias APIs.

Por exemplo:

• "Compartilhe código Python para chamar a API Obter Detalhes da Conta para um determinado ID."

• "Forneça um comando cURL para buscar detalhes da conta por ID."

• "Gere um cliente Go para recuperar detalhes da conta para um ID específico."

\

Lições Aprendidas e Insights

• Documentação rica é imperativa para melhor precisão ao trabalhar com sistemas de IA. Documentação precisa, clara e direta é essencial para robustez. Bônus: Também usamos LLM para gerar um resumo e descrição para cada API, o que ajudou imensamente.
• Categorize Primeiro
• Por quê: Com centenas de APIs, a categorização reduz a carga cognitiva e melhora a recuperação.
• Como: Agrupe APIs relacionadas em um pequeno conjunto de categorias claras. Sistemas de IA têm melhor desempenho quando o espaço de rótulos é limitado.
• Dica de escala: Se o catálogo for muito grande, adicione subcategorias para roteamento mais refinado.
• Construa Iterativamente
• Comece pequeno: Pegue um subconjunto da especificação e treine/valide um roteador que possa selecionar confiavelmente a API correta.
• Expanda gradualmente: Adicione mais APIs ao longo do tempo, meça a precisão e priorize áreas com classificações incorretas.
• Foco: Otimize precisão/recall em vez de amplitude no início.
• Feche o Ciclo com os Usuários
• Colete feedback: Capture casos onde o sistema escolheu a API errada.
• Atue nos sinais: Refine as descrições, resumos e etiquetas das APIs mal identificadas; esclareça escopos sobrepostos.
• Repita: Reavalie após cada alteração para confirmar que a precisão melhora e regressões são evitadas.

Conclusão

À medida que o número de APIs disponíveis continua a crescer, explorar e gerenciá-las requer uma nova abordagem. Com o surgimento de Agentes de IA impulsionados por modelos de linguagem grandes (LLMs), os desenvolvedores agora têm uma maneira mais intuitiva e eficiente de descobrir e interagir com APIs—economizando inúmeras horas anteriormente gastas procurando os endpoints certos.

O potencial não para por aí. Este conceito pode evoluir para um produto independente capaz de ingerir perfeitamente especificações OpenAPI em tempo de execução e expô-las através de uma interface de linguagem natural—oferecendo aos usuários uma solução pronta para uso para exploração de API.

Espero que este artigo tenha ilustrado como aproveitar os LLMs de forma eficaz e como uma documentação de API bem estruturada pode criar uma experiência de descoberta mais suave e inteligente.

\n \n

\n \n