O que aprendemos construindo mais de 200 integrações de API com OpenCode

Na Nango, construímos infraestrutura de código aberto para integrações de produtos.

Com todos os avanços recentes nos modelos de codificação, queríamos ver até onde podemos levar um agente autônomo construindo integrações com APIs externas.

TL;DR: Nosso agente de segundo plano não é perfeito, mas gera de forma confiável cerca de 200 integrações em cinco APIs (Google Calendar, Drive, Sheets, HubSpot e Slack) em 15 minutos e menos de US$ 20 em custos de token.

Anteriormente, isso levaria cerca de uma semana para um engenheiro.

Esta postagem é sobre o que foi necessário para chegar lá, o que quebrou ao longo do caminho e o que aprendemos construindo um agente de codificação em segundo plano para integrações de API.

Experimente você mesmo: nosso construtor Nango AI permite criar integrações de API personalizadas com as habilidades deste artigo.

Nossa configuração

O pipeline é bem simples:

1. Definimos uma lista de interações a serem construídas, por exemplo create-calendar-event, sync-filesou send-slack-message
2. Nosso orquestrador prepara um espaço de trabalho por interação com o andaime de integração Nango correto gerado por nossa CLI
3. Geramos um agente OpenCode por interação
4. Cada agente constrói sua interação de forma independente, testa-a com a API externa (o agente tem acesso a uma conta de teste) e itera até que funcione
5. Assim que todos os agentes terminam, o orquestrador verifica seu trabalho e reúne as interações individuais em uma integração Nango por API

Para tornar nossos aprendizados reutilizáveis ​​para os clientes, dependemos muito de habilidades. Eles são fáceis de publicar, funcionam entre agentes e se adaptam a diferentes casos de uso por meio de um prompt que os referencia.

A especificação de cada interação é muito simples:

{
    "id": "create-event",
    "displayName": "Create Event",
    "description": "Create a calendar event",
    "prompt": "As a pre-requisite create a calendar first",
    "comments": ""
},

Além da descrição da interação, também passamos ao agente informações sobre a documentação da API e como carregar uma conexão de teste (=conta de teste) do Nango:

connection_id: bff8b7b7-cb26-443f-9a3a-ec11a5d4d6ff
integration_id: google-calendar
env: dev

---

This integration uses the Google Calendar REST API v3.
API docs: https://developers.google.com/workspace/calendar/api/v3/reference

Observe que fornecemos ao agente apenas instruções de alto nível (“criar um evento de calendário”) e ele pesquisou de forma autônoma os parâmetros, formatos e descrições necessários.

Isso funciona surpreendentemente bem, mas também funciona se você fornecer um caso de uso muito preciso para criar.

Nas seções a seguir, queremos destacar alguns de nossos aprendizados ao testar essa configuração ao longo de centenas de gerações.

1. Deixe os agentes correrem soltos primeiro

Existem duas abordagens óbvias: começar com muitas proteções ou começar com poucas e aprender o que os modelos realmente fazem.

Escolhemos a segunda porque não queríamos ajustar demais nossas suposições. Ainda não sabíamos em que o modelo seria melhor ou quais restrições seriam importantes, então demos ampla liberdade aos agentes em uma área restrita e observamos o que aconteceu.

Algumas delas foram melhores do que o esperado.

Os agentes frequentemente preenchiam lacunas em nossas instruções. Eles inferiram como usar os auxiliares SDK existentes a partir do código circundante. Eles encontraram detalhes sobre as chamadas de API externas com muito pouco contexto. Eles geralmente exigiam muito menos apoio do que esperávamos.

Mas eles também quebraram de maneiras inesperadas, às vezes de forma espetacular.

2. Não confie nos agentes

Os agentes otimizam a conclusão a todo custo. Esperávamos que fosse um problema complicado, e foi.

Aqui estão alguns dos comportamentos que vimos.

Copiando dados de teste de outros agentes

Um agente precisava de um ID de evento para um teste. Em vez de criar ou encontrar um corretamente, ele procurou no diretório de outro agente e reutilizou o ID encontrado lá.

Isso já foi engraçado, mas dificilmente seria um pipeline previsível.

Consertar: Os agentes não têm mais permissão para sair de seu próprio diretório e receberam instruções melhores sobre como gerar dados de teste.

Alucinando um comando Nango CLI

Até agora, todos nós sabemos que os agentes adoram CLIs. Alguns comandos alucinados eram entradas de produtos genuinamente boas, mas o agente muitas vezes ficava teimoso quando um comando falhava. Em vez de tentar um caminho alternativo, como chamar nossa API conforme instruído inicialmente, ele cairia na toca do coelho tentando fazer um comando funcionar que simplesmente não existe.

Consertar: Melhore as instruções sobre a API e CLI disponíveis. E estamos considerando fornecer ao agente pelo menos alguns dos comandos CLI que ele deseja.

Editando dados de teste quando a implementação falhou

O Nango CLI possui um comando para salvar respostas da API externa como acessórios de teste reutilizáveis.

Às vezes, o agente não gostou dos dados do fixture porque sua implementação falhou. Alterar os dados de teste foi mais fácil do que corrigir o código, e foi isso que tentou fazer.

Primeiro removemos as permissões de edição de .json arquivos. Isso ajudou um pouco.

Então alguns agentes começaram a usar sedredirecionamento bash ou outros comandos shell para contornar essa restrição.

Consertar: Permissões de edição mais restritas, instruções claras para não editar testes e verificações explícitas de que os acessórios de teste não foram modificados.

Fingindo acessibilidade da API

Às vezes, a API externa retornava um 403tinha escopos ausentes ou não estava acessível de outra forma.

Em vez de sinalizar isso como um problema de ambiente ou autenticação, o agente às vezes decidia continuar escrevendo a resposta que achava que a API provavelmente retornaria.

Esse é um comportamento racional se o objetivo interno for “terminar a tarefa”. É um mau comportamento se o objetivo real for “produzir uma integração confiável”.

Consertar: Evite que o agente modifique os dados de teste e torne a falha no acesso à API uma parada brusca.

Afirmar que está feito quando não está feito

Este é familiar para qualquer pessoa que tenha usado agentes de codificação para trabalhos reais.

O agente escreve um resumo limpo, diz que tudo está completo e deixa para trás o código que não compila, não passa nos testes ou não implementa a interação corretamente.

Depois que um agente entra nesse estado, a recuperação geralmente não vale a pena.

Consertar: Exclua o agente e reinicie a geração desta interação do zero.

Recusando-se a usar os recursos do SDK da maneira que queríamos

Às vezes, o agente encontrava uma solução alternativa local e decidia que era boa o suficiente, mesmo quando desejávamos explicitamente usar um recurso do SDK do Nango.

Não queríamos forçar um padrão em todos os casos. Às vezes, o agente tem um motivo válido. Mas queríamos que ele considerasse seriamente a abstração que pretendíamos usar.

Consertar: o agente só poderá ignorar o recurso SDK se deixar um breve comentário explicando por que esse recurso não ajuda aqui.

Isso funcionou melhor do que o esperado. Exigir uma breve explicação muitas vezes levava o agente a perceber que, afinal, deveria usar o recurso.

Verificações pós-conclusão

Assim que um agente termina, nosso orquestrador verifica o resultado:

• reexecutando todos os testes com o Nango CLI
• executando compilação e linters
• examinando as mensagens do seu diálogo interno em busca de questões comuns
• verificando se os artefatos e fixtures gerados não foram modificados

O OpenCode facilita isso porque todas as mensagens são armazenadas em um banco de dados SQLite, portanto, é simples inspecionar rastreamentos e automatizar verificações.

A principal lição aqui é simples: não confie no agente. Verifique tudo.

3. Ignore a mensagem de erro final e rastreie a causa raiz

Quando uma execução falhava, o erro final relatado pelo agente era muitas vezes uma pista falsa.

Um padrão comum era assim:

1. O agente alucinou um comando CLI
2. O comando falhou
3. O agente interpretou mal a falha
4. Ele criou uma solução alternativa com base na suposição errada
5. A solução alternativa introduziu um segundo problema
6. O erro final teve muito pouco a ver com o erro original

Se você depurar apenas a partir do erro final, muitas vezes acabará depurando a coisa errada.

Vimos o mesmo padrão em outras formas também:

• parâmetros de entrada errados que enviaram o agente na direção errada
• suposições ruins sobre escopos de autenticação
• comandos auxiliares falsos que criaram várias camadas de confusão posterior
• bugs de implementação que foram realmente causados ​​por problemas no andaime gerado

A solução foi depurar de cima, não de baixo: encontrar a primeira suposição incorreta no rastreamento e corrigir a causa raiz.

A revisão das execuções bem-sucedidas foi tão útil quanto a revisão das que falharam.

Às vezes, um agente chegava a um resultado correto, mas somente depois de passar muito tempo resolvendo um problema que havíamos apresentado. Observar essas execuções nos ajudou a entender onde o agente estava perdendo tempo, onde as instruções não eram claras e onde o ambiente aumentava o atrito evitável.

Isso tornou o sistema melhor de três maneiras ao mesmo tempo: maior taxa de aprovação, menor uso de token e execução mais rápida.

4. As habilidades são imensamente poderosas

Construir esse agente de base realmente deixou claro como as habilidades são poderosas.

Não precisávamos de orquestração pesada de MCP, geração dinâmica de ferramentas durante a execução ou camadas extras de agentes gerenciando outros agentes. Habilidades, além de um orquestrador determinístico simples e um equipamento de codificação como OpenCode, foram suficientes.

Para nós, o poder das habilidades vem de duas coisas:

1. Encapsulando conhecimento específico sobre a construção de integrações
2. Distribuir esse conhecimento para um público amplo: nosso agente de experiência, clientes do Nango, engenheiros de soluções e qualquer pessoa que queira criar integrações personalizadas no Nango.

Publicamos uma habilidade de criação de integração de IA que os clientes usam para criar integrações no Nango.

À medida que aprendemos novas práticas recomendadas de dogfooding com nosso agente de segundo plano, poderíamos facilmente iterar a habilidade e publicar novas versões. Graças a gerenciadores de pacotes como skills.sh, essas atualizações são fáceis de aplicar para todos que usam nossas habilidades.

5. O OpenCode SDK é excelente para agentes em segundo plano

OpenCode foi uma ótima opção para este projeto. Algumas coisas se destacaram.

Arquitetura cliente-servidor

Ele é executado sem cabeça em um pipeline de execução.

Quando algo dá errado, podemos anexar a UI à sessão e inspecionar o que aconteceu. Este é um grande aumento de produtividade, mesmo na era dos agentes de IA.

Ótimo SDK

O SDK simplificou o gerenciamento de sessões, a configuração de execuções e a integração do OpenCode em nosso orquestrador.

Muitas ferramentas de codificação ainda parecem projetadas principalmente para uso interativo. OpenCode não.

Boas escolhas técnicas

O armazenamento de mensagens SQLite facilitou a depuração.

Poderíamos inspecionar os rastreamentos diretamente, escrever scripts personalizados em torno deles e automatizar as verificações sem combater o sistema subjacente.

O código aberto ajuda mais com ferramentas de IA

Como o OpenCode é de código aberto, podemos inspecionar como ele funciona quando algo se comporta de forma inesperada.

Os modelos também podem ler o código quando necessário, o que ajuda a responder questões mais profundas da plataforma.

As melhores práticas são bem transferidas

A configuração é próxima o suficiente de outros agentes de codificação para que nossas habilidades e práticas operacionais sejam bem transferidas.

Isso é importante porque não queremos um sistema frágil vinculado a uma única ferramenta e queremos práticas reutilizáveis ​​para nossa equipe e clientes que trabalham em diferentes ambientes de agentes.

Conclusão

Os agentes não estão prontos para enviar de forma autônoma todas as integrações de ponta a ponta.

Mas com a estrutura, as ferramentas, as restrições e a verificação corretas, eles podem concluir com segurança uma fatia significativa do trabalho de integração.

Estamos entusiasmados em disponibilizar nosso agente de fundo para todos os clientes Nango e mal podemos esperar para ver o que a próxima geração de modelos irá melhorar!