Pesquisas recentes apontam para um crescimento maciço em Bots acionados pela IA rastejando a web procurando APIs. Embora muitos deles tenham intenção maliciosa, um número crescente é consumidores de API bem-intencionados, apenas tentando descobrir, consumir e se beneficiar das APIs existentes. E, cada vez mais, essas solicitações de API são provenientes de plataformas orientadas a MCP (Modelo Protocolos de contexto) projetado para permitir que o software program autônomo interaja diretamente com as APIs da Net.
E, se as estatísticas recentes forem algum guia, elas são lutando. A taxa de sucesso para os fluxos de trabalho da API de várias etapas são cerca de 30%. Pior, esses clientes geralmente não desistem. Em vez disso, eles continuam tentando – e falhar – para interagir com suas APIs, aumentando o tráfego enquanto diminui a proposta de valor geral das APIs de destino.
Então, o que está acontecendo aqui? Por que os clientes orientados pela IA são incapazes de aproveitar as APIs de hoje? E o que será necessário para mudar isso?
Acontece que a resposta esteve lá o tempo todo. As coisas que os consumidores de API acionados pela IA precisam são as mesmas coisas que os desenvolvedores humanos precisam: clareza, contexto e estrutura significativa. No entanto, muitas empresas ainda não estão prestando atenção. E, como aprendemos em 2017, “Atenção é tudo que você precisa. ”
Você está prestando atenção?
O artigo de Landmark 2017 “Atenção é tudo que você precisa”Apresentou o mundo à noção de transformadores. No mundo da IA, um transformador é um modelo em que as palavras são pontuadas matematicamente com base em seus relacionamentos com outras palavras no conteúdo circundante. Esta pontuação, referida como atençãotorna possível para programas que usar Transformadores (como Chatgpt) produzir respostas que parecem notavelmente coerentes aos leitores humanos.
A capacidade de usar transformadores para impulsionar ferramentas generativas de IA torna imperativo que todos repensemos a maneira como projetamos, documentamos e implementamos nossas APIs. Em poucas palavras, os transformadores prestam atenção a todo o conteúdo que têm acesso, mas não entender qualquer coisa. Ainda mais ao ponto, plataformas genai como chatgpt, ClaudeAssim, Gêmeose Co-piloto pode facilmente prestar atenção para o seu design de API. Eles podem identificar os URLs, os métodos HTTP, as entradas, o esquema e as saídas esperadas. Mas eles não podem realizar nenhum raciocínio sobre qual API usar e qual o conteúdo do corpo retornado realmente significa.
Essencialmente, os bots acionados pela IA de hoje são consumidores de API rápidos e flexíveis que não conseguem encontrar o caminho de um saco de papel molhado. A boa notícia é que podemos aproveitar as habilidades de um cliente orientado a IA em prestar atenção e adicionar suporte ao nosso design de API para compensar sua incapacidade de fazer escolhas sábias.
E essa é uma receita clara para fazer suas APIs prontas.
Coisas que você pode fazer agora para nivelar o campo de jogo
Como os clientes da API orientados a IA serão bons em correspondência de padrões, reconhecer conteúdo repetido e tornar as associações com base no contexto, podemos usar essas habilidades para preencher os aplicativos LLM do GAPS LLM em relação à tomada de decisão, significado e entendimento.
Abaixo estão quatro práticas que já sabemos facilitar para os desenvolvedores humanos entender e usar nossas APIs. Acontece que essas são as mesmas coisas que ajudarão os clientes da API orientados a IA também a ter mais sucesso.
- Ser explícito: Não assuma clientes entender O que esta API faz
- Diga a eles o porquê: Forneça descrições claras do porquê e quando os clientes podem usar a API
- Ser consistente: Quanto mais sua API se parece com os milhares de outros nos dados de treinamento do LLM, melhor
- Torne as respostas de erro acionáveis: Forneça suggestions claro, consistente e detalhado que facilita a resolução de erros de tempo de execução
Vamos olhar para cada um deles por sua vez.
Ser explícito
Ao contrário dos humanos, as máquinas não são exploradores intuitivos. Enquanto são ótimos em analisar o texto e fazer associações, as máquinas não dão saltos intuitivos. Em vez disso, as máquinas precisam de preços explícitos; pistas sobre o que pode ser realizado, como fazê -lo e por que você pode querer executar uma ação. A abordagem clássica centrada no ser humano de projetar e documentar uma API é capturada nesta lista concisa:
GET /clients/GET /clients/{id}POST /clients/PUT /clients/{id}DELETE /clients/{id}
A maioria dos humanos sabe exatamente o que esta lista está se comunicando; A lista completa de operações disponíveis para gerenciar uma coleção de buyer registros. Os seres humanos procurariam em outros lugares na documentação do design da API para determinar as propriedades de dados necessárias e opcionais para passar para cada ação, bem como o formato para lançar as interações (JSON, XML, HTML, and many others.).
Mas não se pode confiar em máquinas para exibir esse nível de entendimento e curiosidade. Eles são mais propensos a fazer apenas alguns “palpites estatísticos” sobre o que essa tabela representa e como usá -la. Para aumentar as possibilities de sucesso e reduzir a probabilidade de erros, é melhor ser muito mais explícito em sua documentação da API para máquinas. Como no exemplo de documentação seguinte que é ajustado para o consumo de LLM:
- Para recuperar uma lista de registros de clientes usados
GET /clients/ - Para recuperar um único uso de registro de cliente
GET /clients/{id}enquanto fornece o valor adequado de{id} - Para criar um novo uso de registro do cliente
POST /clients/com ocreateCustomeresquema - Para atualizar um uso de registro de cliente existente
PUT /clients/{id}com oupdateCustomeresquema enquanto fornece o valor adequado para{id} - Para remover um registro do cliente do uso da coleção
DELETE /clients/{id}enquanto fornece o valor adequado para{id}
Enquanto essas duas listas carregam essencialmente o mesmo significado Para os seres humanos, a segunda lista é muito mais útil para clientes de API orientados para a máquina.
Diga a eles o porquê
Focar em ser explícito é uma ótima maneira de melhorar a taxa de sucesso dos aplicativos de clientes orientados a IA. Outra maneira de fazer isso é fornecer detalhes sobre por que um cliente da API pode querer usar um ponto remaining da API específico. É importante ter em mente que os clientes orientados pela IA são muito bons em adivinhar como Uma API pode ser usada, mas esses mesmos LLMs não são muito bons em descobrir por que eles devem ser usados. Você pode corrigir isso adicionando texto que explica os usos comuns para cada terminal da API.
Por exemplo, em sua documentação, inclua frases como “Use o PriorityAccounts endpoint para identificar os dez principais clientes com base no tamanho do mercado. ” Ou “use o submitApplication O ponto remaining depois que todas as outras etapas do processo de inscrição para funcionários forem concluídas. ” Essas descrições fornecem dicas adicionais aos consumidores da API sobre o porquê ou mesmo quando as APIs serão mais úteis.
Observe que, em ambos os casos, o texto identifica o terminal pelo nome e explica o motivo pelo qual um cliente da API pode usar essa API. Os clientes movidos a IA-especialmente os apoiados pelo LLMS-são muito bons em reconhecer texto como este e associá-lo a outro texto em sua documentação, como a lista que revisamos na seção anterior.
Ser previsível
O poder actual por trás dos aplicativos de clientes baseados em LLM é encontrado em todos os documentos e codificam esses modelos de idiomas que foram levados como dados de treinamento. Todos os livros, papéis e código -fonte alimentados nos bancos de dados LLM fornecem contexto estatístico para qualquer novo texto que sua documentação da API forneça. É o esforço histórico acumulado de milhares de escritores, programadores e arquitetos de software program que possibilitam que os clientes de IA interajam com sua API.
E essas interações serão muito mais suaves se sua API se parecer muito com todas as outras APIs, foi alimentada como dados de treinamento. Se o seu design de API contiver muitos elementos exclusivos, respostas inesperadas ou uso não tradicional de protocolos comuns, aplicativos orientados a IA terão mais dificuldade em interagir com ele.
Por exemplo, embora seja perfeitamente “correto” usar http PUT Para criar novos registros e http PATCH Para atualizar os registros existentes, a maioria das APIs HTTP usa o POST Para criar registros e colocar para atualizá -los. Se sua API depende apenas de uma maneira única de usar PUT e PATCH Operações você provavelmente está dificultando as coisas em seus aplicativos orientados pela IA e reduzindo suas possibilities de sucesso. Ou, se sua API depender exclusivamente de um conjunto de Definição de esquema baseada em XML Documentos, clientes de API movidos a IA que foram treinados em milhares de linhas de JSON Schema Pode não reconhecer seus objetos de entrada e saída da API e pode cometer erros ao tentar adicionar ou atualizar dados para sua API.
Sempre que possível, aproveite os padrões comuns e os detalhes da implementação ao criar sua API. Isso garantirá melhor que os clientes de IA possam reconhecer e interagir com sucesso com seus serviços.
Torne as respostas de erro acionáveis
Quando os humanos encontram erros nas interfaces do usuário, eles geralmente podem digitalizar as informações de erro exibidas, compará -las com os dados em que já digitaram e elaborar uma solução para resolver o erro e continuar usando o serviço. Isso não é muito fácil para os clientes da API acionada por máquina. Eles não têm a capacidade de digitalizar a resposta inesperada, obter significado e depois formular uma solução criativa. Em vez disso, eles tentam novamente (talvez com algumas mudanças aleatórias) ou apenas desistem.
Ao projetar suas APIs para oferecer suporte a clientes orientados para a máquina, é importante aplicar as mesmas três regras que já mencionamos (seja explícito, diga a eles o porquê e seja previsível) quando os clientes da API encontrarem erros.
Primeiro, verifique se o aplicativo cliente reconhece a situação de erro. Para clientes da API, isso é mais do que apenas retornar o standing HTTP 400. Você também deve incluir um documento formatado que identifique e explique os detalhes do erro. Uma ótima maneira de conseguir isso é usar os detalhes do problema para a especificação HTTP APIs (RFC7078) formato. Essa resposta fornece uma maneira estruturada de identificar o problema e sugerir uma possível alteração para resolver o erro.
Observe que essa resposta também atende a nossos critérios para a segunda regra (diga a eles o porquê). Esta atualização falhou porque estava faltando um campo e esse campo é hatsize. O relatório de erro até diz à máquina o que eles podem fazer para fazer outra tentativa de atualizar o registro.
Outra vantagem de usar o formato RFC7078 é que ele nos ajuda a atender à terceira regra (seja consistente). Esta RFC é uma especificação comum encontrada em muitos exemplos de API e é bastante provável que os dados de treinamento do LLM contenham muitas dessas respostas. É melhor usar esse formato de erro existente em vez de confiar em um que você criou.
Finalmente, é uma boa ideia projetar suas APIs para tratar erros como tentativas parciais. Na maioria das vezes, os erros da API são apenas erros simples causados por documentação inconsistente ou ausente e/ou desenvolvedores inexperientes. O fornecimento de informações explícitas para erros não apenas ajuda a resolver o problema com mais facilidade, mas oferece uma oportunidade de “re-treinar” os clientes da máquina, preenchendo o contexto native da máquina com exemplos de como resolver erros no futuro.
Lembre-se de que os clientes baseados em LLM são ótimos em reconhecer padrões. Você pode usar isso quando projeta suas APIs também.
Preste atenção aos seus consumidores de API acionados pela IA
Conforme mencionado no início deste artigo, as coisas identificadas aqui como uma maneira de melhorar suas interações com os clientes da API orientada a IA são práticas que foram sugeridas no passado para melhorar o design das APIs para a interação humana.
Ser explícito reduz a carga cognitiva dos desenvolvedores e os ajuda a se concentrar no trabalho criativo de solução de problemas necessários para usar sua API para resolver seu problema imediato.
Dizer a eles por que facilita os desenvolvedores para identificar as APIs de que precisam e entender melhor a maneira como funcionam e quando podem ser aplicadas.
Ser consistente é outra maneira de reduzir a carga cognitiva para programadores e fornecer uma experiência mais “intuitiva” ao usar sua API.
E, fazer respostas de erro acionável leva a um melhor suggestions de erros e uma resolução de erro mais consistente no tempo de execução e no tempo de design.
Finalmente, todas essas práticas funcionam melhor quando você fica de olho na maneira como os clientes da API (ambos humanos e de IA) na verdade usar seu serviço. Anote quais pontos de extremidade são comumente usados. Identifique as condições persistentes de erro e como elas são resolvidas. E acompanhe o tráfego do cliente da API como uma maneira de avaliar quais APIs fornecem o maior retorno para o seu esforço e que são mais problemáticas do que valem a pena. O monitoramento de qualidade das suas APIs o ajudará a entender melhor quem as está usando e que tipos de problemas eles estão tendo. Isso lhe dará pistas sobre como você pode redesenhar suas APIs no futuro para melhorar a experiência para todos.
Esteja você apoiando o consumo de API movido a humanos ou clientes orientados a máquinas, prestar atenção pode pagar generosamente.