API design quando agentes de IA são os usuários
REST por recurso fez sentido para humanos com UI. Agentes pedem outra granularidade e erros acionáveis.
Resposta direta
Se agentes consomem sua API, saia do CRUD normalizado e vá para contratos de tool-calling: ações claras, erros recuperáveis e menos round-trips frágeis.
Por que o REST clássico atrita com agentes
Nesta parte do material sobre api design para agentes de ia, o foco é «Por que o REST clássico atrita com agentes». Em vez de teoria genérica, o raciocínio parte do que acontece quando você executa de verdade.
Então, George, me diga como o design de API muda quando os agentes são seus usuários principais? Há muitas coisas que passaram por muitos anos, que passaram por onde estamos construindo esses APIs restful, muito normalizados, como recursos por endpoints e como desenvolvedores são o público intenso, ou desenvolvedores que enviam código que consumem os APIs são o público intenso. Eles são muito mais , eles interpretam de forma aberta um sistema diferente que estão falando e não é rígido como chamar essa API, então chamar essa e então precisamente como compor esses pedidos.
Nesse mundo, no mundo agente do LLM, Há técnicas para bridar esse espaço, mas há mais trabalho para fazer para os desenvolvedores. Há também o problema de quanto contexto você está usando ao navegar uma API, isso é algo que você realmente quer ter cuidado, e isso varia de novo, então, se você está agora entrando no mundo de LLMs, você está tomando em conta o tamanho da janela de contexto, a latência do seu API, os modos de falha, como o que acontece quando é falso um call, há informações suficientes para que seja correto. Sim, certamente, porque nós vimos de forma inicial o que significa e apenas levar uma API e fechar para um LLM usar como ferramentas.
Contratos, tool-calling e granularidade
Nesta parte do material sobre api design para agentes de ia, o foco é «Contratos, tool-calling e granularidade». Em vez de teoria genérica, o raciocínio parte do que acontece quando você executa de verdade.
O que algumas das coisas inusuais que você vê em LLMs fazem quando um API não está bem preparado e empacado para uso com um agente? Sim, quando você coloca toda a sua API em uma tela e transforma em ferramentas, a coisa mais engraçada que acontece é que, primeiro, a LLM faz a errada de qual ferramenta usar e quando ela percebe que fez o erro há um tipo de cascada de eventos onde ela tenta chamar tantas outras ferramentas que ela não está entendendo o caminho para a solução para o início do problema então há esse tipo de problema de descanso e em outras ocasiões quando você tem sem credenciais para chamar uma API, ou se o LLM não tem o certo credencial para chamá-la. Então, o Speakeasy começou como nós tomamos a sua API aberta, a descrição da sua API, e nós temos um generador de código que o transforma em SDKs, em múltiplas línguas.
Depois, como em Sebre, nós começamos a fazer a geração de server de MCP para nossos clientes. Cada tipo de SDK de TypeScript tinha um server de MCP que os usuários poderiam instalar. E então foi aí que aprendemos sobre vários problemas com apenas transformar um API em ferramentas direto, o que nos levou para criar um novo produto chamado Gram, que fica junto ao Codegenerator.
Na prática
REST normalizado vs APIs pensadas para agentes como consumidor principal.
Versionamento e estabilidade
Nesta parte do material sobre api design para agentes de ia, o foco é «Versionamento e estabilidade». Em vez de teoria genérica, o raciocínio parte do que acontece quando você executa de verdade.
E isso é mais uma experiência para rapidamente iterar sobre as ferramentas que você está gerando com seu API, melhorando sua qualidade e então fazendo mais um pouco de engenharia de contexto, como construindo templates e ferramentas de alta ordem que chamamos. E sim, o fluxo de pegar uma API e colocar ela em uma ferramenta e gerar um server de MCP não é muito conduzido para uma iteração rápida, porque o que você quer fazer, o que você está focando em para obter ferramentas melhores é melhorar os nomes das ferramentas, melhorar suas descrições. Qual é a sua definição, sua distinção entre um tool e um server de MCP?
O protocolo de contexto de modelo é, principalmente, quase um padrão de facto, a partir deste ponto, para a maquinaria de capacidades de AI, de capacidades de modelos de língua. E o Speakeasy tem um software que que te permite enviar o seu API para o Speakeasy e eles vão gerar o quê para você? Sim, então, nós geraremos, essencialmente, nós criaremos um catálogo de todos os endpoints traduzidos em ferramentas e agora você pode, tipo, cortar e dicar eles em subsets e isso, tipo, fala de um problema diferente, mas você corta eles em subsets e cada subset é seu próprio server MCP, então, por exemplo, você pode ter Apenas os componentes da API Stripe que lidam com cargas, como querendo cargas, criando cargas, esse tipo de coisa tem um server MCP coesivo no seu propósito e isso pode ser instalado em qualquer cliente de LLM como a App Cloud Desktop e nós lidamos com criar o server MCP, no momento em que você criou esse subset, há um server MCP host que você pode instalar diretamente em seu favorito uma aplicação de desktop ou um framework do agentic e você pode ter seu próprio domínio e tudo é muito identificável e você pode usar isso tanto internamente como como times dentro de uma empresa estão construindo e proliferando serviços para uso agente ou você pode publicá-lo para seus clientes e usuários interagirem com o internet público, então você mencionou em seu contato que você vai estar dando mais tarde hoje que você precisa fazer seus apis mais descobridos O que isso significa no contexto de LLMs?
Checklist de redesign
Nesta parte do material sobre api design para agentes de ia, o foco é «Checklist de redesign». Em vez de teoria genérica, o raciocínio parte do que acontece quando você executa de verdade.
O problema que encontramos é que as descrições de API atualmente, seja você usar OpenAPI ou algo parecido a forma como essas foram expostas para o mundo por várias empresas não foi desenhada para uma LLM entender. A descrição de todos os ferramentas é, basicamente, um pouco de contexto que o LLM tem quando ele acessa o server do MCP. Então, se você não investir na mapeagem e na descrição dos ferramentas, então você vai ter um tempo muito difícil de conseguir pessoas do mundo, como integradores, clientes, usando frameworks e metodologias agentes para falar com sua API.
Interessante, a narrativa atual no mundo é que você não pode pegar uma API e transformá-la em ferramentas E eu tendo a concordar com isso, para um grande nível, porque muitos endpoints são muito normalizados Por exemplo, você tem uma API que retorna uma lista de coisas paginadas E ela só tem as IDs das coisas, como a ID do cliente ou a ID do ordenador Então, digamos que você diga a um LLM que me encontre uma ordem particular e me dê alguns detalhes sobre ela É só ter que fazer. Há muitas chamadas de API, ou chamadas de ferramentas, eu diria, para resolver esse problema, especialmente se a ordem desejada é de três páginas para a API. Bem, enquanto você está fazendo isso, você está usando um contexto valioso, porque você está colocando esses dados, como você está colocando a primeira página, isso vai entrar no escritório do contexto, a segunda página vai entrar no escritório do contexto e assim por diante, até encontrar o resultado desejado, e então tem que fazer outro call para conseguir, você sabe, o resultado específico ou resolver o ID específico, então isso é como um uso ineficiente de contexto, mas isso é como se nós não pensássemos que paginação é alguma coisa ruim.
Sinais de que está funcionando
Nesta parte do material sobre api design para agentes de ia, o foco é «Sinais de que está funcionando». Em vez de teoria genérica, o raciocínio parte do que acontece quando você executa de verdade.
É só quando um LLM está confrontado com aqui está uma API paginada para resolver um problema você pode realmente passar pelo seu. Como a Stripe API tem um endpoint de pesquisa para clientes e provavelmente, ou definitivamente, um endpoint para listas de clientes. E, curiosamente, a partir deste ponto, muitos LLMs foram treinados com o Stripe API, então eles sabem o idioma de query a um certo nível.
Então, para voltar à pergunta, você quer criar novas APIs, você não precisa, digamos, tirar sua API atual, você tem que criar novas APIs que são muito compatíveis com modelos de linguagem. Como o Expand API que você tem no Stripe API, esses são realmente valiosos, porque você pode fazer um tool resolver um problema inteiro, ao invés de precisar de múltiplos tools que comecem a usar o contexto. Então é interessante, é quase como criar APIs que você poderia pensar mais facilmente como uma pessoa para você, ao invés de como uma máquina, certo?
O que evitar na primeira semana
Nesta parte do material sobre api design para agentes de ia, o foco é «O que evitar na primeira semana». Em vez de teoria genérica, o raciocínio parte do que acontece quando você executa de verdade.
Como se você estivesse procurando algo sozinho, você não gostaria de uma lista de mil coisas e ir através de cada página, uma ao mesmo tempo, não é? Na verdade, é apenas clicar quando você começa a pensar, como desenvolvedor, antes de tudo isso, quando você está tentando interpretar uma API para navegar para resolver um problema para o seu negócio, você está fazendo a mesma coisa, ou coisas muito similares, como um processo de pensamento para um LLM, e você está tentando navegar a documentação, você está tentando navegar os argumentos, é bem similar, então se você começar a pensar que um LLM é como um engenheiro junior e você quer que ele tenha o maior rendimento de sucesso navegando coisas, você começa a investir em diferentes aspectos da sua API. E quanto às limitações de preço e mensagens de erro, como elas fazem um papel em um API de agentes?
Sim, certamente, limitações de preço existem e LLMs vão atirá-las, especialmente se for passar por um loop de mania de chamar várias APIs. Na verdade, é mais para o intermediário, então quando você está construindo seu server de MCP e você está encodando, tipo, para essa ferramenta fazer essa chamada de API, Você quer garantir que você está adicionando defesas, como se você encontrar um limite de preço, você respeita o retry após a informação que o servidor está te enviando. Não é apenas um apelo direto para uma API, você pode interpretar essa API na layer MCP, adicionar contexto a ela e até adicionar, se você está preso aqui, vá para essa ferramenta de roubamento ou.
Como explicar isso para o time
Nesta parte do material sobre api design para agentes de ia, o foco é «Como explicar isso para o time». Em vez de teoria genérica, o raciocínio parte do que acontece quando você executa de verdade.
Você envia o mensagem de erros para um tool subsequente e isso pode ajudar a resolver o problema. Se o LLM, como você pode ver, você geralmente pode ver a diferença entre quando está correndo porque não está convergindo para uma solução e quando está chamando uma chamada de ferramentas, porque intuitivamente esta é a chamada de ferramentas certa para chamar para resolver um problema. Você não pode realmente ter de um certo ponto de vista, você não quer ter uma ferramenta que é toda-encompassada e responda qualquer pergunta quando uma ferramenta se torna muito aberta, há mais margem de erro para a LLM chamá-la da forma errada mas ferramentas bem feitas que se compõem em uma cadeia para resolver um problema é um conceito tão poderoso e espero que eu possa te mostrar isso mais tarde também sim, eu definitivamente quero ver isso, mas eu me pergunto O que você pensa sobre o futuro?
Você vê um ponto onde os agentes são os primeiros usadores de nossas APIs? O mundo está rapidamente se movendo para isso, com o protocolo de agentes de agentes da MCP e da Google, vamos começar a ter agentes autônomos no campo. É dentro dos próximos 12 a 18 meses que vamos ver mais proliferação desses sistemas autônomas que estão agindo em nome de um dos seus clientes.
Na prática
Próximo passo: escolha uma métrica (taxa de sucesso, tempo, retries ou conversão) e rode um experimento de 7 dias antes de escalar o padrão.