APIs para agentes de IA: de MCP a endpoints personalizados

Quando os LLMs aprenderam a chamar funções

Na era do GPT-3, interagir com um LLM significava fornecer um prompt e receber texto de volta. O conhecimento do modelo era grande, mas estático, congelado no que quer que os dados de treinamento contivessem. Você podia pedir que ele explicasse computação quântica ou redigisse um e-mail, e ele produziria um texto plausível. Mas ele não conseguia verificar a previsão do tempo de hoje, consultar um banco de dados nem executar qualquer ação no mundo real.

O recurso que mudou isso recebe surpreendentemente pouco crédito. Ele deu ao modelo uma escolha entre gerar texto e chamar uma função. Em vez de sempre produzir o próximo token, o modelo agora podia gerar um objeto JSON estruturado especificando o nome de uma função e seus argumentos. O runtime executaria essa função, devolveria o resultado ao modelo, e o modelo continuaria a partir daí. O artigo ReAct (Yao et al., 2022) formalizou isso como o loop Thought-Action-Observation. O modelo raciocina sobre o que fazer, executa uma ação (chama uma ferramenta), observa o resultado e repete. Todo agente de IA sério em 2026 roda em alguma versão desse padrão.

O loop

Claude Code, OpenClaw, Codex, Devin e dezenas de outros sistemas agentivos funcionam da mesma forma. Chamar uma ferramenta, observar o resultado, decidir o que fazer em seguida, repetir. Simon Willison descreveu bem: “Um agente LLM executa ferramentas em um loop para atingir um objetivo.”

Claude Code, por exemplo, usa um loop mestre single-threaded, sem enxame multiagente nem grafo de orquestração complexo: while(tool_call) -> execute -> feed results -> repeat.

A pesquisa da Anthropic sobre autonomia de agentes mostra que as durações dos turnos no Claude Code quase dobraram em três meses, de 25 para mais de 45 minutos. Os usuários confiam cada vez mais que o loop rode sozinho. Os dados mostram que usuários experientes interrompem com mais frequência (mudando de aprovação por ação para monitoramento estratégico), enquanto o próprio agente pede esclarecimentos mais de duas vezes mais frequentemente do que os usuários o interrompem.

Esse padrão de loop aparece em todos os lugares, em agentes de programação, bots de atendimento ao cliente e controladores de robótica.

O que conta como uma ferramenta?

LLMs nos dão bastante liberdade para decidir em que nível de abstração uma ferramenta deve operar. Em um extremo, você tem endpoints de API altamente específicos: “criar um contato no HubSpot com estes 12 campos.” No outro, você tem ferramentas como “execute este comando bash” ou “execute este código Python”, que são essencialmente “faça o que quiser.”

Devin opera com três ferramentas: shell, editor de código, navegador. A principal ferramenta do Claude Code também é um shell. OpenClaw usa um sistema dinâmico de plugins de habilidades. A tendência nas ferramentas de programação agentivas tem sido caminhar para menos ferramentas, mais gerais, em vez de muitas ferramentas específicas.

Simon Willison observou que MCP “inicialmente explodiu, mas depois pareceu menos central” para agentes de programação porque bash é a ferramenta universal. Arquivos e scripts são um primitivo com menor sobrecarga do que implementações completas de servidores MCP. Se o agente consegue escrever e executar código, ele consegue fazer quase qualquer coisa sem precisar de uma definição de ferramenta dedicada.

Mas ferramentas de propósito geral funcionam para agentes de propósito geral. Para agentes de IA específicos de domínio (atendimento ao cliente, vendas, operações internas), você precisa de ferramentas específicas de domínio. Seu agente de suporte não deve escrever Python para verificar o status de um pedido. Ele deve chamar um endpoint de API bem definido, com parâmetros claros e respostas previsíveis. O design do seu conjunto de ferramentas se torna uma decisão de produto.

O que um endpoint de API significa agora

Para agentes de IA, um endpoint de API funciona como uma declaração de capacidade. Publicar um deles diz que você (ou seu agente de IA) agora pode fazer algo que antes não era possível.

Isso funciona nas duas direções. Um fornecedor de software publica uma API para que outros possam integrar com seu produto. Mas um agente de IA também pode descobrir endpoints por conta própria, pesquisando documentação, lendo especificações OpenAPI ou literalmente pesquisando no Google como realizar uma tarefa.

Um servidor MCP é um pacote curado de endpoints de API com uma noção preconcebida de como eles devem ser usados. O criador do MCP já tomou decisões sobre quais endpoints expor, como nomeá-los, quais parâmetros destacar e, implicitamente, quais fluxos de trabalho apoiar. Essa curadoria é tanto a força (conveniência, padronização) quanto a fraqueza (rigidez, escopo opinativo). O servidor da Notion é um exemplo concreto: ele publica 28 ferramentas, e um agente de central de ajuda precisa de quatro delas, divididas em duas conexões.

MCPs trocam controle por facilidade de uso. Em 2026, a IA escreve a maior parte do código de integração. Se um agente consegue ler a documentação da API e escrever a integração por conta própria, o argumento de “facilidade de uso” para MCP fica mais fraco. A camada MCP pode ser mais importante durante o período de transição, enquanto as ferramentas ainda não alcançaram a capacidade do modelo. O guia da Anthropic sobre padrões de design para uso de ferramentas é uma referência prática para estruturar esquemas de ferramentas, independentemente de você usar MCP ou endpoints individuais.

Um desenvolvimento relacionado: llms.txt é um padrão proposto no qual sites publicam um arquivo /llms.txt para orientar modelos de IA em direção a recursos de alto valor. Anthropic, Cloudflare, Docker e Stripe o adotaram. MCP padroniza a invocação de ferramentas; llms.txt padroniza a descoberta de documentação. Ambos tentam tornar a web mais legível para máquinas, por ângulos diferentes.

O que é um endpoint de API no contexto de agentes de IA?

Um endpoint de API é uma URL específica que aceita entrada estruturada e retorna saída estruturada. Para agentes de IA, cada endpoint representa uma capacidade discreta, algo que o agente pode fazer no mundo real. A descrição do endpoint, as definições de parâmetros e as respostas de erro servem como o manual de instruções do agente. Quanto melhor documentado for o endpoint, mais confiavelmente um agente poderá usá-lo.

Diferentemente de desenvolvedores humanos, que podem ler tutoriais e depurar iterativamente, um agente depende do esquema e da descrição do endpoint para fazer uma única chamada correta. É por isso que a documentação de API projetada para consumo por IA importa mais do que nunca. Apenas 24% dos desenvolvedores atualmente projetam APIs pensando em agentes de IA, apesar de 89% usarem IA em seu fluxo de trabalho.

O que é MCP (Model Context Protocol)?

MCP é um protocolo aberto introduzido pela Anthropic que padroniza como agentes de IA se conectam a ferramentas externas e fontes de dados. Pense nele como USB-C para IA. Um único conector que qualquer provedor de ferramentas pode implementar e qualquer agente de IA pode consumir. Um servidor MCP expõe um conjunto de ferramentas (essencialmente endpoints de API) com esquemas padronizados, e um cliente MCP (o agente) pode descobri-las e chamá-las sem código de integração personalizado. Para uma explicação técnica mais aprofundada, consulte nosso post MCP Explained. Para um relato prático de MCP em produção, veja nossa análise dos desafios reais ao construir com o MCP da Shopify.

O espectro de controle no Quickchat AI

Quickchat AI oferece três formas de equipar um AI Agent com ferramentas externas. Elas ficam em um espectro que vai da mais automatizada à mais controlada. Cada abordagem faz uma troca diferente entre velocidade de configuração e precisão de comportamento.

Remote MCP: conectar e usar

Remote MCP é a maneira mais rápida de conectar um AI Agent a funcionalidades externas. Você fornece a URL de um servidor MCP, o Quickchat AI se conecta a ele, descobre todas as ferramentas disponíveis e permite selecionar quais delas seu agente deve usar.

Como configurar:

1. Vá para AI Actions no dashboard do Quickchat AI
2. Clique em “Add Remote MCP”
3. Cole a URL do seu servidor MCP (por exemplo, https://mcp.example.com/sse)
4. Opcionalmente, adicione um token de autenticação ou headers personalizados (os dois são mutuamente exclusivos)
5. Clique em “Connect.” O Quickchat AI descobre todas as ferramentas disponíveis e exibe seus nomes
6. Ative ou desative ferramentas individuais para controlar quais delas seu agente pode usar
7. Configure a flag “default tool is active” para controlar se ferramentas recém-descobertas são ativadas ou desativadas automaticamente

O que acontece por baixo dos panos:

Quando você clica em Connect, o Quickchat AI detecta automaticamente o protocolo de transporte pela URL. Se a URL contiver sse, o transporte SSE será usado; caso contrário, streamable_http será o padrão. Quando você fornece um token de autenticação, ele é enviado como um token Bearer no header Authorization.

A filtragem de ferramentas funciona por meio de um sistema de três níveis. Cada ferramenta do servidor MCP é verificada em relação a dois conjuntos: ferramentas explicitamente ativadas são sempre incluídas, ferramentas explicitamente desativadas são sempre excluídas, e qualquer ferramenta que não esteja em nenhum dos conjuntos recai para a configuração “default tool is active” que você escolheu. Isso significa que, quando um servidor MCP adiciona novas ferramentas, você controla se elas ficam automaticamente disponíveis para seu agente ou se exigem ativação explícita.

Em tempo de execução, quando uma conversa começa, todas as conexões Remote MCP ativas para o agente são carregadas. As ferramentas são buscadas e filtradas conforme a configuração de cada conexão, e a exclusividade dos nomes das ferramentas é verificada em todas as fontes (com um aviso se duplicatas forem encontradas).

A troca: você obtém acesso imediato a tudo que o MCP expõe, mas tem controle limitado sobre descrições de ferramentas, definições de parâmetros ou como o agente decide usá-las. Como descobrimos ao criar um AI Agent com o MCP da Shopify, passar de uma demonstração para produção exige ajustes cuidadosos que a abordagem empacotada do MCP pode dificultar.

Veja também: conecte seu agente a um servidor MCP remoto, How to Launch Your Quickchat AI MCP, considerações de segurança de MCP, documentação do Quickchat AI: canal MCP.

AI Actions (HTTP Request): um endpoint, controle total

Uma AI Action no Quickchat AI é um único endpoint de API HTTP que você configura individualmente para seu AI Agent. Enquanto MCP importa um pacote de ferramentas de uma vez, cada AI Action dá a você controle total sobre uma capacidade específica. Para um exemplo completo, com quatro ações que criam e enriquecem contatos, registram negócios e abrem tickets em um CRM, consulte o tutorial de AI Actions com HubSpot.

Configurando uma AI Action:

1. Name (máx. 64 caracteres): isso se torna o nome da ferramenta que o LLM vê. Ele é normalizado para um identificador válido (por exemplo, “Check Order Status” se torna Check_Order_Status)
2. Description (máx. 1.000 caracteres): este é o campo mais importante. A descrição informa ao LLM quando usar esta ferramenta. Boas descrições especificam em quais circunstâncias conversacionais chamá-la, quais informações coletar do usuário primeiro e como os resultados devem ser comunicados de volta
3. HTTP method: GET, POST, PATCH, DELETE ou PUT
4. URL (máx. 10.000 caracteres): pode conter placeholders {{parameter_name}} para valores dinâmicos
5. Headers: pares chave-valor para autenticação e tipo de conteúdo
6. Body items / Body JSON: corpo da requisição com injeção de parâmetros
7. Query parameters: valores da query string da URL
8. Parameters (máx. 10): cada um com nome, descrição (máx. 500 caracteres), tipo (str, int, float, bool ou custom), uma flag de obrigatório e um valor padrão opcional

Os placeholders {{parameter_name}} são o mecanismo principal. Quando o LLM chama a ferramenta, ele fornece valores para cada parâmetro com base no contexto da conversa. O Quickchat AI então injeta esses valores nos templates de URL, headers, body e query string antes de fazer a requisição HTTP. Também há quatro variáveis integradas que podem ser injetadas dessa forma: scenario_id, conversation_id, conversation_channel e conversation_url.

Uma AI Action configurada para verificar o status de um pedido, mostrando template de URL com placeholder de parâmetro, headers e definições de parâmetros.

Por baixo dos panos: o Quickchat AI cria dinamicamente um esquema tipado a partir das suas definições de parâmetros para cada AI Action. Os cinco tipos compatíveis (str, int, float, bool, custom) são mapeados para seus equivalentes nativos, e esse esquema é usado para validar as entradas do LLM antes de fazer a requisição HTTP.

Um exemplo de AI Action para verificar o status de um pedido:

{
  "name": "check_order_status",
  "description": "Quando o usuário perguntar sobre o status do pedido e tiver fornecido um número de pedido, chame este endpoint para recuperar o status atual. Informe ao usuário o status, a data estimada de entrega e o número de rastreamento (se disponível).",
  "method": "GET",
  "url": "https://api.example.com/orders/{{order_id}}",
  "headers": [
    { "name": "Authorization", "value": "Bearer YOUR_API_KEY" },
    { "name": "Content-Type", "value": "application/json" }
  ],
  "parameters": [
    {
      "name": "order_id",
      "description": "O ID do pedido fornecido pelo usuário (por exemplo, ORD-12345)",
      "type": "str",
      "is_required": true
    }
  ]
}

Testes: o dashboard tem um botão “Test” que permite fornecer valores de parâmetros de exemplo e ver a requisição HTTP real (incluindo um comando curl gerado) e a resposta antes da implantação.

Dicas para escrever descrições eficazes de AI Action:

• Seja específico sobre quando o agente deve chamá-la: “Quando o usuário perguntar sobre o status do pedido e fornecer um número de pedido, chame este endpoint”
• Mencione quais informações coletar primeiro: “Antes de chamar, garanta que você tenha o endereço de e-mail do usuário e o ID do pedido”
• Descreva como lidar com a resposta: “Se o status for ‘shipped’, informe ao usuário o número de rastreamento presente na resposta”
• Para fluxos de trabalho com várias etapas, descreva a sequência no prompt de sistema principal do agente, em vez de descrições de ações individuais, e para transportar um valor entre ações e condicionar a escrita a ele, use Save to memory mais uma run-condition

Um exemplo prático: para uma AI Action passo a passo que registra leads, perguntas sem resposta e solicitações de demo diretamente em uma planilha, veja como conectar um agente de IA ao Google Sheets.

Generate from Text: deixe a IA descobrir

A terceira opção é para usuários que sabem o que querem que o agente faça, mas não sabem qual endpoint de API (ou mesmo qual serviço) usar.

Como funciona:

1. Você digita uma descrição em linguagem natural do que deseja, por exemplo, “Quero que meu AI Agent consiga ligar o Tesla de um usuário quando ele pedir”
2. O Quickchat AI envia isso a um LLM com a ferramenta web_search ativada
3. O modelo pesquisa na web para encontrar a API correta, lê a documentação oficial e gera uma especificação completa de AI Action, incluindo URL, método, headers, parâmetros e requisitos de autenticação
4. O resultado retorna com a configuração completa da ação, citações da documentação usada e uma mensagem explicativa observando pressupostos e lacunas
5. Você revisa, preenche suas credenciais e ativa

Inserindo uma descrição em linguagem natural da capacidade desejada.

A configuração de AI Action gerada, com citações da documentação de API usada.

A geração automatizada de AI Action é estruturada em torno de três prioridades:

• Prioridade 1: entender a intenção. Identificar a capacidade exata que o desenvolvedor deseja e o endpoint de API específico que a fornece
• Prioridade 2: fundamentar na documentação. Usar pesquisa na web para encontrar documentação oficial do fornecedor, não suposições
• Prioridade 3: projetar semântica orientada à conversa. O nome e a descrição gerados devem tratar de quando em uma conversa essa ferramenta é usada, não apenas do que a API faz tecnicamente

O prompt usa duas convenções de placeholder. {{param}} marca parâmetros de runtime que o LLM preenche a partir do contexto da conversa. [[secret_name]] (colchetes duplos) marca constantes do desenvolvedor, como chaves de API e IDs de conta, que devem ser configuradas manualmente antes da ativação. Todo nome de parâmetro deve aparecer como um placeholder {{that_exact_name}} em algum lugar da definição da requisição, e placeholders órfãos não são permitidos.

O sistema usa uma política fail-closed. Se o modelo não conseguir confirmar uma informação crítica na documentação (o método HTTP, a URL, o esquema de autenticação ou a estrutura obrigatória do payload), nenhuma ação será criada. Em vez disso, o sistema retorna uma explicação concisa do que está faltando, em vez de fazer suposições.

É aqui que o ponto filosófico sobre agentes de IA descobrindo APIs se conecta a um recurso concreto de produto. O recurso Generate from Text é literalmente um agente de IA (um LLM com pesquisa na web) criando uma definição de ferramenta para outro agente de IA (o agente Quickchat AI que a usará em conversas).

Um exemplo prático: para o tutorial completo que transforma duas frases digitadas em duas ações ativas e testadas (uma consulta de clima sem chave e uma da NASA com chave, incluindo a recusa fail-closed), veja como conectar seu agente de IA a qualquer API em inglês simples.

Em tempo de execução, todos esses tipos de ferramenta são montados juntos. O Quickchat AI reúne ferramentas de AI Action de requisição HTTP, ferramentas Shopify MCP, ferramentas de base de conhecimento, ferramentas Remote MCP, ferramentas Discord e outras ferramentas personalizadas em uma coleção a ser apresentada ao LLM. O modelo não vê distinção entre elas. Uma ferramenta Remote MCP e uma AI Action configurada manualmente parecem idênticas quando estão na lista de ferramentas.

APIs abertas como o novo SEO

Se agentes de IA vão descobrir e usar APIs de forma autônoma, então ter uma API bem documentada e fácil de usar se torna um ativo de distribuição. A Gartner prevê que mais de 30% do aumento na demanda por APIs virá de agentes de IA até 2026.

Empresas que têm APIs abertas com barreiras mínimas de credenciais podem descobrir que suas APIs se tornam seu melhor canal de aquisição. Em vez de impressões de pesquisa no Google, as “impressões” são agentes de IA escolhendo usar seu serviço em vez do serviço de um concorrente.

A mesma lógica se aplica um nível acima. Um agente de IA que responde a partir da sua documentação pode ele próprio ser exposto como um servidor MCP que ChatGPT, Claude e Cursor chamam como ferramenta, o que torna seu conhecimento, não apenas sua API, descobrível pela web agentiva.

A qualidade da sua documentação de API determina se um agente de IA consegue se integrar a você com sucesso em uma única tentativa. Descrições de parâmetros, mensagens de erro e exemplos de respostas cumprem a mesma função que meta descriptions e dados estruturados no SEO tradicional. Uma resposta de erro confusa ou um campo obrigatório não documentado significa que um agente falhará, e não há um humano do outro lado para depurar.

Empresas cujas APIs não têm documentação ou ficam bloqueadas por requisitos pesados de credenciais podem se tornar invisíveis para a web agentiva, da mesma forma que empresas sem sites se tornaram invisíveis para o Google nos anos 2000.

Uso de computador vs. APIs

Há investimento significativo em ensinar modelos de IA a fazer “uso de computador” (clicar em botões, preencher formulários, navegar por UIs). Anthropic, OpenAI (Operator) e projetos open-source como Browser Use oferecem versões disso.

Mas o uso de navegador é uma solução de contorno para uma API ausente. Uma chamada POST /orders leva milissegundos e retorna dados estruturados. Um agente de navegador navegando por um fluxo de checkout leva minutos e pode quebrar quando um botão se move três pixels para a esquerda. APIs são mais rápidas, mais determinísticas e mais baratas de executar.

O contra-argumento é real: APIs não existem para tudo. Sistemas legados, software empresarial sem superfície de API, dispositivos físicos controlados por GUIs. O uso de computador preenche uma lacuna genuína nesses casos.

A melhor resposta de longo prazo para “não temos uma API para isso” provavelmente é construir a API, em vez de ensinar a IA a usar a GUI. À medida que mais software é escrito por agentes de IA para agentes de IA, o custo de construir e manter APIs cai. O cálculo econômico que tornava mais barato fazer scraping de uma UI do que construir uma API está mudando.

Também há um ângulo de segurança. A “tríade letal” de Simon Willison descreve a combinação perigosa de acesso a dados privados + exposição a conteúdo não confiável + comunicação externa. Isso se aplica a ambas as abordagens, mas ferramentas baseadas em API são mais fáceis de auditar e restringir. Você pode registrar cada chamada de API, validar cada parâmetro e aplicar rate limit a cada endpoint. Fazer o equivalente para um agente de navegador que pode clicar em qualquer coisa é muito mais difícil.

Ferramentas para o mundo físico

Tudo discutido até agora trata de software. O mesmo padrão aparece no mundo físico.

O RT-2 e o Gemini Robotics do Google DeepMind usam a mesma arquitetura, exceto que as ferramentas disparam atuadores em vez de APIs. O framework SPCA (Sense-Plan-Code-Act) formaliza isso para robótica: escanear o ambiente, planejar a abordagem, gerar código executável, executá-lo, observar os resultados.

Não há API para “mova a planta na minha mesa para a direita.” Mas um robô com uma câmera poderia definir move_object(object_id="plant_01", direction="right", distance_cm=15) como uma ferramenta em tempo real e depois chamá-la. A definição da ferramenta serve como a interface entre a camada de raciocínio e a camada de execução física, o mesmo papel que endpoints de API desempenham em software.

A arquitetura LLM + ferramentas + loop é de propósito geral. Hoje, ela é mais fácil de implementar em software, mas a robótica está alcançando.

APIs escritas por IA, para IA

Em cerca de dois anos (2024 a 2026), passamos de a maior parte do código ser escrita por humanos para a maior parte do código ser escrita por IA. Este é um bom momento para reconsiderar o que é um endpoint de API. Cada vez mais, um endpoint é uma declaração de capacidade projetada para ser descoberta e executada por máquinas, não uma interface técnica para desenvolvedores humanos lerem documentação e depois integrarem manualmente.

MCPs são uma camada útil de padronização, mas também são uma camada de curadoria que introduz viés. O criador do MCP decide quais ferramentas expor e como enquadrá-las. Para agentes de IA em produção, esse enquadramento pode não corresponder ao que você realmente precisa. (Escrevemos sobre isso em detalhes ao analisar os desafios com o MCP da Shopify.)

O espectro que percorremos em Quickchat AI Agents reflete um ponto mais amplo. O nível correto de controle depende do seu caso de uso. Remote MCP funciona bem para prototipagem rápida. AI Actions individuais dão controle granular para agentes em produção voltados ao cliente. Generate from Text permite que a IA pesquise a API e crie a definição de ferramenta para você quando ainda está explorando.

E, em todos os níveis, o padrão subjacente é o mesmo. Um LLM, um conjunto de ferramentas, um loop. Sejam as ferramentas comandos bash, endpoints de API, servidores MCP ou atuadores de robôs, são ferramentas em todas as camadas.