Agents.json - A especificação OpenAI para LLMs

• Uma especificação aberta baseada no padrão OpenAPI que define um contrato claro entre LLMs e APIs
  • Organiza chamadas de API como ferramentas orientadas a objetivos para que os LLMs possam usá-las com facilidade
• Só com a documentação OpenAPI existente, os LLMs tinham dificuldade para selecionar e chamar a API adequada
  • O agents.json permite manter o processo de chamada de API determinístico, ao mesmo tempo em que possibilita que o resultado que o LLM busca alcançar seja executado de forma não determinística

Por que isso é necessário?

• Para usar LLMs, muitas vezes é preciso implementar manualmente a forma de integração com APIs
• Muitos desenvolvedores acabam abrindo mão do comportamento não determinístico dos agentes e tentam obter o resultado desejado por meio de workflows codificados manualmente
• Com agents.json, o LLM pode operar de forma não determinística no processo de alcançar o resultado desejado, enquanto a chamada de API em si pode ser executada de forma determinística
• As APIs existentes foram projetadas com foco em desenvolvedores, o que dificulta seu uso direto por LLMs
• Exemplo da API do Gmail:
  • É necessário pesquisar emails, obter a lista de emails de uma thread e responder a um email específico
  • Quando o LLM consultava a documentação OpenAPI diretamente, muitas vezes falhava em escolher a chamada de API adequada
  • Com agents.json, é possível pré-definir as chamadas de API para executá-las na ordem correta

Componentes do agents.json

• Arquivo agents.json
  • Serve para conectar chamadas de API entre si e definir ferramentas orientadas a resultados
  • É usado em conjunto com o arquivo OpenAPI existente
• SDK do agents.json
  • Permite que o LLM carregue ferramentas com base no agents.json e execute uma série de chamadas de API

Diferenças em relação ao OpenAPI tradicional

• Usando apenas OpenAPI, muitas vezes o LLM não consegue selecionar corretamente as chamadas de API
• Com agents.json, é possível transformar o processo de chamadas de API em templates, oferecendo o fluxo ideal de chamadas para alcançar o resultado desejado

Motivo de ter sido lançado como open source

• No início, era um arquivo de configuração usado internamente, mas conforme os recursos foram sendo ampliados, decidiu-se publicá-lo como open source
• Dharmesh, CTO da HubSpot, propôs o conceito de uma especificação de tradução de APIs para LLMs, e isso inspirou sua publicação
• Atualmente, já existem 10 integrações de API validadas, e novas APIs estão sendo adicionadas diariamente
• Para facilitar a expansão pelos desenvolvedores, também é oferecida gratuitamente uma plataforma de busca de ferramentas e coleções personalizadas (https://wild-card.ai)

[GN⁺]

Opiniões do Hacker News

• Estou de olho no agents.json e espero que esse protocolo dê certo

  • Acho que MCP e agents.json podem coexistir
  • O MCP cobre mais coisas, e pode ser difícil criar um protocolo simplificado

• Para que o agents.json seja adotado no início, a documentação precisa ser mais fácil de entender

  • Os exemplos precisam estar visíveis de imediato, e o schema deve estar por perto
  • O pitch precisa ser conciso, e os campos do schema também precisam ser claros
  • Talvez seja necessária uma ferramenta que cole um schema OpenAPI e gere um rascunho de agents.json com ajuda de um LLM

• A compatibilidade entre OpenAPI e agents.json é boa, mas pode ser excessiva

  • OpenAPI é popular, mas não dominou totalmente o mercado
  • Se isso adicionar complexidade ao agents.json, fica a dúvida se vale a pena dar suporte
  • Mesmo sem compatibilidade de 100%, pode ser possível oferecer suporte parcial com conversores personalizados

• Muita gente já usa IDEs agentic, e seria bom se o agents.json compartilhasse snippets explicando como usar, como encontrar documentação e como pesquisar no registro

• Pergunta sobre as diferenças entre agents.json e a especificação OpenAPI Arazzo

  • Dúvida se ela é mais adequada para uso com LLMs
  • Pelos exemplos, parecem existir conceitos semelhantes

• Opinião de que é difícil ver arquivos agents.json reais

  • Mesmo procurando por 10 minutos no registro, não foi possível encontrar um exemplo

• Pergunta sobre a licença do pacote Python

  • Dúvida se é AGPL

• A ideia é boa, mas a questão da licença pode dificultar a adoção

  • Espera-se que a equipe explique como times podem adotar um pacote AGPL em seus produtos

• Pode ficar mais simples, e isso seria algo bom

  • Pode ter sido encontrado um bug no título da propriedade de informação da especificação

• Comparação entre agents.json e llms.txt

  • O llms.txt também está surgindo como um padrão para ajudar LLMs a entender APIs
  • O agents.json parece melhor para fornecer uma compreensão estruturada de diferentes endpoints

• Pergunta sobre por que agents não conseguiriam usar APIs documentadas com especificações OpenAPI

  • Em testes pessoais, funcionou bem, então deve haver algo que passou despercebido

• Espera-se que agents.json e arquivos LLM.txt se tornem padrões simples como o robot.txt

  • CrewAI, Letta/MemGPT e OpenHands/OpenDevin são relacionados, mas nada ultrapassa fronteiras
  • MCP é a abordagem mais flexível, e seria bom se combinasse bem com agents.json
  • A equipe da Netlify está pensando em algo interessante sobre Agent Experience (AX), e as equipes da Anthropic e wildcard deveriam prestar atenção

• Pergunta sobre semelhanças/diferenças em relação ao MCP

  • Parece interessante