Show HN: agents.json – LLM을 위한 OpenAPI 명세 - Insights | Molayo

<p align="center"> <source srcset="./static/logo/agentsjson-white-blackbackground.png"> <img alt="검은 배경에 흰색의 agents.json 로고를 보여줍니다." src="./static/logo/agentsjson-white-blackbackground.png" width="full"> </p> <h1 align="center"> OpenAPI를 LLM 도구로 변환하세요</h1>

The agents.json Spec

API는 LLM이 아닌 개발자를 위해 설계되었습니다. 만약 AI 에이전트(AI agents)를 위한 통합(integrations) 기능을 구축하고 있다면, 각 API마다 상용구 코드(boilerplate)를 작성하고, 시스템 프롬프트(system prompts)를 실험하며, 도구 정의(tool definitions)를 최적화하고, 응답을 벡터 스토어(vector stores)로 파싱해야 합니다.

예를 들어, Gmail API에는 스레드를 검색하고, 스레드 내의 이메일 목록을 나열하며, base64 RFC 822 콘텐츠가 주어진 이메일로 답장을 보내는 엔드포인트(endpoints)가 있습니다. 대신, LLM에는 이 모든 것을 하나의 도구로 처리할 수 있는 명확하고 최상위 수준의 지침(top-level directive)이 필요합니다.

왜 agents.json은 OpenAPI를 기반으로 구축되었는가? — OpenAPI는 API 엔드포인트가 어떻게 작동하고 실행될 수 있는지를 설명하는 표준(gold standard)입니다. 대부분의 API 제공업체는 OpenAPI 명세(specs)를 보유하고 있거나, OpenAPI로 완전히 설명할 수 있는 API를 제공합니다. 이러한 명세만으로는 AI 에이전트 시대에 충분하지 않지만, API 에이전트 통신을 위한 훌륭한 기초를 제공합니다.

그래서 우리는 agents.json을 구현했습니다. 우리는 우리 자신을 위해 이것을 만들었으며, 여러분과 이를 공유하게 되어 기쁩니다.

`agents.json` 파일

agents.json은 AI 에이전트를 위해 설계된 구조화된 계약(structured contracts)의 JSON 스키마(JSON schema)입니다. API 제공업체는 기존의 OpenAPI 명세를 사용하여 이 파일을 구성하며, 에이전트는 정확한 일련의 API 호출을 수행하기 위해 이 파일을 검사합니다.

agents.json 명세는 엔드포인트 발견(endpoint discovery)과 LLM 인자 생성(argument generation)을 최적화하기 위해 OpenAPI 명세에 추가된 일련의 요소들을 포함합니다. 여기에는 설명(descriptions)을 업데이트하거나 예시(examples)를 추가하는 작업이 포함될 수 있습니다.

엔드포인트와 데이터 모델(data models)을 설명하면서 그것들이 어떻게 서로 상호작용하는지를 설명하지 않는 것이 바로 AI 에이전트가 올바른 일련의 동작을 수행하는 데 어려움을 겪는 이유입니다.

이를 해결하기 위해, 우리는 flow(흐름)와 link(연결)를 도입합니다. Flow는 하나의 결과물을 설명하는 1개 이상의 일련의 API 호출로 구성된 계약(contract)입니다. Link는 두 동작이 어떻게 결합되는지를 설명합니다.

우리는 웹 서비스에 접속하는 에이전트들이 쉽게 발견할 수 있도록 /.well-known/agents.json 경로에 파일을 배치할 것을 제안합니다. 현재로서는 사용 가능한 agents.json 파일들을 위한 레지스트리를 운영하고 있습니다.

Wildcard Bridge

Wildcard Bridge는 LLM이 agents.json을 로드, 파싱(parse) 및 실행할 수 있도록 지원합니다. 작동 방식은 다음과 같습니다:

개발자가 자신의 에이전트를 agents.json 파일과 연결합니다.
에이전트가 관련 체인(chain)을 선택하고 주어진 작업에 대한 인자(argument)를 채웁니다.
Bridge가 해당 체인(chain)을 실행합니다.

목표로 하는 사용자 경험은 개발자가 워크플로우에 agents.json 파일을 추가하기만 하면, 통합을 위한 올바른 동작 세트가 실행되는 것입니다. Bridge는 요청에 Basic, ApiKey, Bearer 인증을 추가하는 것을 지원합니다.

설계 원칙 (Design Tenets)

OpenAPI 표준을 기반으로 구축 <br>
가능한 한 기존의 표준과 인프라를 활용합니다.
인간이 아닌 LLM에 최적화된 스키마 (schema) <br>
AI의 소비를 염두에 두고 설계합니다.
무상태성 (Statelessness) 강제 <br>
오케스트레이션(orchestration)은 호출하는 에이전트에 의해 처리됩니다.
기존 API에 대한 최소한의 변경 요구 <br>
도입이 최대한 원활하게 이루어지도록 합니다.

왜 지금인가?

OpenAI의 Operator 출시와 함께, 우리는 AI가 무엇을 자동화할 것인지에 대한 패러다임의 변화를 목격했습니다. AI가 인터넷에서 자유롭게 작동하게 되면, 에이전트를 위한 웹 경험 위에 기능과 가드레일(guardrails)이 모두 구축될 것을 요구하게 될 것입니다. 하지만 대다수의 서비스에서 이는 API가 이미 제공하고 있는 기능이며, 그 이상입니다.

단순히 웹 에이전트 (Web Agents)를 위한 UX를 최적화하는 대신, API를 풍부하게 만드는 것이 더 확장 가능하고 강력하며 안전한 에이전트를 만들어낼 것입니다. API는 확장을 위해 구축된 백엔드 인프라 (Backend Infrastructure)에 의해 지원되기 때문입니다.

여전히 해결해야 할 질문들이 남아 있으며 더 많은 작업이 필요합니다. 지금 논의를 시작하고 반복적으로 구축해 나가는 것은, AI 에이전트 개발의 진화하는 패러다임에 맞춰 우리가 함께 적응할 수 있는 기반을 제공할 것입니다.

FAQ (자주 묻는 질문)

<details> <summary>API 제공자가 직접 자체 에이전트 서버나 "/agent" 엔드포인트 (Endpoint)를 제공해야 하지 않나요?</summary>

제공자들의 공식적인 채택이 이루어지기 전이라도 우리는 즉시 agents.json 파일을 구축하기 시작할 수 있습니다. 추가적인 인프라 변경, 서버, 또는 새로운 엔드포인트가 필요하지 않습니다. 실행의 책임을 클라이언트 (Client)에게 맡김으로써, 이 패러다임은 오늘날 기존 API 기반 애플리케이션의 보안 및 오케스트레이션 (Orchestration) 프로토콜을 그대로 따르게 됩니다. API 제공자들은 여전히 공식적인 agents.json 파일을 유지 관리하는 방식을 선택할 수 있습니다.

</details> <details> <summary>왜 직접 HTTP 요청을 보내는 대신 SDK로 라우팅하나요?</summary>

OpenAPI 명세 (OpenAPI Specs)가 API 사용 방법에 대한 훌륭한 설명을 제공하기는 하지만, OpenAPI generator나 Swagger code-gen과 같은 도구를 사용한 코드 생성 (Code-gen)이 완벽하지는 않습니다. 많은 API에는 원시 HTTP 요청 (Raw HTTP Requests)에는 포함되지 않고 클라이언트 SDK에 반영된 예외 케이스 (Edge Cases)들이 존재합니다. 예를 들어, Gmail의 RFC2822 형식이나 Twilio의 커스텀 TwiML 형식은 LLM이 입력값으로 생성하는 것보다 코드로 파싱 (Parsing)하는 것이 더 적합합니다. 저희는 사용을 위해 레포지토리 (Repo) 내 agents.json 파일 옆에 OpenAPI 명세의 사본을 함께 포함하고 있습니다.

</details> <details> <summary>이것은 Model Context Protocol (MCP)과 어떻게 다른가요?</summary>

MCP는 클라이언트와 서버 간의 지속적인 연결을 통해 컨텍스트(context)와 요청을 교환하는 상태 유지(stateful) 방식으로 설계된 반면, Agents.json은 무상태(stateless) 방식입니다. 여기서는 에이전트(agent)가 모든 컨텍스트를 독립적으로 관리합니다. 기존의 에이전트 아키텍처와 RAG(검색 증강 생성) 시스템을 활용하여 상태를 효과적으로 처리할 수 있습니다. Agents.json을 사용하면 기존의 발행/구독(pub/sub) 아키텍처, 서버리스(server-less) 환경, 그리고 현재 이미 지원되고 있는 인프라 API를 활용하여 구축할 수 있습니다. 또한 정의는 OpenAPI 명세에 의해 강력한 타입(strongly typed)을 가집니다.

</details> <details> <summary>llms.txt는 어떤가요?</summary>

llms.txt는 웹사이트 콘텐츠를 LLM(대규모 언어 모델)이 더 읽기 쉽게 만드는 데 매우 훌륭한 표준이지만, 구조화된 동작을 수행하는(taking structured actions) 과제는 해결하지 못합니다. llms.txt가 LLM의 정보 검색 및 해석을 돕는다면, agents.json은 LLM이 다단계 워크플로(multi-step workflows)를 안정적으로 실행할 수 있게 합니다.

</details> <details> <summary>왜 OpenAPI를 사용하나요?</summary>

OpenAPI는 HTTP API의 변화와 함께 발전해 온 사려 깊은 표준입니다. API 엔드포인트가 어떻게 작동하고 실행될 수 있는지를 설명하는 골드 표준(gold standard)입니다. 대부분의 API 제공업체는 OpenAPI 명세를 가지고 있거나, OpenAPI로 완전히 설명할 수 있는 API를 보유하고 있습니다. 이러한 명세들이 에이전트 시대에 완전히 충분한 것은 아니지만, API와 에이전트 간의 통신을 위한 훌륭한 토대를 제공합니다.

</details>

기능 로드맵 (Feature Roadmap)

기여하기 (Contributions)

agents.json 명세에는 커뮤니티의 의견이 필요합니다. 이 GitHub 리포지토리는 비공식적인 리뷰를 호스팅하여 버전 관리와 공개 토론을 가능하게 할 것입니다. 토론을 원하시면 Discord 커뮤니티에 참여하세요. 이 프로젝트는 계속 진화하고 있으며, 여러분의 피드백 없이는 완성될 수 없습니다.

팀 및 유지 관리자 (Team and Maintainers)

이 프로젝트는 Wildcard AI에 의해 시작되었습니다.

현재 유지 관리자 목록은 MAINTAINERS.md를 참조하세요.

<div align="center"> Made with ❤️ in San Francisco

</div>

Show HN: agents.json – LLM을 위한 OpenAPI 명세

요약

핵심 포인트