Show HN: Open Envelope – an open schema for defining AI agent teams | AI Paper Digest

TL;DR Highlight

여러 AI 에이전트가 팀처럼 협업하는 구조를 벤더 중립적인 오픈 스키마로 선언적으로 정의할 수 있게 해주는 프로젝트로, 멀티 에이전트 오케스트레이션의 표준화를 시도한다.

Who Should Read

LLM 기반 멀티 에이전트 시스템을 설계하거나 여러 AI 도구를 팀 단위로 조율하려는 백엔드/풀스택 개발자. 특정 벤더에 종속되지 않는 에이전트 워크플로우 아키텍처를 고민 중인 사람에게 특히 유용하다.

Core Mechanics

Open Envelope는 AI 에이전트 팀의 구성, 역할, 권한, 트리거 조건 등을 JSON/YAML 스키마로 선언적으로 표현할 수 있게 해주는 오픈 스펙이다. 특정 LLM 벤더나 런타임에 종속되지 않는 것이 핵심 목표다.
스키마에는 `reportsTo` 필드가 있어 에이전트 간 위계 구조(상위 오케스트레이터에게 위임하거나 하위 에이전트에게 작업을 넘기는 구조)를 바텀업 방식으로 표현할 수 있다.
`workspaces` 개념을 통해 에이전트별로 접근할 수 있는 데이터 범위를 정의할 수 있다. 현재 일부 구현체는 하나의 공유 데이터 풀에 서브에이전트별 구독을 두는 방식을 쓰는데, 이 방식은 암묵적으로 처리돼야 할 입력 요건까지 명시적으로 추가해야 하는 단점이 있다.
`accessPolicy` 필드로 에이전트별 접근 권한을 정의할 수 있지만, 커뮤니티에서는 이 방식이 위험할 수 있다고 지적했다. 접근 범위는 에이전트가 아니라 도구(tool) 자체에 정의되어야 하며, 에이전트는 어떤 도구를 쓸 수 있는지만 알면 된다는 의견이 있다.
human approval(사람이 승인해야 진행되는 게이트) 기능이 내장되어 있고, `GateTypes`로 흐름 제어를 할 수 있다. 다만 이미 input requirement로 표현 가능한 내용을 별도 타입으로 중복 정의한 것 아니냐는 비판도 있다.
트리거 조건으로 `any_approved | all_approved` 같은 논리 연산을 지원하지만, XOR(둘 중 정확히 하나만 참) 같은 복잡한 조건을 표현하기엔 부족하다. 플랜 기반 실행으로 확장될 경우 TriggerRequirements를 재귀적으로 중첩할 수 있도록 v2에서 분리가 필요할 것으로 보인다.
Claude Code는 자체 동적 워크플로우(https://code.claude.com/docs/en/workflows)를 통해 이 문제를 직접 해결하려는 방향으로 가고 있어, Open Envelope는 그에 대한 벤더 중립적 대안으로 포지셔닝된다.

Evidence

선언적 스키마만으로는 한계가 있다는 의견이 있었다. CDK나 Pulumi처럼 코드로 작성하고 런타임에 선언적 설정으로 컴파일되는 방식이 테스트 가능성과 타입 안정성 측면에서 더 낫다는 주장이었으며, Terraform 호환이 필요 없다면 명령형 접근이 우선이라는 실무 경험이 공유됐다.
`accessPolicy`를 에이전트 레벨에서 정의하는 것은 footgun(스스로 발등을 찍는 설계)이라는 강한 비판이 있었다. 접근 범위는 도구 정의 시점에 결정돼야 하고, 에이전트는 단순히 '사용 가능한 도구 목록'만 받아야 한다는 의견이었다.
스키마가 상세하게 공개되어 있어 AI를 활용한 리버스 엔지니어링이 쉬워졌다는 점을 지적하며, 직접 VPS에서 자체 런타임을 구축하는 것 대비 유료 호스팅을 써야 할 이유가 무엇인지 묻는 댓글이 있었다. 오픈 스키마의 투명성이 오히려 유료 서비스의 차별화를 약화시킨다는 논점이다.
규칙(upstream rules)은 특정 에이전트 구현체가 아닌 저장소(repository)와 함께 관리되어야 한다는 의견이 있었다. 모델을 자유롭게 교체하거나 실험할 수 있어야 하며, 특정 벤더에 종속된 스노우플레이크 구현체에 묶이면 안 된다는 실용적인 주장이었다.
보이스(voice) 인터페이스처럼 QoS(서비스 품질) 제어가 중요한 환경에서는 '최대 한 번만 실행(at-most-once invocation)' 같은 도구 실행 제약 기능이 필요한데, 현재 스키마의 tool 정의에는 이런 세부 제어 옵션이 없다는 경험이 공유됐다.

How to Apply

여러 AI 에이전트(예: 리서치 에이전트, 코드 리뷰 에이전트, 배포 에이전트)를 조합한 파이프라인을 설계할 때, Open Envelope 스키마로 각 에이전트의 역할, 트리거 조건, 데이터 접근 범위를 선언적으로 문서화하면 팀 간 협업 시 공통 언어로 활용할 수 있다.
Claude Code, LangGraph, AutoGen 등 특정 프레임워크에 에이전트 설정이 묶여 있는 경우, Open Envelope 스키마를 중간 표준으로 두고 각 런타임에서 이를 읽어 실행하는 어댑터 레이어를 만들면 벤더 전환 비용을 줄일 수 있다.
에이전트 실행 흐름에 human-in-the-loop(사람이 중간에 개입해 승인하는 구조)가 필요한 서비스를 만들 때, `GateTypes`와 human approval 필드를 활용해 어느 단계에서 승인이 필요한지를 코드가 아닌 설정으로 관리할 수 있다. 단, 입력 요건(input requirement)으로도 동일하게 표현 가능한지 검토하고 중복 정의를 피하는 것이 좋다.
접근 권한 설계 시, 에이전트 레벨의 `accessPolicy`보다 각 도구(tool) 정의 안에 접근 범위를 포함시키는 방향으로 스키마를 커스터마이징하면, 에이전트가 교체되거나 재조합될 때도 권한이 일관되게 유지된다.

Terminology

오케스트레이터(orchestrator)여러 AI 에이전트에게 작업을 나눠주고 결과를 취합하는 상위 조율자 에이전트. 마치 팀장이 팀원에게 업무를 분배하는 역할이다.

선언적(declarative) 스키마'어떻게'가 아니라 '무엇을' 원하는지를 기술하는 방식. YAML이나 JSON으로 최종 상태를 정의하면 런타임이 알아서 실행하는 구조다.

GateType에이전트 워크플로우에서 특정 조건이 충족될 때까지 흐름을 멈추는 검문소 역할. 사람의 승인이나 외부 이벤트를 기다릴 때 사용한다.

at-most-once invocation동일한 작업이 네트워크 오류 등으로 재시도될 때도 딱 한 번만 실행되도록 보장하는 실행 의미론. 결제나 이메일 발송처럼 중복 실행이 치명적인 경우에 필요하다.

footgun개발자 커뮤니티에서 쓰는 은어로, 겉보기엔 편리해 보이지만 잘못 쓰면 스스로 큰 버그나 사고를 유발하는 설계를 말한다.

human-in-the-loopAI가 자동으로 처리하다가 특정 시점에 사람이 개입해 검토하거나 승인해야 다음 단계로 진행되는 워크플로우 패턴.

Show HN: Open Envelope – an open schema for defining AI agent teams